Diferente da consulta de uma antecipação específica, este endpoint retorna uma lista paginada das antecipações encontradas com base nos filtros informados.

A consulta de antecipações é útil para acompanhar o ciclo de vida das antecipações realizadas na conta, monitorar mudanças de status e realizar processos de conciliação financeira relacionados à antecipação de recebíveis.

Quando utilizar

Este endpoint é recomendado quando sua integração precisa:

• Consultar múltiplas antecipações de forma consolidada.
• Monitorar antecipações criadas para cobranças ou parcelamentos.
• Filtrar antecipações por status.
• Identificar antecipações que foram creditadas, debitadas, negadas ou canceladas.
• Sincronizar informações de antecipação com sistemas financeiros, ERPs ou processos internos de conciliação.

Ao contrário do endpoint de consulta individual, este recurso permite recuperar diversas antecipações em uma única chamada.

Parâmetros mais relevantes

Embora todos os parâmetros estejam documentados na referência técnica do endpoint, alguns possuem impacto direto no comportamento da consulta.

Status disponíveis

O filtro status permite consultar antecipações em estados específicos.

Exemplo:

GET /v3/anticipations?status=PENDING

Como os filtros funcionam

Os filtros podem ser utilizados para restringir os resultados retornados pela API.

Alguns exemplos:

Consultar antecipações pendentes:

GET /v3/anticipations?status=PENDING

Consultar antecipações de uma cobrança específica:

GET /v3/anticipations?payment=pay_123456

Consultar antecipações de um parcelamento:

GET /v3/anticipations?installment=ins_123456

Quando múltiplos filtros são enviados, apenas os registros compatíveis com todos os critérios informados serão retornados.

Paginação

O retorno é paginado e pode conter apenas parte dos registros encontrados.

Para navegar por grandes volumes de dados, utilize os parâmetros:

• offset
• limit

Exemplo:

GET /v3/anticipations?limit=100&offset=100

📘

Importante

Integrações que realizam sincronizações periódicas devem percorrer todas as páginas disponíveis para garantir a recuperação completa das antecipações.

Exemplo de consulta

Requisição

GET /v3/anticipations?status=CREDITED&limit=50

Exemplo de cenário

Neste exemplo, a API retornará apenas antecipações cujo valor já tenha sido efetivamente creditado na conta.

Esse tipo de consulta é frequentemente utilizado em processos de conciliação financeira para identificar antecipações concluídas.

Boas práticas

• Utilize filtros sempre que possível para reduzir o volume de dados retornados.
• Prefira consultas incrementais em vez de consultar todo o histórico repetidamente.
• Implemente paginação para contas com grande volume de antecipações.
• Considere que o status de uma antecipação pode mudar ao longo do tempo.
• Armazene internamente os identificadores retornados para facilitar futuras consultas individuais.

🚧

Atenção

O status retornado representa a situação da antecipação no momento da consulta e pode sofrer alterações posteriormente em função do processamento financeiro da operação.

Erros comuns

Nenhum resultado encontrado

Pode ocorrer quando os filtros informados não possuem registros compatíveis.

Paginação incompleta

Ocorre quando apenas a primeira página é consultada e existem registros adicionais disponíveis.

Filtros incompatíveis

Combinações específicas de filtros podem reduzir significativamente a quantidade de resultados retornados.

Próximos passos

Dependendo da necessidade da integração, os conteúdos abaixo podem complementar a implementação:

• Consultar antecipação específica.
• Solicitar antecipação.
• Consultar cobranças.
• Consultar parcelamentos.
• Conciliação financeira.
• Recuperar extrato financeiro.

📘

Importante

Chamadas GET para este endpoint devem ser enviadas com o body vazio. Caso a requisição seja enviada com body preenchido, a API poderá retornar erro 403 Forbidden.