Mudanças da API: Financeiro

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 no Financeiro

Detalhes das mudanças

1. GET /core/v5/payables — Histórico limitado a 24 meses

• O que muda: o histórico de recebíveis pagos retornado pelo endpoint passa a ser limitado aos últimos 24 meses, contados a partir da data de criação do recebível. Recebíveis em aberto ou futuros continuam disponíveis na totalidade, sem restrição de período.
• Impacto: consultas que dependem de recebíveis pagos com mais de 24 meses não retornarão esses registros.
• Ação necessária: se sua integração precisa manter histórico de longo prazo, armazene localmente os dados de recebíveis pagos antes do fim da janela de deprecação.

2. GET /core/v5/payables — Paginação exclusiva por cursor

• O que muda: a paginação por offset será descontinuada. A partir do fim da janela, a paginação será feita exclusivamente por cursor.
• Impacto: integrações que utilizam paginação por offset deixarão de funcionar.
• Ação necessária: adapte sua integração para utilizar paginação por cursor. Consulte a documentação de referência para detalhes dos parâmetros e formato de resposta: Retornando Recebíveis.

3. GET /core/v5/payables — Remoção de filtros

• O que muda: os filtros por amount e installments serão descontinuados.
• Impacto: requisições que utilizam esses filtros continuarão sendo aceitas, mas os filtros serão ignorados silenciosamente — a resposta retornará como se eles não tivessem sido enviados.
• Ação necessária: remova os filtros amount e installments das suas requisições. Caso precise filtrar por esses critérios, faça a filtragem no lado da sua aplicação após receber a resposta.

4. GET /core/v5/payables — Descontinuação de campos

• O que muda: os campos abaixo deixarão de ser preenchidos no response (retornarão null) para recebíveis criados após o fim da janela de deprecação.
  • liquidation_arrangement_id
  • bulk_anticipation_id
  • gateway_id
• Impacto: integrações que dependem desses campos para reconciliação, vinculação ou rastreabilidade perderão essas referências para novos recebíveis. Recebíveis criados antes do fim da janela mantêm os valores preenchidos.
• Ação necessária: revise sua lógica de reconciliação e remova as dependências desses campos. Esses campos não terão substitutos.

5. GET /core/v5/payables — Adição de campos e novos movimentos da Agenda de recebíveis

• **O que muda: **com a descontinuação da entidade de balance_operations (Operações de Saldo), será fornecido uma visão completa da Agenda de recebíveis através de uma única entidade: payables (Recebíveis).
  Com essa mudança, o campo originator_model, que retorna o tipo de operação que gerou o recebível quando o mesmo foi gerado por uma operação diferente de transação, passará a retornar além dos 2 valores possíveis atualmente (refund e chargeback) mais outros 4, sendo eles: ownership_assignment (Cessão de Recebíveis), cross_balance (Balanceamento de Saldo), guarantee (Garantia de Recebíveis) e financial_adjustment (Ajustes Financeiros na Agenda).
  O response contará com um novo campo informando o settlement_id para viabilizar conciliação com consultas em GET /core/v5/settlements, mais informações em Objeto Settlements. Além da adição do campo payment_profile_id para conciliar novos Recebedores, mais informações na página Liquidação e Recebedores no item 4.
• **Impacto: **retorno de 6 valores possíveis em originator_model, sendo 4 novos, e adição dos campos settlement_id e payment_profile_id.
• **Ação necessária: **revise sua integração para suportar os novos valores de originator_model retornando no response e considere o direcionamento do item 8. GET /core/v5/balance/operations para avaliar impactos no fluxo conciliatório.
• Exemplos

{
    "id": "7c2a91e4b8f05d3619ac78b2f4e5c0d8a91b6e2f7c3d54a8b019f6e3c7d2a94b",
    "status": "paid",
    "amount": -4320,
    "fee": 0,
    "anticipation_fee": 0,
    "fraud_coverage_fee": 0,
    "installment": null,
    "gateway_id": null,
    "split_id": null,
    "recipient_id": null,
    "payment_profile_id": "pp_4h8dxst2c9nyv615jbewql3fp",
        "originator_model": "ownership_assignment",
    "originator_model_id": "7823044",
    "payment_date": "2026-07-15T03:00:00Z",
    "original_payment_date": "2026-08-20T03:00:00Z",
    "type": "credit",
    "payment_method": null,
    "accrual_at": "2026-07-14T22:15:03Z",
    "created_at": "2026-07-15T12:30:47Z"
}

{
    "id": "3f8b1e9c47a52d016b8fc39e2a74d5089b1e6c3f7a4d92b58c07e1f6a3d4b295",
    "status": "paid",
    "amount": -890,
    "fee": 0,
    "anticipation_fee": 0,
    "fraud_coverage_fee": 0,
    "installment": null,
    "gateway_id": null,
    "split_id": null,
    "recipient_id": null,
    "payment_profile_id": "pp_7m2kzqx4b9nyv518jhewrl6cd",
    "originator_model": "cross_balance",
    "originator_model_id": "8190332",
    "payment_date": "2026-05-10T03:00:00Z",
    "original_payment_date": "2026-05-10T03:00:00Z",
    "type": "credit",
    "payment_method": null,
    "accrual_at": "2026-05-09T14:42:19Z",
    "created_at": "2026-05-10T09:11:55Z"
}

{
    "id": "e1a94b7f3c86d052914bef780a2c5d3671e9f2b48c15a63d907f4e2b8a1c6d53",
    "status": "paid",
    "amount": -27500,
    "fee": 0,
    "anticipation_fee": 0,
    "fraud_coverage_fee": 0,
    "installment": null,
    "gateway_id": null,
    "split_id": null,
    "recipient_id": null,
    "payment_profile_id": "pp_3f9pdst6c1nybw24jkexql8ma",
    "originator_model": "guarantee",
    "originator_model_id": "9004517",
    "payment_date": "2026-09-01T03:00:00Z",
    "original_payment_date": "2026-10-15T03:00:00Z",
    "type": "credit",
    "payment_method": null,
    "accrual_at": "2026-08-31T20:58:44Z",
    "created_at": "2026-09-01T14:05:32Z"
}

{
    "id": "b6d0e2a91c47f83506d1e9b2a875c4f30e6b1a7d928f4c05e3b7a1d68f2c9e04",
    "status": "paid",
    "amount": -60,
    "fee": 0,
    "anticipation_fee": 0,
    "fraud_coverage_fee": 0,
    "installment": null,
    "gateway_id": null,
    "split_id": null,
        "recipient_id": null,
    "payment_profile_id": "pp_5h1dxsw8c3nzv672jbfrql9kp",
    "originator_model": "financial_adjustment",
    "originator_model_id": "9218763",
    "payment_date": "2026-06-05T03:00:00Z",
    "original_payment_date": "2026-06-30T03:00:00Z",
    "type": "credit",
    "payment_method": null,
    "accrual_at": "2026-06-04T11:33:08Z",
    "created_at": "2026-06-05T08:20:16Z"
}

6. Identificador de payables — Mudança no tipo e formato do id

• O que muda: mudança no tipo e no formato do id de payable retornado, que passa de int para string, conforme exemplos abaixo.
  • Antes (int): 9102837456
  • Depois (string): bdb119f99012997b01300f60a1c5ec872c6f08902fb03f29a0739f07229bbf60
• Impacto: sistemas que dependem do padrão atual (ex.: parse numérico, colunas de banco de dados do tipo inteiro, tamanho fixo, validações por regex) precisarão ser atualizados. Atenção especial para armazenamento: o novo formato tem 64 caracteres e exige um campo do tipo texto com capacidade suficiente.
• Ação necessária: ajuste sua integração para tratar o id como string, sem depender de tipo numérico, tamanho fixo ou padrão específico, lembrando que os dois formatos podem coexistir durante a transição.

7. GET /core/v5/payables/{payable_id} — Endpoint descontinuado

• O que muda: o endpoint será descontinuado.
• Impacto: consultas a esse endpoint deixarão de retornar resultados.
• Ação necessária: utilize o endpoint de listagem GET /core/v5/payables aplicando filtro pelo id do recebível desejado.

8. GET /core/v5/balance/operations — Endpoint descontinuado

• O que muda: o endpoint será descontinuado. Novos dados não serão retornados.
• Impacto: integrações que dependem desse endpoint para consultar o histórico de operações de balance precisam migrar para os endpoints específicos por entidade.
• Ação necessária: migre para os endpoints correspondentes a cada tipo de operação:

9. GET /core/v5/balance/operations/{balance_operation_id} — Endpoint descontinuado

• O que muda: o endpoint será descontinuado. Novos dados não serão retornados.
• Impacto: consultas individuais a operações de balance deixarão de retornar resultados.
• Ação necessária: mesmas orientações do item 8. GET /core/v5/balance/operations.

Perguntas frequentes das mudanças no Financeiro

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

Como obter histórico de Recebíveis pagos com mais de 24 meses?

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.

Recebíveis em aberto ou futuros também serão limitados aos 24 meses?

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.

Posso continuar usando offset na consulta de Recebíveis durante a janela de deprecação?

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.

Minha integração na rota de Recebíveis depende de liquidation_arrangement_id, bulk_anticipation_id e gateway_id. O que faço?

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.

O novo campo settlement_id na rota de Recebíveis estará presente em todos objetos do retorno?

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.

Os novos valores de originator_model (ownership_assignment, cross_balance, etc.) na rota de Recebíveis quebrarão minha integração?

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.

Posso usar GET /core/v5/payables/{payable_id} para consultar um recebível específico?

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.

Os endpoints GET /core/v5/balance/operations e GET /core/v5/balance/operations/{id} serão descontinuados. Onde busco esses dados agora?

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 de mapeamento no item 8 dessa página para mais detalhes.