Autenticação

Todas as chamadas à API requerem autenticação via API Key.

Obter uma API Key

Regista-te no Portal do Cliente
Após aprovação do administrador, acede ao painel
Navega para API Keys e clica em Nova API Key
A chave é mostrada apenas uma vez, guarda-a imediatamente
O formato é feak_ seguido de 64 caracteres hexadecimais

Exemplo:

feak_8738a27cee79a85c02fa5c96fc1bf1a2d31d856c98b0bf1a344be9f013f5ea67

Usar a API Key

Inclui a chave em todos os requests à API. Escolhe um destes métodos:

Header `x-api-key` (recomendado)

x-api-key: feak_8738a27cee79a85c02fa5c96fc1bf1a2d31d856c98b0bf1a344be9f013f5ea67

Header `Authorization: Bearer`

Authorization: Bearer feak_8738a27cee79a85c02fa5c96fc1bf1a2d31d856c98b0bf1a344be9f013f5ea67

Exemplo de Chamada

curl -X POST https://connect.factflexi.com/v2/series 
  -H "Content-Type: application/json" 
  -H "x-api-key: feak_8738a27cee79a85c02fa5c96fc1bf1a2d31d856c98b0bf1a344be9f013f5ea67" 
  -d '{"nif":"5000537039","privateKey":"-----BEGIN PRIVATE KEY-----\n..."}'

Respostas de Erro de Autenticação

HTTP	Resposta	Causa
401	`{ "success": false, "error": "Nao autorizado.", "code": "UNAUTHORIZED" }`	API Key não foi enviada
401	`{ "success": false, "error": "API Key invalida.", "code": "UNAUTHORIZED" }`	API Key não existe ou foi revogada
403	`{ "success": false, "error": "Scope insuficiente.", "code": "FORBIDDEN" }`	A key não tem permissão para este endpoint
429	`{ "success": false, "error": "Demasiados pedidos. Tente novamente mais tarde.", "code": "RATE_LIMITED" }`	Limite de pedidos excedido

Rate Limiting

Cada API Key tem um limite de pedidos por minuto (por defeito: 60/minuto, configurável na criação da key). Pedidos sem key válida também são limitados por IP.

Quando o limite é excedido, a resposta vem com HTTP 429 e o header Retry-After (segundos a aguardar):

HTTP/1.1 429 Too Many Requests
Retry-After: 42

Boa prática: implementar backoff exponencial no teu sistema — ao receber 429, aguarda o Retry-After indicado em vez de insistir imediatamente.

Scopes (Permissões)

Cada API Key tem scopes que definem o que pode fazer:

Scope	Permite
`facturas:emitir`	Emitir documentos e solicitar séries
`facturas:consultar`	Consultar estado de documentos
`series:listar`	Listar séries de numeração
`*`	Acesso total a todos os endpoints

Segurança

A chave é mostrada apenas uma vez no momento da criação
Se perderes a chave, usa a opção Rodar para gerar uma nova
A chave anterior é revogada automaticamente ao rodar
As chaves são armazenadas com hash SHA-256, impossível recuperar
Guarda a chave num gestor de segredos (ex: variáveis de ambiente, Vault)

Boas Práticas

Nunca exponhas a API Key no frontend, usa-a apenas no backend do teu sistema
Usa uma key por ambiente, cria keys separadas para testes e produção
Roda as chaves periodicamente, recomendado a cada 90 dias
Trata erros 401, faz logout/notifica o administrador se a key for revogada
Não comites a key no Git, usa .env ou gestor de segredos