Quickstart

Pré-requisitos: gateway conectado na sua conta Revtriever 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. 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": "[email protected]"
    }
  }'

{
  "id": "0199c1b0-…",
  "planId": "0199c1a8-…",
  "planVersion": 1,
  "status": "active",
  "chargeDay": 29,
  "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.

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": [
    {
      "productName": "Caixa do Clube",
      "monthlyPriceCents": 24990,
      "months": 6,
      "discountPercent": 20,
      "totalCents": 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. Alguns dias antes do vencimento a fatura é gerada (a régua congela os valores; produto variável tem o preço puxado do seu endpoint) e a cobrança avulsa é criada no seu gateway. 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.
• Contrato completo de cada rota: Referência.