Visão geral

Um recebível (receivable) representa um valor a receber na sua conta, gerado automaticamente quando uma transação é aprovada. Cada parcela de uma venda e cada destinatário de um split viram recebíveis independentes, com data prevista de liberação (expectedOn) e status próprio — e este recurso permite consultá-los para conciliação financeira.

Na API pública, Recebíveis é um recurso somente leitura: você lista (GET /v1/receivables) e consulta analytics (GET /v1/receivables/analytics). A criação, a liberação e a mudança de status acontecem por conta do servidor, conforme as transações são processadas — você acompanha essas mudanças pelos webhooks receivable.*, nunca por polling.

O que é um recebível (e por que existe)

Quando um cliente paga, o dinheiro não cai imediatamente disponível na sua conta. Ele entra como um valor a receber, com uma data prevista de liberação que depende do método de pagamento, do parcelamento e das suas condições de antecipação. O recebível é o registro contábil desse valor: quanto é, de qual transação veio, quando deve ser liberado e em que estágio está.

• Vendas parceladas geram um recebível por parcela — cada parcela tem seu próprio installmentNumber e seu próprio expectedOn.
• Splits (divisão de pagamento entre destinatários) geram um recebível por destinatário, ligados pelo splitId.
• O saldo disponível (/v1/finance/balance) é a soma dos recebíveis já liberados (paid).

Use Recebíveis para conciliar o que você recebeu e o que ainda vai receber: relatórios de fluxo de caixa, previsão de liberação, conferência de taxas e auditoria por transação.

Modelo do objeto

O exemplo abaixo é a projeção completa retornada por GET /v1/receivables (cada item de data[]):

{
  "id": "rec_01hqzvabc",
  "transactionId": "tra_01hqzvabc",
  "recipientId": null,
  "splitId": null,
  "currency": "BRL",
  "amount": 4850,
  "grossAmount": 5000,
  "status": "pending",
  "installmentNumber": 1,
  "anticipationFee": 0,
  "liable": true,
  "chargeProcessingFee": true,
  "description": "Payment successfully completed.",
  "paidAt": null,
  "refundedAt": null,
  "canceledAt": null,
  "expectedOn": "2026-04-20T00:00:00.000Z",
  "updatedAt": "2026-04-12T17:56:33.000Z",
  "createdAt": "2026-04-12T17:56:33.000Z"
}

Campos

Ciclo de vida e status

O status de um recebível acompanha o da transação de origem. Um recebível nasce agendado ou pendente, é liberado na data prevista e pode ser afetado por reembolsos, disputas ou chargebacks.

O diagrama ilustra as transições típicas; as transições reais são determinadas pelo ciclo da transação de origem e podem variar conforme o método de pagamento e a adquirente.

Valores de status

Estes são os valores possíveis de status (enum exposto pelo filtro de status em GET /v1/receivables/analytics):

O parâmetro released (yes / no) é um atalho de filtro por "já liberado vs. ainda não liberado", complementar ao status.

Operações disponíveis

As respostas trazem _links (HATEOAS): a listagem aponta para analytics e a analytics aponta para list, permitindo navegar entre as duas visões sem montar URLs à mão. Veja Convenções.

Exemplo rápido

Listar os recebíveis pendentes mais recentes:

curl -s "https://api.selectwin.io/v1/receivables?status=pending&sort=descending&limit=20" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Autenticação é sempre pelo header SelectKey (em sandbox a chave começa com sl_test_). Nunca use Authorization: Bearer/Basic. Veja Autenticação.

Erros

Recebíveis usa os códigos transversais da API — não há códigos error.code específicos deste recurso. Trate sempre pelo error.code (estável), não pela message.

Para o envelope de erro completo e como tratá-lo, veja Tratamento de Erros e o Catálogo de Códigos de Erro.

Boas práticas

• Concilie por transactionId. Vincule cada recebível à sua transação de origem; uma venda parcelada gera vários recebíveis com o mesmo transactionId e installmentNumber distintos.
• Use expectedOn para previsão de caixa, não para confirmação. Só considere o dinheiro disponível quando o status for paid (e/ou paidAt estiver preenchido).
• Some amount, não grossAmount, para o líquido. O grossAmount é o bruto; as taxas (incluindo anticipationFee) explicam a diferença.
• Reaja a mudanças via webhooks receivable.*, não por polling. Listar repetidamente para detectar liberações desperdiça rate limit e atrasa a reação. Veja Proibição de Polling.
• Filtre por período com os parâmetros daterange* (daterangegte/daterangelte para intervalos inclusivos) em vez de baixar tudo e filtrar no cliente.
• Pagine com offset/limit (limit máximo 50) e use hasMore/_links para percorrer páginas. Veja Paginação.
• Trate os IDs como opacos e armazene a string inteira; o prefixo rec_ é só leitura humana.

Veja também

• Listar Recebíveis — filtros, paginação e a projeção completa.
• Analytics de Recebíveis — agregados por período para relatórios.
• Transactions — Visão Geral — a origem de todo recebível.
• Catálogo de Eventos — eventos receivable.*.
• Convenções · Paginação · Autenticação · Proibição de Polling