Autenticación e idempotencia

Contrato de autenticación, scopes y garantías de ejecución única en APIs Beacon.

reference • updated 2026-03-15

Headers base

Header	Obligatorio	Descripción
`Authorization: Bearer <access_token>`	Sí	Token de acceso al contexto de organización
`Content-Type: application/json`	Sí (POST/PATCH)	Formato del payload
`Idempotency-Key`	Recomendado	Clave de deduplicación para operaciones mutables

Reglas de idempotencia

Mismo Idempotency-Key + mismo endpoint + misma organización debe producir el mismo resultado lógico.
Usa claves diferentes para operaciones distintas, aunque el payload sea parecido.
Persiste claves durante una ventana temporal definida por tu política operacional.

Errores típicos

Código	Significado	Acción
`401`	token inválido o ausente	renovar credenciales y reintentar
`403`	scope insuficiente	revisar permisos de organización
`409`	conflicto idempotente	validar si la operación ya se completó
`429`	throttling	aplicar retry con backoff

Ejemplo de petición segura

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"}'