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