Skip to main content
Atualiza um dispute com merge: o que você manda em evidence e metadata é combinado com o que já existe, campo a campo, sem apagar o resto. Esse mesmo endpoint serve pra duas coisas — montar a defesa aos poucos (com submit: false) e efetivamente enviá-la pra análise. A defesa inteira vive nos campos nomeados de evidence. Campos de arquivo recebem o ID de um file (file_*) enviado antes com POST /v1/files e purpose=dispute_evidence — veja Criar arquivo; campos de texto recebem string livre. Pra limpar um campo — de texto ou de arquivo —, envie string vazia (""). O catálogo completo dos 27 campos, com a descrição de cada um, está na visão geral do dispute.
Um request que contém a chave evidence envia a defesa por padrão: submit assume true quando omitido. Enquanto estiver montando a defesa em várias chamadas, mande submit: false explicitamente em cada uma — só a última, a do envio, vai sem submit (ou com submit: true). Um request sem a chave evidence nunca envia a defesa.

​
O que precisa estar pronto antes do envio funcionar

O envio (submit efetivo true) só é aceito se todas essas condições forem verdadeiras:
  • O dispute não pode já estar fechado (status diferente de won, lost e warning_closed).
  • O prazo em evidence_details.due_by ainda não pode ter passado — isso é checado contra o relógio no momento da chamada, não contra o valor já salvo em evidence_details.past_due.
  • Precisa haver pelo menos um campo de arquivo de evidence preenchido — considerando o merge deste próprio request. Só texto não é suficiente pro envio passar.
  • A defesa ainda não pode ter sido enviada (evidence_details.submission_count igual a 0) — o envio é único e irreversível.
A ordem dentro da chamada é sempre a mesma: primeiro o merge de evidence é aplicado, depois a defesa é enviada. Ou seja, um único request pode anexar o último arquivo e já enviar. Quando o envio é aceito, o dispute passa para under_review e evidence fica somente leitura.
Se o prazo termina com pelo menos um campo de arquivo preenchido e a defesa não enviada, a Chargefy envia a defesa automaticamente por você — o charge.dispute.updated reflete a mudança para under_review.

​
Validações e limites de evidence

Cada request com evidence é validado na hora — você nunca descobre um estouro só no fim:
  • Chave desconhecida em evidence é recusada com 400 e param: "evidence.<chave>". Só as 27 chaves do contrato existem.
  • Campo de arquivo precisa apontar pra um file existente, da organização atuante, com purpose=dispute_evidence e não excluído.
  • O mesmo file_* não pode ocupar dois campos da defesa — envie um upload por documento.
  • Limites somados dos arquivos preenchidos na defesa: até 10 páginas e 6,5 MB no total (PDF conta as páginas reais, medidas no upload; cada imagem conta 1 página). O 400 de estouro diz quanto ainda resta.
  • Limite somado dos campos de texto: até 150.000 caracteres no total.
​
string
obrigatório
ID do dispute (dp_*).
​
object
Campos nomeados da defesa. Faz merge por campo com o evidence que já existe — campos ausentes ficam como estão, campos enviados são sobrescritos e "" limpa o campo. Campos de texto: access_activity_log, billing_address, cancellation_policy_disclosure, cancellation_rebuttal, customer_email_address, customer_name, customer_purchase_ip, duplicate_charge_explanation, duplicate_charge_id, product_description, refund_policy_disclosure, refund_refusal_explanation, service_date, shipping_address, shipping_carrier, shipping_date, shipping_tracking_number e uncategorized_text. Campos de arquivo (valor file_* com purpose=dispute_evidence): cancellation_policy, customer_communication, customer_signature, duplicate_charge_documentation, receipt, refund_policy, service_documentation, shipping_documentation e uncategorized_file. A descrição de cada campo está na visão geral do dispute.
​
object
Pares chave-valor livres. Também faz merge com o metadata existente.
​
boolean
Se a defesa deve ser enviada pra análise nesta chamada. Quando o request contém evidence, o padrão é true — mande submit: false pra apenas preparar a defesa sem enviar. Num request sem evidence, submit é ignorado e nada é enviado. O envio só funciona com os requisitos acima satisfeitos; quando aceito, o dispute passa para under_review. O envio é único e irreversível.

​
(a) Montar a defesa sem enviar

Anexe arquivos e preencha textos quantas vezes precisar, sempre com submit: false:
cURL

​
(b) Limpar um campo preenchido

String vazia limpa o campo — vale pra texto e pra arquivo:
cURL

​
(c) Enviar a defesa

O request final pode completar os últimos campos e enviar na mesma chamada — com evidence presente, submit omitido já significa true:

​
Erros comuns