Convenções da API

Toda a API vive sob uma base, com um conjunto único de regras:

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

A referência está organizada por recurso:

Recurso	O que cobre
Produtos	Catálogo: criar, editar, arquivar e testar o endpoint de preço
Planos	A oferta: período, método, parcelamento, régua de desconto, versões
Assinaturas	Vincular cliente, simular fatura, condição individual, cancelar
Faturas	Consultar, destravar pricing retido, informar valor manual
Eventos	O replay de tudo que o motor conta pro seu sistema
Integração	API keys, secret de integração e webhook de alertas

O contrato bruto (gerado do código, sempre em dia) segue disponível em motor.revtriever.com/docs (Swagger UI) e /docs-json (OpenAPI 3, para gerar clients). As páginas aqui cobrem o mesmo contrato com o significado de cada campo, os valores aceitos e as regras que não cabem num schema.

Autenticação

Toda chamada leva Authorization: Bearer rk_…. A API key é criada em Cobrança → Integração ou via POST /v1/integration/api-keys, e tem escopo da sua conta — não existe key global.

401 significa key ausente, inválida ou revogada. Não confunda a API key (você → motor) com o secret de integração (motor → você, assina webhooks e chamadas de preço) — são credenciais distintas.

Idempotência

O header Idempotency-Key é obrigatório nos três POSTs que criam recurso:

• POST /v1/products
• POST /v1/plans
• POST /v1/subscriptions

O valor é qualquer string única sua (um UUID, ou algo determinístico como sub-{seuClienteId}). Repetir a mesma chave devolve a mesma resposta da primeira chamada — nunca cria de novo. É o que torna seguro retentar um POST que deu timeout. Sem o header, a resposta é 400.

Formatos de dado

Formato	Regra
Dinheiro	Sempre centavos, inteiro: 24990 = R$ 249,90. Nunca float, nunca string com vírgula
Datas	YYYY-MM-DD, no fuso America/Sao_Paulo (ex.: dueDate, firstChargeDate)
Instantes	ISO 8601 em UTC: 2026-08-29T18:12:03.000Z (todo campo *At)
Ids	UUID gerado pelo motor. Campos *Id referenciam sempre o id do motor
externalRef	O seu id — aceito em clientes e produtos, devolvido em webhooks e no endpoint de preço. A busca nos recursos é sempre pelo id do motor
Nulos	Campo null na resposta é semântico (ex.: totalCents: null = fatura ainda sem valor fechado) — documentado campo a campo em cada recurso

Paginação

As listas (GET /products, /plans, /subscriptions, /invoices) paginam por página:

Parâmetro	Tipo	Padrão	Descrição
page	integer	1	Página, começando em 1
pageSize	integer	25	Itens por página — máximo 100

A resposta tem sempre a mesma casca:

{
  "data": [ … ],
  "pagination": { "page": 1, "pageSize": 25, "totalRecords": 132, "totalPages": 6 }
}

Exceção: GET /v1/events pagina por cursor (cursor + limit, padrão 50, máximo 200) e devolve nextCursor — é um stream de replay, não uma lista navegável.

Erros

Todo erro sai em problem+json, com a mesma forma:

{
  "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.",
  "requestId": "01a04f38-…",
  "meta": { "maxInstallments": 6, "gatewayMax": 1, "provider": "stripe" }
}

Campo	Tipo	Descrição
type	string	Código estável, legível por máquina (engine.…) — é nele que seu código deve fazer branch, nunca no texto
title	string	Classe do erro, para humanos
status	integer	O mesmo HTTP status da resposta
detail	string	Mensagem legível — segura para exibir ao usuário final
requestId	string | null	Id de correlação — é o que o suporte pede para achar a trilha completa
meta	object	Detalhes estruturados (campos inválidos, ids, limites), quando fizer sentido

Como os status são usados:

Status	Quando
400	Payload inválido ou Idempotency-Key ausente
401	API key ausente, inválida ou revogada
404	Recurso não existe (ou não é da sua conta)
409	Conflito de estado: mexer no modo de preço (imutável), plano arquivado, assinatura já cancelada, item que não está aguardando valor
422	Regra de negócio: método/parcelamento não suportado pelo gateway conectado, desconto em produto variável

Exemplos de códigos que você vai encontrar: engine.payment_method_unsupported, engine.installments_unsupported, engine.plan_archived, engine.gateway_choice_required. Cada página de recurso lista os erros possíveis de cada rota.

Exemplos desta referência

Os exemplos em curl assumem as duas variáveis do Quickstart:

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