Enviar defesa
POST/v1/disputes/:id/evidenceTrês formas de responder a uma disputa, que se somam: arquivos de evidência, a defesa estruturada e a sua explicação. Valem enquanto a disputa está viva (OPEN ou UNDER_ANALYSIS) e antes de evidenceDueAt. Escopo da chave: disputes em write.
Evidências
Um arquivo por chamada, em multipart/form-data, com Idempotency-Key. A chave compara a disputa e a impressão do arquivo (sha256, tamanho e nome) com a categoria e a descrição: o mesmo arquivo de novo devolve a resposta guardada sem criar outro; outro arquivo com a mesma chave é 409 IDEMPOTENCY_KEY_REUSED.
filearquivoobrigatórioPDF, PNG ou JPEG, até 10 MB. O tipo é conferido pelos bytes, não pelo nome.categorytextoopcionalO que o arquivo prova (tabela abaixo). Padrão: OTHER.descriptiontextoopcionalUma linha sobre o arquivo, até 300 caracteres.
- Até 20 arquivos por disputa.
- A primeira evidência leva a disputa de
OPENparaUNDER_ANALYSISe disparadispute.updated. - A resposta traz o arquivo registrado (sem o conteúdo) e a disputa atualizada.
| category | O que é | Exemplos |
|---|---|---|
TRANSACTION_RECEIPT | Comprovante da transação | Comprovante do PIX, recibo, tela do pedido pago. |
PROOF_OF_SHIPPING | Comprovante de envio | Etiqueta, nota de despacho, código de rastreio. |
PROOF_OF_DELIVERY | Comprovante de entrega | Assinatura no recebimento, foto da entrega, rastreio "entregue". |
CUSTOMER_COMMUNICATION | Conversas com o pagador | Prints de WhatsApp, e-mails, chat do suporte. |
CUSTOMER_ACCOUNT | Cadastro do cliente | Tela do perfil na sua plataforma: dados, data e IP do cadastro, verificação. |
DEPOSITS_WITHDRAWALS | Depósitos e saques do cliente | Extrato do cliente na sua plataforma. |
INVOICE | Nota fiscal ou fatura | NF-e, fatura ou pedido do produto ou serviço. |
TERMS_ACCEPTANCE | Aceite dos termos | Registro do aceite com data, hora e IP. |
USAGE_LOGS | Registros de uso | Logs de acesso, ativação de licença, consumo do serviço. |
OTHER | Outro material | Qualquer coisa que mostre que a compra foi legítima. |
Defesa estruturada
POST/v1/disputes/:id/defenseOs dados do cliente na sua plataforma, a atividade dele e a entrega, num JSON { "defense": { … } }. Tudo é opcional e vai como texto (contagens também); o que vier precisa ser válido. Cada envio diferente vira uma versão nova e vale a mais recente: mande sempre a defesa inteira, não só o que mudou.
customer.platformIdtextoopcionalO id do cliente no seu sistema, até 120 caracteres.customer.signupDatedataopcionalQuando ele se cadastrou, "AAAA-MM-DD", sem data futura.customer.nametextoopcionalNome do cliente, até 160 caracteres.customer.documenttextoopcionalCPF ou CNPJ, conferido, numa disputa em BRL.customer.email · customer.phonetextoopcionalE-mail válido; telefone com DDI e DDD.customer.signupIptextoopcionalIP do cadastro, IPv4 ou IPv6.customer.kyc · customer.kycDatetextoopcional"YES" ou "NO": você verificou a identidade dele? A data só com "YES".activity.depositsCount · withdrawalsCounttextoopcionalQuantos depósitos e saques ele fez na sua plataforma, número inteiro em texto ("12").activity.depositsTotal · withdrawalsTotaltextoopcionalSomas na moeda da disputa: "1800.00" ou "1.800,00".activity.firstActivityDate · lastActivityDatedataopcionalPrimeira e última atividade; a última não vem antes da primeira.delivery.producttextoopcionalO que foi entregue, até 200 caracteres.delivery.deliveredDate · trackingCodetextoopcionalData da entrega e código de rastreio (até 80 caracteres).delivery.confirmationtextoopcionalComo a entrega foi confirmada, até 500 caracteres, com quebras de linha.summarytextoopcionalO resumo da defesa nas suas palavras, até 4.000 caracteres, com quebras de linha.
- Versão nova:
201comversion,savedAtechanged: true. A mesma defesa de novo:200comchanged: false, sem versão nova. Por isso não precisa deIdempotency-Key. - A primeira defesa precisa de ao menos um campo preenchido.
Explicação da empresa
PATCH/v1/disputes/:id/commentUm texto livre, de 5 a 2.000 caracteres, em { "comment": "…" }. Substitui a explicação anterior e responde com comment (text e at) e changed; o mesmo texto de novo vem com changed: false e não grava nada.
curl -X PATCH https://api.averopay.io/v1/disputes/dsp_2Lm7Qx4Rt9Kd/comment \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{"comment":"A cliente usou a licença por 5 dias antes de abrir o MED."}'Erros
| Código | HTTP | Quando acontece |
|---|---|---|
DISPUTE_EVIDENCE_CLOSED | 409 | Passou o evidenceDueAt: a disputa não aceita mais material. |
CONFLICT | 409 | A disputa já foi decidida, ou já tem o máximo de arquivos. |
VALIDATION_ERROR | 422 | Arquivo que não é PDF, PNG ou JPEG, maior que 10 MB, categoria desconhecida ou campo da defesa inválido; error.details aponta cada campo. |
IDEMPOTENCY_KEY_REQUIRED | 400 | Evidência sem Idempotency-Key. |
IDEMPOTENCY_KEY_REUSED | 409 | A Idempotency-Key já foi usada com outro arquivo. |
NOT_FOUND | 404 | A disputa não existe nesta empresa e neste ambiente. |
API_KEY_SCOPE | 403 | A chave não tem write em disputes. |
Tudo o que você manda aparece no painel como enviado pela API, com o nome da chave. A defesa leva dados pessoais do seu cliente: mande só o que ajuda a provar a compra.
Antes de enviar
Confira o prazo e a força da defesa em GET /v1/disputes/:id (evidenceOpen, evidenceDueAt e strength). O ciclo da disputa está em Como funciona a MED.