Integração com a ribbo
A ribbo é a plataforma de cobrança recorrente para assinaturas de qualquer tipo. Com esta API o seu sistema (app, site, backend) lê e gerencia assinaturas, consulta as capacidades (entitlements) de cada cliente, processa estornos, gera links de pagamento e recebe webhooks assinados a cada evento de cobrança.
A recorrência é gerida pela ribbo: o seu sistema nunca fala com o gateway de pagamento, nunca vê número de cartão e não precisa agendar cobranças. Você declara o que o cliente tem direito; a ribbo cuida de cobrar e te avisa o que aconteceu.
A assinatura nasce no checkout da ribbo. Não existe endpoint para criar assinatura: o cliente assina pela página de checkout e a API serve para ler e operar as assinaturas que já existem.
Do que a API é capaz
| Área | Você consegue |
|---|---|
| Assinaturas | listar, ler o estado atual, cancelar (na hora ou no fim do período) e desfazer o cancelamento agendado |
| Planos | trocar de plano (upgrade imediato com proração, downgrade agendado), cancelar troca agendada |
| Cobrança | cobrar agora (cartão salvo), reagendar a próxima cobrança, estornar (total ou parcial) |
| Links | link de pagamento da fatura aberta, 2ª via do Pix de um pedido, link de renovação antecipada, link de troca de forma de pagamento |
| Clientes | atualizar e-mail, nome e telefone, listar assinaturas e histórico de pagamentos |
| Entitlements | consultar as capacidades vivas de um cliente (o que liberar no seu SaaS) |
| Indicações | obter link/código de indicação e progresso das recompensas |
| Campanhas | gerar e listar links de renovação de uma campanha |
| Webhooks | receber 19 tipos de evento assinados (assinatura, fatura, pedido, pagamento, indicação) |
| IA | servidor MCP para o seu assistente consultar e operar a cobrança (guia) |
Gateways
A cobrança roda na conta de gateway do próprio vendedor. O seu sistema não precisa saber qual é:
o campo gateway_provider do pagamento informa, se você quiser.
| Gateway | Métodos | Valor mínimo por cobrança |
|---|---|---|
Stone (Pagar.me), pagarme | cartão (até 18x), Pix (também na assinatura), Google Pay | sem mínimo |
Stripe, stripe | cartão, Apple Pay e Google Pay (sem Pix) | R$ 0,50 |
Asaas, asaas | Pix (também na assinatura) e cartão na página segura do Asaas | R$ 5,00 |
Uma cobrança acima de zero e abaixo do mínimo do gateway não é enviada: a oferta, o cupom e a troca de plano são validados contra esse mínimo.
Como a integração funciona
- Você gera uma API key (
bk_...) no painel, em Configurações → API keys. - Chama a API REST com
Authorization: Bearer bk_.... Tudo em JSON, dinheiro em centavos. - Cadastra um endpoint de webhook em Configurações → Webhooks e valida a assinatura de cada evento.
- Decide o acesso do cliente no seu SaaS pelo campo
status(nunca pela presença deentitlements, ver a regra de ouro).
Para IA: o contrato completo, legível por máquina, está em
/openapi.json(OpenAPI 3.1) e resumido em/llms.txt. Aponte o seu agente para essas URLs, ou instale o servidor MCP.