Billing API

Endpoints críticos para criação de checkout, confirmação de subscrição e portal de gestão.

reference • updated 2026-03-15

Objetivo

Operar o ciclo completo de faturação recorrente: iniciar checkout, confirmar estado pós-pagamento e abrir portal self-service sem perder rastreabilidade por organização.

Endpoints e contrato operativo

Endpoint	Quando usar	Requisitos-chave
`POST /v1/billing/subscription-checkouts`	iniciar subscrição ou upgrade	token Bearer, plano válido, `Idempotency-Key`
`POST /v1/billing/subscriptions/{subscription_id}/confirm`	reconciliar estado após retorno do checkout	`subscription_id` existente, contexto de organização
`POST /v1/billing/customer-portal/sessions`	abrir gestão self-service de plano/método	cliente associado à organização e modo correto

Fluxo recomendado

11) Criar checkout
Gera sessão com plano, ciclo e contexto de organização. Guarda o checkoutSessionId para rastreio.
22) Redirecionar utilizador
Envia o utilizador para checkoutUrl e bloqueia duplicação de submit no frontend.
33) Confirmar resultado
Após callback/retorno, chama .../confirm para fechar o estado de forma determinística.
44) Expor portal
Disponibiliza customer-portal/sessions apenas a perfis autorizados.

Exemplo de criação de checkout

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: chk_<operation_id>" \
  -d '{
    "organizationId": "<organization_id>",
    "plan": "plus",
    "billingCycle": "monthly",
    "mode": "test"
  }'

json

{
  "checkoutSessionId": "cs_123",
  "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_123",
  "expiresAt": "2026-03-15T10:30:00Z"
}

Idempotência, retries e consistência

Reutiliza a mesma Idempotency-Key quando repetes a mesma operação lógica.
Define timeout de cliente com retry exponencial e jitter para erros transitórios (429, 5xx).
Não assumes sucesso apenas com redirect concluído; o estado final deve ser confirmado por endpoint e eventos.

Erros frequentes

Código	Causa típica	Ação recomendada
`401`	token inválido ou expirado	renovar credencial e repetir com novo token
`403`	scope insuficiente	rever permissões do token para billing
`409`	conflito idempotente	reutilizar resultado original, sem nova operação
`422`	payload inconsistente	corrigir plano/ciclo/organização e revalidar

Checklist de go-live

Fluxo testado em mode=test com sucesso e sem estados pendentes.
Alertas ativos para falhas de confirmação e aumento de retries.
Portal restrito por perfil e com auditoria de acesso.