Motor de Cobrança — API

API REST (e MCP) do motor de cobrança por assinatura da Revtriever. Você cadastra produtos e planos, vincula clientes, e o motor gera e emite as faturas no gateway conectado à sua conta.

Base e autenticação

Base URL: https://motor.revtriever.com/v1
Header:   Authorization: Bearer rk_sua_api_key

A API key é criada em Cobrança → Integração (ou via POST /v1/integration/api-keys). Teste a autenticação:

curl https://motor.revtriever.com/v1/products \
  -H "Authorization: Bearer rk_sua_api_key"

401 = key ausente, errada ou revogada.

Integre pelo seu agente

Se quem escreve a integração é um agente de código (Claude Code, Cursor, Codex…), instale as skills oficiais — ele aprende as convenções, o endpoint de preço e os webhooks antes da primeira linha:

npx skills add Revtriever/revtriever-skills

No Claude Code, o plugin instala as skills e já configura o MCP do motor junto. Fonte: github.com/Revtriever/revtriever-skills.

Convenções (valem para toda rota)

Convenção	Regra
Dinheiro	Sempre centavos, inteiro: 24990 = R$ 249,90. Nunca float
Idempotency-Key	Header obrigatório em POST /products, /plans e /subscriptions. Repetir a mesma chave devolve a mesma resposta, nunca duplica
Erros	problem+json: { type, title, status, detail, requestId, meta? }. O type é o código estável (ex.: engine.plan_archived); guarde o requestId para suporte
Listas	?page=1&pageSize=25 (máx. 100). Exceção: GET /v1/events pagina por cursor
Datas	YYYY-MM-DD no fuso America/Sao_Paulo; instantes em ISO 8601 UTC
Rate limit	300 req/min por conta; estourou → 429 engine.rate_limited com Retry-After em segundos
externalRef	Em clientes e produtos, o campo carrega o seu ID — é ele que devolvemos em webhooks e no endpoint de preço

Exemplo de erro:

{
  "type": "engine.installments_unsupported",
  "title": "EngineInstallmentsUnsupportedError",
  "status": 422,
  "detail": "O gateway stripe cobra cartão em até 1x — parcelamento em 6x não é possível. Para cobrar em partes, considere um plano de período mensal com fidelidade.",
  "requestId": "01a04f38-…",
  "meta": { "maxInstallments": 6, "gatewayMax": 1, "provider": "stripe" }
}

Mapa da documentação

• Conceitos — o modelo de dados: produto, plano (versionado), assinatura, fatura e os estados de cada um.
• Quickstart — do zero à primeira fatura, chamada a chamada.
• Endpoint de preço — o contrato do pull para produto de valor variável, com verificação de assinatura.
• Webhooks e eventos — o catálogo de eventos, o envelope, a verificação HMAC e o replay.
• MCP — conectar um agente à API, as skills instaláveis e o tutorial de confirmação.
• Referência — cada rota campo a campo: significado, valores aceitos de cada enum, exemplos e erros. O contrato bruto gerado do código segue em motor.revtriever.com/docs.