Fundamentos de la API
Referencia base de hosts, autenticación, alcance y errores públicos.
reference • updated 2026-03-17
Convenciones HTTP
| Tema | Regla |
|---|---|
| Host base | https://app.beacon.pt/api (live) y https://test.beacon.pt/api (test) |
| Auth | Authorization: Bearer <beacon_session_token> |
| Alcance de organización | org=<organization_slug> en rutas por organización |
| Modo | `mode=test |
| Content-Type | application/json en rutas JSON |
| Webhooks Stripe | Stripe-Signature obligatorio en /api/webhooks/stripe* |
Estructura de error
Los errores deben devolver un payload consistente con:
ok: false: fallo explícito.error: resumen legible para troubleshooting.code: identificador estable de categoría.nextAction: siguiente paso recomendado cuando el dominio lo ofrece.fieldErrors: lista opcional de errores por campo.
Códigos comunes
| Código | Significado | Acción recomendada |
|---|---|---|
400 | payload o query inválidos | corregir org, mode o body y reintentar |
401 | bearer token ausente o inválido | renovar la sesión Beacon y reintentar |
403 | el usuario no es elegible para la acción | revisar membresía OWNER/ADMIN en la organización |
409 | el estado actual del dominio bloquea la operación | inspeccionar checkout pendiente, suscripción activa o bloqueo operativo |
422 | validación semántica de dominio fallida | corregir el input funcional antes de repetir |