# ribbo API

> Cobrança recorrente para quem constrói SaaS. Leia e gerencie assinaturas (que nascem no checkout da ribbo), consulte as capacidades (entitlements) de cada cliente, processe estornos, gere links de pagamento e receba webhooks assinados. A recorrência é gerida pela ribbo: você nunca fala com o gateway.

Autenticação: `Authorization: Bearer bk_...` (API key do tenant). Dinheiro em centavos (inteiro). IDs com prefixo (sub_, cus_, inv_, plan_, offer_...); plano por `plan_id` e oferta por `offer_id`. Paginação por cursor. Erros em `{"error":"..."}`. Não há endpoint de criar assinatura. Servidor MCP: pacote `ribbo-mcp` no npm.

## Começar
- [Visão geral](https://dash.ribbo.app/docs): O que é a ribbo, do que a API é capaz e os gateways.
- [Quickstart](https://dash.ribbo.app/docs/quickstart): Primeira chamada e primeiro webhook em 3 passos.
- [Autenticação](https://dash.ribbo.app/docs/authentication): Bearer bk_, escopos read/write, erros.
- [Convenções](https://dash.ribbo.app/docs/conventions): Centavos, IDs (plan_id, offer_id), paginação, datas, erros, idempotência.

## Recursos
- [Assinaturas](https://dash.ribbo.app/docs/subscriptions): Listar, ler, estados, trial e régua de cobrança.
- [Troca de plano](https://dash.ribbo.app/docs/change-plan): Upgrade imediato, downgrade agendado, cancelar troca.
- [Ações de cobrança](https://dash.ribbo.app/docs/billing-actions): Estorno, cancelar e desfazer, cobrar agora, reagendar, remover cupom.
- [Links de pagamento](https://dash.ribbo.app/docs/payment-links): Fatura em aberto, 2ª via do Pix, renovação e troca de forma de pagamento.
- [Clientes](https://dash.ribbo.app/docs/customers): Atualizar dados (celular E.164), histórico de pagamentos.
- [Entitlements](https://dash.ribbo.app/docs/entitlements): Consultar capacidades e a regra de ouro.
- [Indicações e campanhas](https://dash.ribbo.app/docs/referrals-campaigns): Link de indicação e links de campanha de renovação.
- [Webhooks](https://dash.ribbo.app/docs/webhooks): 19 eventos, envelope, campos, validação HMAC, retries.
- [Servidor MCP](https://dash.ribbo.app/docs/mcp): Instalar o ribbo-mcp no Claude Code, Cursor, VS Code ou Claude Desktop.
- [Testes e sandbox](https://dash.ribbo.app/docs/sandbox): Como testar com segurança e artefatos p/ IA.

## Contrato (legível por máquina)
- [OpenAPI 3.1](https://dash.ribbo.app/openapi.json): todos os endpoints, schemas e webhooks.
- [Documentação completa](https://dash.ribbo.app/llms-full.txt): todos os guias + endpoints em um arquivo.
- [Referência interativa](https://dash.ribbo.app/docs/reference)