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.

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
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": "Conflito",
  "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 e o tutorial de confirmação.
• Referência — o contrato completo de cada rota, gerado do código, em motor.revtriever.com/docs.