Uwata Developers

Como funciona

A API Uwata usa API Keys para autenticar pedidos de sistemas externos. Cada chave é associada a uma empresa específica e tem um conjunto de permissões (scopes) que define o que pode fazer.

As chaves são geradas no Dashboard em Programadores. O token é gerado com 32 bytes aleatórios e armazenado apenas como hash SHA-256 — nunca em texto simples na base de dados.

Modos: LIVE vs TEST

Cada chave tem um modo que determina se opera sobre dados reais ou de teste.

Modos disponíveis

Nome	Tipo	Obrig.	Descrição
`LIVE`	`mode`	não	Opera sobre dados reais da empresa. Prefixo sk_live_. Usar em produção.
`TEST`	`mode`	não	Opera sobre dados de teste. Prefixo sk_test_. Usar em desenvolvimento.

Scopes disponíveis

Ao criar uma chave, selecciona apenas os scopes necessários para o teu caso de uso (princípio do menor privilégio).

Scopes

Nome	Tipo	Obrig.	Descrição
`invoices:read`	`scope`	não	Listar e consultar facturas da empresa.
`clients:read`	`scope`	não	Listar e consultar clientes.
`clients:write`	`scope`	não	Criar novos clientes via API.

Criar uma API Key

As chaves são criadas no Dashboard. Após a criação, o token completo é mostrado uma única vez. Guarda-o imediatamente.

Criar API Key

// POST /api/v1/developer/api-keys
// Autenticado com Firebase JWT (sessão do Dashboard)

{
  "name": "ERP Interno",
  "mode": "LIVE",
  "scopes": ["invoices:read", "clients:read", "clients:write"]
}

Usar a chave nos pedidos

Inclui a chave no cabeçalho Authorization como Bearer token, e o ID da empresa no cabeçalho X-Company-Id.

Autenticar pedidos

curl https://api.uwata.app/api/v1/v1/invoices \
  -H "Authorization: Bearer sk_live_a1b2c3d4e5f6..." \
  -H "X-Company-Id: clx1234companyid"

Boas práticas de segurança

Nunca incluas tokens directamente no código fonte ou em repositórios Git.
Usa variáveis de ambiente (process.env, os.environ) ou um gestor de segredos.
Cria chaves separadas para cada ambiente (desenvolvimento, staging, produção).
Revoga imediatamente qualquer chave que possa ter sido comprometida.
Usa o modo TEST durante o desenvolvimento para evitar efeitos em dados reais.
Limita os scopes ao mínimo necessário para cada integração.

Revogar uma chave

No Dashboard em Programadores, clica no ícone de lixo ao lado da chave que pretendes revogar. A revogação é imediata — todos os pedidos subsequentes com essa chave receberão um erro 401 Unauthorized.

Podes ter até 10 chaves activas por empresa em simultâneo.

Autenticação