rrefera
HomeEntrar

Referência

Todos os endpoints.

Todas as rotas usam Authorization: Bearer rfr_live_.... Todas retornam JSON com Content-Type: application/json. Erros seguem o shape { "error": { code, message, reference? } }.

métodopathdescrição
POST/api/v1/salesRegistra uma venda + comissão + goal check. Idempotente por external_ref. →
POST/api/v1/conversionsRegistra um lead/conversion pré-venda.
GET/api/v1/partnersLista partners do tenant. Filtros: status, limit.
POST/api/v1/partnersCria partner (gera referral_code automático).
GET/api/v1/partners/{code}Lookup por referral_code.
GET/api/v1/commissionsLista comissões. Filtros: partner_id, status.
GET/api/v1/withdrawalsLista saques. Filtros: partner_id, status.
POST/api/v1/withdrawalsSolicita saque PIX.
POST/api/v1/withdrawals/{id}/{decision}Aprova, paga ou rejeita um saque.

Erros

Os erros retornam HTTP 4xx ou 5xx com um objeto error contendo:

  • code: máquina-amigável para routing e tratamento (ex: partner_not_found, insufficient_balance, internal).
  • message: descrição amigável. Para erros 4xx (validação, negócio), é em português. Para erros 5xx (interno), é genérica com um ID de correlação para suporte.
  • reference: UUID presente apenas em erros 5xx, vinculando a resposta ao log do servidor. Time de suporte usa este ID para investigar em logs estruturados.

Exemplo de erro 500 (interno):

{
  "error": {
    "code": "internal",
    "message": "Internal server error. Reference: a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

Se você receber um erro 500, copie o UUID e compartilhe com o time de suporte — ele correlaciona sua requisição com logs detalhados no servidor.

Convenções

  • Tempos: ISO 8601 UTC (2026-08-06T14:38:19Z).
  • Valores monetários: reais em number com duas casas decimais (não string).
  • UUIDs: lowercase com hífens.
  • Rate limit: hoje sem limite formal. Se você precisa fazer >100 req/s, chama a gente antes.