Quickstart

Pré-requisitos: gateway conectado na sua conta Revtriever (Vindi, Stripe, Malga, Asaas ou pagar.me) e uma API key criada em Cobrança → Integração.

Toda chamada leva a key no header. Todo POST que cria recurso (/products, /plans, /subscriptions) leva também um Idempotency-Key — qualquer string única sua; repetir a mesma devolve a mesma resposta, nunca duplica:

export MOTOR=https://motor.revtriever.com/v1
export AUTH="Authorization: Bearer rk_sua_api_key"

1. Crie um produto

Preço sempre mensal, em centavos:

curl -X POST $MOTOR/products -H "$AUTH" -H "Idempotency-Key: prod-caixa-1" \
  -H "Content-Type: application/json" -d '{
    "name": "Caixa do Clube",
    "description": "6 garrafas · seleção do sommelier",
    "pricing": { "mode": "fixed", "monthlyPriceCents": 24990 }
  }'

{
  "id": "0199c1a2-…",
  "name": "Caixa do Clube",
  "pricingMode": "fixed",
  "monthlyPriceCents": 24990,
  "endpointUrl": null,
  "archivedAt": null,
  "createdAt": "2026-08-29T18:12:03.000Z"
}

Se o seu gateway tem catálogo de produtos (Vindi, Stripe), o motor cria o espelho lá automaticamente, em background.

2. Monte um plano

O plano carrega período, método padrão, parcelamento e a régua de desconto por produto:

curl -X POST $MOTOR/plans -H "$AUTH" -H "Idempotency-Key: plano-semestral-1" \
  -H "Content-Type: application/json" -d '{
    "name": "Clube Semestral",
    "periodMonths": 6,
    "defaultPaymentMethod": "card",
    "maxInstallments": 6,
    "items": [{
      "productId": "<id do passo 1>",
      "discounts": [
        { "percent": 20, "fromCycle": 1, "toCycle": 2 },
        { "percent": 10, "fromCycle": 3, "toCycle": 5 }
      ]
    }]
  }'

Leitura: uma fatura a cada 6 meses de 6 × R$ 249,90, com 20% off nos 2 primeiros ciclos, 10% do 3º ao 5º, cheia depois. Cartão em até 6x. Opcional: expirationDays (0–90, padrão 0) define quantos dias depois da geração a cobrança vence. A resposta traz id e version: 1.

Se o gateway conectado não suporta o método ou o parcelamento pedido, a resposta é 422 com type: engine.payment_method_unsupported ou engine.installments_unsupported — nada é convertido por conta própria.

3. Vincule um cliente

customer.externalRef é o ID do cliente no seu sistema — é ele que devolvemos em webhooks e no endpoint de preço:

curl -X POST $MOTOR/subscriptions -H "$AUTH" -H "Idempotency-Key: sub-4512-1" \
  -H "Content-Type: application/json" -d '{
    "planId": "<id do passo 2>",
    "customer": {
      "externalRef": "cliente-4512",
      "name": "Ana Beatriz Sales",
      "email": "ana@exemplo.com.br"
    }
  }'

{
  "id": "0199c1b0-…",
  "planId": "0199c1a8-…",
  "planVersion": 1,
  "status": "active",
  "chargeDay": 28,
  "paymentMethod": "card",
  "paymentMethodSource": "plan_default",
  "cycleCount": 0,
  "nextDueDate": "2026-09-28",
  "customer": { "id": "…", "externalRef": "cliente-4512", "name": "…", "email": "…" }
}

Campos opcionais:

• chargeDay (1–28): dia do vencimento. Omitido, vira o dia de hoje (29, 30 ou 31 viram 28).
• firstChargeDate (YYYY-MM-DD, futura): adia a primeira fatura para essa data.
• paymentMethod: sobrescreve o padrão do plano só para esta assinatura.
• gatewayConnectionId: com mais de um gateway conectado, escolhe por qual esta assinatura fatura (obrigatório nesse caso — as opções estão em GET /v1/integration). Com um só, omita.
• expirationDays (0–90): sobrescreve o prazo de vencimento do plano só para esta assinatura.
• customer.phone e customer.address: opcionais no geral, mas a pagar.me exige telefone para emitir pix e endereço para emitir boleto — sem eles a fatura fica retida com o erro do gateway.

4. Simule a próxima fatura

curl $MOTOR/subscriptions/<id>/preview -H "$AUTH"

{
  "subscriptionId": "0199c1b0-…",
  "cycle": 1,
  "dueDate": "2026-09-28",
  "paymentMethod": "card",
  "installments": 6,
  "fixedTotalCents": 119952,
  "hasPendingItems": false,
  "items": [
    {
      "productId": "0199c1a2-…",
      "productName": "Caixa do Clube",
      "pricingSource": "table",
      "pricingStatus": "priced",
      "monthlyPriceCents": 24990,
      "months": 6,
      "discountPercent": 20,
      "amountCents": 119952
    }
  ]
}

É a mesma decisão da geração real, sem nenhum efeito — use para conferir régua e parcelas antes do primeiro ciclo. Item de preço variável aparece com pricingSource: endpoint; o valor real só é apurado na geração.

5. O que acontece depois

Você não emite fatura — o motor emite. No chargeDay, entre 05h e 22h BRT, a fatura é gerada (a régua congela os valores; produto variável tem o preço puxado do seu endpoint com a janela do ciclo já fechada) e a cobrança avulsa é criada no seu gateway, vencendo em chargeDay + expirationDays. Para acompanhar:

curl "$MOTOR/invoices?page=1&pageSize=25" -H "$AUTH"     # todas as faturas
curl "$MOTOR/events?limit=50" -H "$AUTH"                 # invoice.issued, invoice.paid, …

Ou receba por push: cadastre um webhook em Cobrança → Integração — o catálogo completo está em Webhooks e eventos.

Próximos passos

• Produto de valor variável (uso, consumo): Endpoint de preço.
• Integrar por agente em vez de código: MCP.
• Usa Claude Code, Cursor ou Codex para escrever a integração? Instale as nossas skills — npx skills add Revtriever/revtriever-skills — e o agente aprende as convenções, o endpoint de preço e os webhooks (detalhes no guia MCP).
• Contrato completo de cada rota: Referência.