POST /api/v1/sales

Registrar uma venda + comissão.

Este é o endpoint principal pra integração com sistemas de pagamento externos. Ele registra uma campaign_sale, cria a commission automaticamente com base na commission_pct do plano, e roda o goal check pra ver se o vendedor bateu alguma meta.

Idempotente por external_ref: se você chamar duas vezes com o mesmo external_ref, a segunda chamada retorna 200 com a venda já criada — sem duplicar comissão.

Request body

campo	tipo	obr	descrição
`referral_code`	string	✓	Código único do vendedor no seu tenant.
`campaign_id`	uuid	✓	ID da campanha.
`plan_id`	uuid	✓	ID do plano vendido (define a comissão %).
`amount_brl`	number	✓	Valor bruto da venda em reais (ex: 149.90).
`external_ref`	string		ID no seu sistema (ex: stripe session_id). Idempotência.
`sold_at`	ISO 8601		Momento da venda. Default: agora.
`customer_ref`	string		Identificador do cliente (email, id externo). Só metadata.
`notes`	string		Observações internas.

Exemplo

bash

curl -X POST https://refera.com.br/api/v1/sales \
  -H "Authorization: Bearer rfr_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "referral_code": "PZMUDXJD",
    "campaign_id": "c64d34c8-0000-0000-0000-000000000000",
    "plan_id": "eb1a683e-0000-0000-0000-000000000000",
    "amount_brl": 149.90,
    "external_ref": "stripe_cs_test_01",
    "customer_ref": "cliente@empresa.com"
  }'

Response · 201 Created

json

{
  "sale_id": "a8f2c341-...",
  "commission_id": "d1b78e05-...",
  "commission_amount_brl": 14.99,
  "idempotent": false
}

Response · 200 (idempotente)

Quando o mesmo external_ref é usado de novo:

json

{
  "sale_id": "a8f2c341-...",
  "commission_id": "d1b78e05-...",
  "commission_amount_brl": 14.99,
  "idempotent": true
}

Erros comuns

404 partner_not_found — referral_code não existe ou vendedor não está ativo.
422 create_failed — regra de negócio violada (campanha inativa, plano não pertence à campanha, vendedor não vinculado, etc). Mensagem detalha.
400 invalid_body — schema Zod falhou. details traz os issues.

Node.js SDK stub

node·lib/refera.ts

export async function reportSale(input: {
  referralCode: string
  campaignId: string
  planId: string
  amountBrl: number
  externalRef: string
}) {
  const res = await fetch('https://refera.com.br/api/v1/sales', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.REFERA_API_KEY!}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      referral_code: input.referralCode,
      campaign_id: input.campaignId,
      plan_id: input.planId,
      amount_brl: input.amountBrl,
      external_ref: input.externalRef,
    }),
  })
  if (!res.ok) throw new Error(`Refera error: ${res.status}`)
  return res.json()
}