[Fábio Rodrigues (FabioMR)]

A Barte vai descontinuar os endpoints atuais de estorno e substituí-los pelo novo fluxo: um endpoint só para estorno total e parcial, assíncrono e com idempotência.

O que muda

• create_refund(charge_id, amount, idempotency_key): chama POST /v2/charges/{uuid}/refunds com o header x-idempotency-key.
  • Devolve um ChargeRefund, normalmente em PROCESSING. O resultado final vem em Charge.refunds ou no webhook do domínio CHARGE.
  • Repetir a chamada com a mesma chave e o mesmo valor devolve o mesmo estorno.
  • Valor com mais de duas casas decimais é recusado, e não arredondado.
• Charge.refunds: a lista de estornos que o GET /v2/charges/{uuid} já devolvia e o SDK descartava.
  • Todos os campos de ChargeRefund são opcionais, porque itens antigos vêm sem uuid e sem idempotencyKey.
  • O campo entra como argumento nomeado (kw_only=True, default None), para não quebrar os construtores de Charge e PixCharge, inclusive as chamadas por posição.
• _request aceita headers por requisição. A chave de idempotência não pode ir para os headers da sessão, que é compartilhada entre chamadas.
• refund_charge, partial_refund_charge, get_refund e Charge.refund passam a emitir DeprecationWarning, sem remoção. O estorno parcial feito pelo fluxo antigo só aparece no GET /v2/charges/partial-refund/{id}, então esses métodos ainda são necessários durante a transição.

O status HTTP de um erro, por exemplo o 409 de conflito de idempotência, está em BarteError.response.status_code.

Testes

• Casos novos em tests/test_client.py, com payloads reais do sandbox. Os testes antigos de estorno passam a conferir o aviso de depreciação.
• Contrato validado no sandbox da Barte: 202, repetição idempotente, 409 BAR-0466 e 400 BAR-0451.

Depois do merge, a versão sai como v0.16.0.

[Copilot]

🟡 Changes recommended

O novo campo obrigatório quebra a compatibilidade dos construtores públicos de Charge e PixCharge.

1 open finding

• Tornar refunds opcional e somente nomeado nos construtores públicos · New

What changed in this PR

Adiciona ao SDK o novo fluxo assíncrono de estorno da Barte, mantendo os métodos legados durante a transição.

Alterações:

• Introduz create_refund com chave de idempotência por requisição.
• Expõe estornos em Charge.refunds e exporta ChargeRefund.
• Adiciona avisos de depreciação e testes do novo fluxo.

File	Description
tests/​test_client.py	Testa estornos, validação, conflito e depreciação.
barte/​models.py	Adiciona ChargeRefund e Charge.refunds.
barte/​client.py	Implementa o endpoint e headers por requisição.
barte/​__init__.py	Exporta ChargeRefund.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.