Quickstart
Em 3 passos você faz a primeira chamada e recebe o primeiro webhook.
1. Gere uma API key
No painel, Configurações → API keys, dê um nome e clique em Gerar. Copie a chave bk_... na hora: ela é
mostrada uma única vez. Escolha o escopo: read (leitura) ou write (leitura + ações).
2. Faça uma chamada
Consultar as capacidades de um cliente (leitura, escopo read basta):
curl "https://api.ribbo.app/v1/entitlements?external_id=cliente-123" \
-H "Authorization: Bearer bk_sua_chave"
Resposta:
{
"customer_id": "cus_01J…",
"subscriptions": [
{ "id": "sub_01J…", "status": "active", "plan_id": "plan_01J…",
"interval": "month", "current_period_end": "2026-09-01T00:00:00Z",
"entitlements": { "seats": 5, "api": true } }
],
"merged_entitlements": { "seats": 5, "api": true }
}
Cliente que ainda não existe na ribbo devolve 200 com
customer_id: null, nunca 404.
3. Receba um webhook
Cadastre a URL do seu endpoint no painel (Configurações → Webhooks), escolha os eventos e
valide a assinatura de cada POST. A cada fatura paga, troca de plano, suspensão
etc., a ribbo envia um POST assinado para você.