Enviar defesa

POST/v1/disputes/:id/evidence

Trê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 OPEN para UNDER_ANALYSIS e dispara dispute.updated.
  • A resposta traz o arquivo registrado (sem o conteúdo) e a disputa atualizada.
Categorias de evidência
categoryO que éExemplos
TRANSACTION_RECEIPTComprovante da transaçãoComprovante do PIX, recibo, tela do pedido pago.
PROOF_OF_SHIPPINGComprovante de envioEtiqueta, nota de despacho, código de rastreio.
PROOF_OF_DELIVERYComprovante de entregaAssinatura no recebimento, foto da entrega, rastreio "entregue".
CUSTOMER_COMMUNICATIONConversas com o pagadorPrints de WhatsApp, e-mails, chat do suporte.
CUSTOMER_ACCOUNTCadastro do clienteTela do perfil na sua plataforma: dados, data e IP do cadastro, verificação.
DEPOSITS_WITHDRAWALSDepósitos e saques do clienteExtrato do cliente na sua plataforma.
INVOICENota fiscal ou faturaNF-e, fatura ou pedido do produto ou serviço.
TERMS_ACCEPTANCEAceite dos termosRegistro do aceite com data, hora e IP.
USAGE_LOGSRegistros de usoLogs de acesso, ativação de licença, consumo do serviço.
OTHEROutro materialQualquer coisa que mostre que a compra foi legítima.

Defesa estruturada

POST/v1/disputes/:id/defense

Os 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: 201 com version, savedAt e changed: true. A mesma defesa de novo: 200 com changed: false, sem versão nova. Por isso não precisa de Idempotency-Key.
  • A primeira defesa precisa de ao menos um campo preenchido.

Explicação da empresa

PATCH/v1/disputes/:id/comment

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

Explicação
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ódigos de erro
CódigoHTTPQuando acontece
DISPUTE_EVIDENCE_CLOSED409Passou o evidenceDueAt: a disputa não aceita mais material.
CONFLICT409A disputa já foi decidida, ou já tem o máximo de arquivos.
VALIDATION_ERROR422Arquivo 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_REQUIRED400Evidência sem Idempotency-Key.
IDEMPOTENCY_KEY_REUSED409A Idempotency-Key já foi usada com outro arquivo.
NOT_FOUND404A disputa não existe nesta empresa e neste ambiente.
API_KEY_SCOPE403A 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.