Visão Geral das mudanças da API

As datas oficiais serão comunicadas por e-mail, além de publicação e atualização nessa documentação. Recomendamos manter seus contatos atualizados.

Você terá uma janela de 45 dias entre o início da deprecação e o momento em que as mudanças entram em vigor. Durante todo este período, o comportamento antigo continuará disponível em paralelo. Recomendamos começar a adequação no início dessa janela para evitar impactos na integração.

Após o fim da janela, sua integração pode sofrer interrupção. Revise as mudanças e o que precisa ser alterado em sua integração para evitar impacto, recomendamos fortemente não deixar para o último momento.

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".

Não é recomendado. Use o sandbox para testes antes do go-live. Durante a janela de deprecação em produção, o comportamento antigo continua funcionando, permitindo migração gradual da sua aplicação. Quando estiver pronto, aplique as mudanças em produção.

Depende de como você trata esses códigos. Se você tem mapeamentos customizados ou uma tabela de lookup, será necessário atualizar para o padrão ABECS.

Consulte a documentação de códigos de retorno ABECS para a tabela de mapeamento para mais detalhes.

Sim. Os webhooks de atualização de status chegarão com o charge_id da nova cobrança, não com o do original. Sua integração de webhooks precisa:

1. Reconhecer que a nova cobrança é um registro independente.
2. Vinculá-la ao order_id para rastreamento.
3. Não sobrescrever o status da cobrança original — ambas devem ser consultáveis.

Sim, se sua coluna de banco de dados for INTEGER ou BIGINT. Você precisa:

1. Alterar o schema para aceitar VARCHAR ou TEXT (até 128 caracteres).
2. Se houver parsing no código (ex: parseInt() em JavaScript), remover ou desativar.
3. Se houver validação regex, atualizar para aceitar alfanuméricos.

Recomendamos fazer essas alterações antes do fim da janela, para permitir armazenar ambos os formatos durante a transição.

Caso sua integração precise manter histórico de longo prazo, armazene localmente os dados de recebíveis pagos antes do fim da janela de deprecação. Após esse período, recebíveis pagos com mais de 24 meses não estarão mais disponíveis via API.

Recomendações:

1. Exporte o período desejado usando paginação por cursor, respeitando o limite de RPM (Requests Per Minute).
2. Evite consultar por id específicos, realize sua busca utilizando payment_date ou updated_at.
3. Armazene os dados localmente em seu banco de dados.
4. Mantenha esses dados localizáveis para auditorias e reconciliações futuras.

Não. A limitação de 24 meses aplica-se apenas a recebíveis já pagos. Recebíveis em aberto, agendados ou futuros continuarão disponíveis em sua totalidade, sem restrição de período.

Sim, mas recomendamos migrar o quanto antes. Além de deixar de funcionar após a janela de 45 dias, a mudança para cursor também resulta em uma consulta mais performática.

Esses campos deixarão de ser preenchidos (retornarão null) para recebíveis criados após o fim da janela. Recebíveis criados antes continuam retornando os valores. Se você depende desses campos para reconciliação ou rastreabilidade, será necessário alterar sua lógica.

Lembre-se: esses campos não terão substitutos diretos.

Não. Será incluído quando disponível (quando há vinculação à settlement), mas pode estar null para recebíveis que não têm relacionamento com settlement ainda. Trate como campo opcional.

Sim, se sua integração não tratar esses valores. Se você faz parsing de originator_model com uma lista fixa de valores ou com regex, precisará atualizá-la. Os 6 valores possíveis após a mudança são: refund, chargeback, ownership_assignment, cross_balance, guarantee e financial_adjustment.

Não, após o fim da janela esse endpoint será descontinuado. Use GET /core/v5/payables?id=<payable_id> como filtro no endpoint de listagem.

Depende do tipo de operação que você consulta:

1. payables (recebíveis): GET /core/v5/payables
2. settlements: GET /core/v5/settlements

Consulte a tabela na página "Financeiro" no item 8 para mais detalhes.

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.

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.

Os dois formatos podem coexistir durante a transição. Não dependa do prefixo sett_ ou de tamanho fixo no seu código.

1. Exemplo antes: sett_cm3kx7t2n0a4b1jn12h95wzq8
2. Exemplo depois: 0000A978-24A7-0822-902E-FFFFFFAC08DD