Mudanças da API: Antecipações

Mudanças da API v5 em Antecipações: filtros removidos, campos descontinuados e simulate de GET para POST.

Documentação legada do Pagar.me v5

Esta página descreve um conceito da Pagar.me v5 (versão clássica). Para projetos novos, explore o API Catalog.

Para um consolidado completo de todas mudanças da API, detalhes de prazo para conclusão dos ajustes e contatos de suporte, acesse a página Visão Geral das mudanças da API.

Resumo das mudanças em Antecipações

	Método	Endpoint	Mudança
1	GET	`/core/v5/recipients/{recipient_id}/bulk_anticipations`	Remoção do filtro `id`
2	GET	`/core/v5/recipients/{recipient_id}/bulk_anticipations`	Os campos `FraudCoverageFee` e `AutomaticTransfer` passarão a retornar `null`
3	GET	`/core/v5/recipients/{recipient_id}/bulk_anticipations/limits`	Remoção do filtro `payment_date`
4	GET	`/core/v5/recipients/{recipient_id}/bulk_anticipations/limits`	Objeto `minimum` deixará de retornar
5	—	`/core/v5/recipients/{recipient_id}/bulk_anticipations/simulate`	Mudança no método da requisição

Detalhes das mudanças

Como ler essa seção?

Abaixo, temos o formato de como cada ajuste será apresentado nessa seção.

Endpoint: método e rota afetados.
O que muda: descrição técnica da alteração.
Impacto: consequência prática na sua integração.
Ação necessária: o que você precisa fazer (quando aplicável).
Exemplo: request/response ilustrativo (quando aplicável).

1. `GET /core/v5/recipients/{recipient_id}/bulk_anticipations` — Remoção de filtro

O que muda: o filtro por id será descontinuado.
Impacto: requisições com esse filtro deixarão de retornar resultados filtrados.
Ação necessária: remova o filtro id das suas requisições. Não haverá filtro alternativo — caso precise localizar uma antecipação específica, faça a filtragem no lado da sua aplicação após receber a listagem.

2. `GET /core/v5/recipients/{recipient_id}/bulk_anticipations` — Descontinuação de campos

O que muda: os campos abaixo deixarão de ser preenchidos no response (retornarão null) após o fim da janela de deprecação.
- FraudCoverageFee
- AutomaticTransfer
Impacto: integrações que dependem desses campos deixarão de recebê-los no response.
Ação necessária: remova as dependências desses campos da sua integração. Esses campos não terão substitutos.

3. `GET /core/v5/recipients/{recipient_id}/bulk_anticipations/limits` — Remoção de filtro

O que muda: o filtro por payment_date será descontinuado.
Impacto: requisições com esse filtro deixarão de retornar resultados filtrados.
Ação necessária: ajuste sua integração para não enviar o parâmetro payment_date neste endpoint.

4. `GET /core/v5/recipients/{recipient_id}/bulk_anticipations/limits` — Descontinuação de campos

O que muda: atualmente, o retorno completo retorna o objeto de maximum e o objeto de minimum. Após o fim da janela de deprecação, será retornado somente o objeto de maximum.
Impacto: descontinuação do objeto minimum do response.
Ação necessária: remova as dependências desse campo da sua integração. Esses campos não terão substitutos.
Exemplo

{
  "maximum": {
    "amount": 0,
    "anticipation_fee": 0,
    "fee": 0,
    "fraud_coverage_fee": 0
  }
}

{
  "maximum": {
    "amount": 0,
    "anticipation_fee": 0,
    "fee": 0,
    "fraud_coverage_fee": 0
  },
  "minimum": {
    "amount": 0,
    "anticipation_fee": 0,
    "fee": 0,
    "fraud_coverage_fee": 0
  }
}

5. `/core/v5/recipients/{recipient_id}/bulk_anticipations/simulate` — Mudança no método de `GET` para `POST`

O que muda: atualmente o método é GET e passará a ser POST com envio dos parâmetros obrigatórios no body da requisição, não mais no Query/Path Params.
Impacto: clientes que utilizam essa rota precisam adaptar o método e requisição.
Ação necessária: a requisição precisa ser alterada para o método POST e envio dos parâmetros obrigatórios no body, seguindo os detalhes abaixo.

Campo	Tipo	Obrigatório	Regras	Exemplo
`timeframe`	`string`	Sim	`start` ou `end`	`start`
`requested_amount`	`int`	Sim	Maior que `0`	`10000`

Exemplo

{
  "timeframe": "start",
  "requested_amount": 10000
 }

Perguntas frequentes das mudanças em Antecipações

Existe ambiente de sandbox para testar as mudanças antes do go-live?

Sim. Iremos fornecer respostas de exemplo nas principais mudanças no ambiente de sandbox já utilizado atualmente na sua integração. Você poderá acessá-lo com suas credenciais de teste normais. Detalhes estão disponíveis em "Testes de integração" na página "Visão Geral das mudanças da API".

Os campos FraudCoverageFee e AutomaticTransfer em GET /core/v5/recipients/{recipient_id}/bulk_anticipations também deixarão de retornar?

Sim, após o fim da janela retornarão null. Se sua integração os utiliza, remova as dependências, verifique se há cálculos ou lógica condicionada a esses campos.

O campo payment_date não é mais obrigatório na mudança de GET para POST no /core/v5/recipients/{recipient_id}/bulk_anticipations/simulate?

Não. Após o fim da janela, não será mais possível passar o payment_date na rota /core/v5/recipients/{recipient_id}/bulk_anticipations/simulate.