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

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