Skip to main content
GET
Listar recebíveis
GET /receivables Faz parte do recurso Recebíveis — o conceito, o ciclo de vida e a tabela de status estão lá. Retorna os recebíveis da sua conta do mais próximo de cair ao mais distante (expectedAt crescente, com id como desempate), paginados: limit padrão 20, máximo 100 — confira pagination.totalPages antes de concluir que a lista acabou. Todos os filtros são opcionais e podem ser combinados. Sem status, vêm todos os status, inclusive liquidated e cancelled; os valores aceitos estão em Status do recebível, e as datas seguem ISO 8601 com timezone (veja Convenções).
Filtro com valor inválido é rejeitado, não ignorado. ?status=pago responde 400 com error.issues[] apontando o campo e os valores aceitos. O mesmo vale para type, paymentMethod, currency e para data fora do formato.O formato do erro está em Erros.
Vários valores no mesmo filtro. status, type, paymentMethod e recipientIds aceitam uma lista separada por vírgula, e o resultado traz qualquer recebível que case com um dos valores. Ex.: ?status=projected,confirmed&paymentMethod=credit_card.
O cronograma de uma venda. transactionId e paymentId são match exato: ?transactionId=txn_... devolve uma linha por recebedor e por parcela daquela venda, na ordem em que vão cair — é a forma de saber quando o dinheiro de um pedido chega.
Sincronização incremental. Para trazer só o que mudou desde a última execução, combine dateField=updatedAt com startDate e ordene por updatedAt. O campo muda a cada alteração do recebível — a confirmação do adquirente, a liquidação, um estorno meses depois da venda —, o que uma busca por expectedAt não traria.
Prefira janelas fechadas (startDate + endDate) a varrer muitas páginas de um período ainda em aberto: registros alterados durante a varredura mudam de posição e podem escapar da paginação.
O recebível nasce depois do pagamento, não junto. Ele é criado instantes após o pagamento ser confirmado. Quem consulta ao receber o webhook payment.paid pode ainda não encontrar nada — trate a lista vazia como “ainda não projetado” e consulte de novo.

​
Exemplo

Uma venda de R$ 300 em 3x, um mês depois. A primeira parcela já liquidou: liquidatedAt preenchida e walletTransactionId apontando o lançamento correspondente no extrato. As outras duas estão confirmed — valores definitivos, falta chegar a data. Um recebível recém-criado vem projected, com feeAmount 0 e netAmount igual ao bruto, até o adquirente confirmar.

Authorizations

​
x-api-key
string
header
required

API Key da Credential (gerada no Backoffice)

Query Parameters

​
page
integer
default:1

Página da listagem. Padrão: 1.

Required range: x >= 1
​
limit
integer
default:20

Itens por página. Padrão: 20. Máximo: 100.

Required range: 1 <= x <= 100
​
recipientIds
string[]

IDs de recebedores (rec_). Aceita vários valores separados por vírgula.

Minimum string length: 1
​
transactionId
string | null

ID da transação de origem (txn_). Match exato.

Minimum string length: 1
​
paymentId
string | null

ID do pagamento de origem (pay_). Match exato.

Minimum string length: 1
​
status
enum<string>[]

Status do recebível. Aceita vários valores separados por vírgula. Sem o filtro, todos os status.

Available options:
projected,
confirmed,
paid,
liquidated,
anticipated,
cancelled
​
type
enum<string>[]

Natureza do lançamento: credit, refund_reversal e chargeback_refund somam; refund e chargeback subtraem. Aceita vários valores separados por vírgula.

Available options:
credit,
refund,
refund_reversal,
chargeback,
chargeback_refund
​
paymentMethod
enum<string>[]

Método de pagamento da venda de origem. Aceita vários valores separados por vírgula.

Available options:
credit_card,
debit_card,
boleto,
pix
​
currency
enum<string> | null

Moeda (ISO 4217). Hoje o único valor aceito é 'BRL'.

Available options:
BRL
​
startDate
string<date-time> | null

Data inicial, ISO 8601 com timezone, inclusive. Aplica-se ao campo indicado em dateField.

​
endDate
string<date-time> | null

Data final, ISO 8601 com timezone, inclusive. Aplica-se ao campo indicado em dateField.

​
dateField
enum<string> | null

Campo de data ao qual startDate/endDate se aplicam. Padrão: expectedAt. Use updatedAt para sincronização incremental (o campo muda a cada alteração do recebível).

Available options:
expectedAt,
updatedAt
​
sortBy
enum<string> | null

Campo de ordenação. Padrão: expectedAt.

Available options:
expectedAt,
updatedAt
​
sortDir
enum<string> | null

Direção da ordenação. Padrão: asc (do mais próximo ao mais distante).

Available options:
asc,
desc

Response

Lista paginada de recebíveis

​
data
object[]
required

Lista de registros retornados na página atual.

​
pagination
object
required

Dados de paginação do resultado.