Listar recebíveis

Retorna uma lista paginada dos seus recebíveis (valores a receber gerados por transações aprovadas), com filtros por status, por estado de liberação e por intervalo de datas. É o endpoint que você usa para conciliação financeira: ver o que já caiu, o que ainda vai cair e em que data.

GET /v1/receivables

Como funciona

Um recebível (receivable) é um valor a receber na sua conta. Ele é criado automaticamente quando uma transação é aprovada — você não cria recebíveis pela API. Cada parcela de uma venda parcelada e cada destinatário de um split geram seu próprio recebível, com data prevista de liberação (expectedOn) e status próprio. Para o modelo completo do objeto e o ciclo de vida dos status, veja a Visão geral.

Este endpoint é somente leitura e retorna a projeção completa de cada recebível — os 19 campos do objeto, e não um recorte resumido. Por isso ele é a fonte de dados para extratos detalhados, relatórios de conciliação e telas que listam linha a linha o que você tem a receber. Se você só precisa de um recorte enxuto voltado a agregação/relatórios, use Analytics.

A resposta segue o envelope de paginação padrão da API (offset, limit, total, hasMore, page, data, merchant, _links). Diferentemente da maioria das listagens — em que data[] traz uma projeção leve — aqui cada item de data vem completo. O bloco _links (navegação HATEOAS) inclui um atalho analytics apontando para o endpoint de métricas do mesmo recurso.

Os filtros se combinam por E lógico: passar status=pending e um intervalo de datas retorna apenas recebíveis pendentes dentro daquele intervalo. Os limites de paginação seguem a convenção global, com a ressalva de que aqui o limit aceita no máximo 50 itens por página.

Quando usar

• Conciliação e extrato: listar o que você tem a receber, com valores líquido/bruto, parcela e data prevista, item a item.
• Acompanhar liberações: combinar status e released para separar o que já foi liquidado do que ainda está agendado/pendente.
• Fechamento por período: usar os filtros daterange* para recortar um dia ou uma janela (ex.: tudo previsto para abril).

Quando não usar (e a alternativa):

• Para totais e agregados (somatórios, recorte por período obrigatório) prefira Analytics — ele já vem com um payload mais leve por item.
• Para reagir a mudanças de status de um recebível, não fique consultando esta lista em loop. Assine os eventos receivable.* por webhook — veja Proibição de polling.

Requisição

Headers

Por ser uma requisição GET sem corpo, não há Content-Type nem chave de idempotência.

Parâmetros de query

Todos opcionais. Os filtros se acumulam (E lógico).

Exemplos curl

Listagem simples (primeira página, 20 itens):

curl -X GET "https://api.selectwin.io/v1/receivables?limit=20&offset=0&sort=descending" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Apenas recebíveis pendentes ainda não liberados:

curl -X GET "https://api.selectwin.io/v1/receivables?status=pending&released=no" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Tudo previsto dentro de uma janela de datas (fechamento de abril):

curl -X GET "https://api.selectwin.io/v1/receivables?daterangegte=2026-04-01T00:00:00Z&daterangelte=2026-04-30T23:59:59Z" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Um recebível específico por ID:

curl -X GET "https://api.selectwin.io/v1/receivables?id=rec_01hqzvabc" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Resposta 200 OK

O corpo é o objeto paginado diretamente. Cada item de data traz a projeção completa do recebível.

{
  "offset": 0,
  "limit": 20,
  "total": 128,
  "hasMore": true,
  "page": {
    "current": 1,
    "total": 7,
    "offset": { "first": 0, "prev": null, "next": 20, "last": 120 }
  },
  "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"
    }
  ],
  "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 do envelope

Campos de cada recebível (data[])

Erros

Este recurso usa o envelope de erro padrão (veja Tratamento de erros); trate sempre pelo error.code, nunca pela message. A listagem de recebíveis não tem códigos de erro de regra de negócio próprios — os erros possíveis são os transversais:

Veja a lista completa em Catálogo de Códigos de Erro.

Boas práticas

• Pagine pelos page.offset.* da resposta, não recalculando offsets na mão. Pare quando hasMore for false (ou page.offset.next for null).
• Respeite o teto de 50 por página: pedir limit maior não retorna mais itens e pode gerar invalidParameters. Para volumes grandes, itere as páginas com um pequeno intervalo entre chamadas para não estourar o rate limit.
• Filtre no servidor. Use status, released e daterange* para reduzir o tráfego em vez de baixar tudo e filtrar localmente.
• Recortes de período corretos: para uma janela fechada, combine daterangegte (início, inclusivo) com daterangelte (fim, inclusivo); para um único dia, basta daterange.
• Trate IDs como opacos. Use rec_... apenas como identificador; não tente extrair informação do conteúdo.
• Concilie em centavos. Some amount/grossAmount como inteiros e converta para reais só na apresentação.
• Não faça polling para detectar liberações. Assine os eventos receivable.* (paid, canceled, refunded, etc.) e use esta lista para reconciliar — veja Proibição de polling.

Veja também

• Recebíveis - Visão geral — modelo do objeto, ciclo de status e eventos.
• Recebíveis - Analytics — recorte resumido e agregados por período.
• Paginação e Convenções — envelope de listas, datas e dinheiro em centavos.
• Catálogo de Códigos de Erro e Tratamento de erros.