Autenticação e idempotência

Contrato de autenticação, escopos e garantias de execução única em APIs Beacon.

reference • updated 2026-03-15

Headers base

Header	Obrigatório	Descrição
`Authorization: Bearer <access_token>`	Sim	Token de acesso ao contexto da organização
`Content-Type: application/json`	Sim (POST/PATCH)	Formato do payload
`Idempotency-Key`	Recomendado	Chave de deduplicação para operações mutáveis

Regras de idempotência

A mesma Idempotency-Key + mesmo endpoint + mesma organização deve produzir o mesmo resultado lógico.
Chaves diferentes para operações distintas, mesmo com payload semelhante.
Persistência de chaves por janela temporal definida pela equipa de operação.

Erros típicos

Código	Significado	Ação
`401`	token inválido ou ausente	renovar credencial e repetir
`403`	scope insuficiente	rever permissões da organização
`409`	conflito idempotente	validar se já existe operação concluída
`429`	throttling	aplicar retry com backoff

Exemplo de pedido seguro

bash

curl -X POST https://api.beacon.pt/v1/billing/subscription-checkouts \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: org-acme-20260315-0001" \
  -d '{"plan":"plus","billing":"monthly"}'