Listar recebíveis

Lista os recebíveis (valores a receber) da sua conta — cada parcela que uma transação gera e que será liquidada no seu saldo. Use este endpoint para acompanhar o que já caiu, o que ainda está pendente e quando cada valor fica disponível, com filtros de status, período e paginação. É a base para conciliação financeira, previsão de caixa e relatórios de receita.

GET /v1/receivables

Recebível (do inglês receivable) é um direito de recebimento: quando uma venda é aprovada, a plataforma cria um ou mais recebíveis (um por parcela) que serão pagos a você na data prevista. Listar recebíveis é, na prática, ver o "extrato futuro e passado" das suas vendas.

Como funciona

Cada transação aprovada gera recebíveis — um para pagamento à vista (parcela 1) ou vários para vendas parceladas (uma parcela por mês). Cada recebível tem um valor bruto (grossAmount, o que o cliente pagou na parcela) e um valor líquido (amount, o que efetivamente entra no seu saldo, já descontadas as taxas). Ele nasce com status: "pending" e tem uma data prevista de liquidação (expectedOn); quando o dinheiro é liberado, o status passa para paid e paidAt é preenchido.

Ciclo de vida típico de um recebível:

Pontos importantes sobre o mecanismo:

• Projeção leve em listas. Os itens em data[] são uma visão resumida do recebível. Trate os campos null (paidAt, refundedAt, canceledAt, recipientId, splitId) como "ainda não aconteceu" / "não se aplica" — veja Convenções → null vs. ausente.
• Somente leitura. Recebíveis não são criados nem alterados por você; eles são consequência de transações, estornos e disputas. Para mudar o estado, opera-se na transação de origem, não no recebível.
• Resposta paginada padrão. O corpo é o objeto de paginação (não um array direto), com data[], metadados de página, merchant e _links HATEOAS. Veja Paginação.
• Atualizações via webhook, nunca por polling. Para saber quando um recebível muda de status, assine eventos em vez de ficar relistando — veja Proibição de Polling.

Quando usar

• Previsão de caixa: filtre por status=pending e por período (daterange*) para ver o que vai entrar.
• Conciliação: cruze os recebíveis paid de um dia com o seu extrato bancário/contábil.
• Auditoria de uma transação: filtre por id ou cruze pelo transactionId dos itens.

Quando não usar:

• Para saber o saldo agregado disponível agora, use Consultar Saldo — não some recebíveis manualmente.
• Para métricas e totais de um período (em vez da lista item a item), use o endpoint de analytics de recebíveis (GET /v1/receivables/analytics).
• Para detalhes da venda (cliente, método de pagamento, parcelas), consulte a transação de origem em Listar Transações.

Requisição

Headers

Como é uma leitura (GET), não há corpo nem necessidade de Content-Type ou X-Idempotency-Key.

Parâmetros de query

Todos são opcionais. Combine-os livremente (ex.: status + período + paginação).

Valores de status aceitos:

Exemplo curl

Listar os 20 recebíveis pendentes mais recentes:

curl -G https://api.selectwin.io/v1/receivables \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  --data-urlencode "status=pending" \
  --data-urlencode "sort=descending" \
  --data-urlencode "limit=20" \
  --data-urlencode "offset=0"

Filtrar por período (recebíveis liberados em abril/2026):

curl -G https://api.selectwin.io/v1/receivables \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  --data-urlencode "status=paid" \
  --data-urlencode "daterangegte=2026-04-01T00:00:00Z" \
  --data-urlencode "daterangelt=2026-05-01T00:00:00Z"

Buscar um recebível específico:

curl -G https://api.selectwin.io/v1/receivables \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  --data-urlencode "id=rec_01hqzvabc"

Resposta

200 OK — objeto paginado com a lista em data[], metadados de página, merchant e _links.

{
  "offset": 0,
  "limit": 20,
  "total": 128,
  "page": {
    "offset": { "first": 0, "prev": null, "next": 20, "last": 120 },
    "current": 1,
    "total": 7
  },
  "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"
    }
  ],
  "hasMore": true,
  "merchant": {
    "name": "Seller Name",
    "merchantId": "bus_1234567890",
    "isSubAccount": false
  },
  "_links": {
    "self": {
      "href": "https://api.selectwin.io/v1/receivables/list",
      "method": "GET"
    },
    "analytics": {
      "href": "https://api.selectwin.io/v1/receivables/analytics",
      "method": "GET"
    }
  }
}

Campos de paginação

Detalhes em Paginação.

Campos de cada recebível (data[])

Erros

A API responde com o envelope padrão de erro, em que o que importa é o error.code (estável e legível por máquina), não a message. Veja Tratamento de Erros e o Catálogo de Códigos de Erro.

{
  "error": {
    "code": "invalidParameters",
    "statusCode": 400,
    "category": "validation",
    "message": "Validation errors occurred.",
    "params": [
      { "limit": "limit must be a number between 1 and 50" }
    ]
  }
}

Boas práticas

• Pagine pelos page.offset.*. Avance usando page.offset.next até hasMore virar false, em vez de recalcular offsets na mão — assim você não pula nem repete itens.
• Respeite o teto de limit (50). Pedir mais que 50 retorna invalidParameters. Para grandes volumes, prefira páginas de 50 com intervalos entre as chamadas (evita 429).
• Filtre por período no servidor. Use daterangegte + daterangelt para janelas fechadas, em vez de baixar tudo e filtrar localmente — menos dados, menos chamadas, menos risco de rate limit.
• Não some recebíveis para obter saldo. Para o disponível agregado, use Consultar Saldo; os valores já consideram bloqueios, pendências e garantias.
• Distinga amount de grossAmount. Para receita líquida, some amount; para o total cobrado do cliente, some grossAmount. Misturá-los gera divergência de conciliação.
• Não fique relistando para detectar mudanças. Assine Webhooks para reagir a liberações/estornos em vez de fazer polling.
• Trate todos os timestamps como UTC. Converta para o fuso do usuário só na exibição; ao filtrar, envie sempre o sufixo Z.

Veja também

• Visão Geral de Finanças — o recurso e todas as suas operações.
• Consultar Saldo — saldo disponível, pendente e bloqueado.
• Paginação · Convenções · Tratamento de Erros · Proibição de Polling
• Listar Transações — detalhes das vendas que originam os recebíveis.