Fundamentos da API
Referência base para hosts, autenticação, contexto e erros públicos.
reference • updated 2026-03-17
Convenções HTTP
| Tema | Regra |
|---|---|
| Base host | https://app.beacon.pt/api (live) e https://test.beacon.pt/api (test) |
| Auth | Authorization: Bearer <beacon_session_token> |
| Contexto organizacional | org=<organization_slug> nas rotas por organização |
| Modo | `mode=test |
| Content-Type | application/json nas rotas JSON |
| Webhooks Stripe | Stripe-Signature obrigatório nas rotas de ingressão Stripe |
Estrutura de erro
Erros devem devolver payload consistente com:
ok: false: falha explícita.error: resumo legível para troubleshooting.code: identificador estável da categoria de erro.nextAction: passo seguinte recomendado quando existe remediação guiada.fieldErrors: lista opcional de erros por campo em validações.
Códigos frequentes
| Código | Significado | Ação recomendada |
|---|---|---|
400 | payload ou query inválidos | corrigir org, mode ou body e repetir |
401 | token Bearer ausente ou inválido | renovar sessão Beacon e repetir |
403 | utilizador sem papel elegível | rever membership OWNER/ADMIN na organização |
409 | estado actual impede a operação | confirmar se já existe checkout pendente, subscrição activa ou bloqueio operacional |
422 | validação semântica devolvida pelo domínio | corrigir dados funcionais antes de repetir |