Como enviar evidências de disputa (MED) usando a API de arquivos

Ao responder ou contestar uma disputa (MED), você pode anexar documentos que sirvam como evidência do seu argumento.

Agora é possível enviar esses documentos diretamente pela API de arquivos da Woovi, sem precisar hospedar o arquivo em uma URL pública.

Para enviar uma evidência dessa forma, siga os passos abaixo:

1. Obtenha o id da disputa

Crie um webhook para o evento OPENPIX:DISPUTE_CREATED. No payload desse evento você encontra o id da disputa.

{
  "event": "OPENPIX:DISPUTE_CREATED",
  "dispute": {
    "status": "<status>",
    "endToEndId": "<endToEndId>",
    "id": "<idDaDisputa>"
  }
}

2. Envie o arquivo para a API de arquivos

Faça uma requisição para o endpoint de upload de arquivos, enviando o documento como multipart/form-data.

Campos da requisição:

• file — o arquivo a ser enviado (PDF, PNG ou JPEG)

• purpose — deve ser DISPUTE_EVIDENCE

• correlationID — opcional. Um identificador seu para evitar que o mesmo arquivo seja enviado duas vezes

curl -X POST "https://api.woovi.com/api/v1/files" \
  -H "Authorization: <appID>" \
  -F "purpose=DISPUTE_EVIDENCE" \
  -F "file=@/caminho/do/arquivo.pdf"

A resposta traz o id do arquivo, que será usado no próximo passo:

{
  "file": {
    "id": "<idDoArquivo>",
    "fileName": "arquivo.pdf",
    "contentType": "application/pdf",
    "size": 10240,
    "url": "<urlAssinada>",
    "urlExpiresAt": "<data>",
    "createdAt": "<data>"
  }
}

3. Envie a evidência para a disputa usando o id do arquivo

Com o id retornado no passo anterior, faça a requisição para anexar o documento à disputa:

curl -X POST "https://api.woovi.com/api/v1/dispute/<idDaDisputa>/evidence" \
  -H "Authorization: <appID>" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "documents": [
      {
        "fileId": "<idDoArquivo>",
        "description": "<descrição>",
        "correlationID": "<correlationID>"
      }
    ]
  }'

Esse recurso depende da funcionalidade DISPUTE_EVIDENCE_FILE_ID estar habilitada na sua conta. Caso não esteja, a requisição retorna erro 403 e você pode enviar o documento por url ou falar com o suporte para habilitar.

4. Entendendo o retorno

Se tudo ocorrer corretamente, você recebe um código 200 com os dados da evidência registrada:

{
  "documents": [
    {
      "url": "<urlParaVisualizarDocumento>",
      "fileId": "<idDoArquivo>",
      "description": "<descrição>",
      "correlationID": "<correlationID>",
      "createdAt": "<data>"
    }
  ]
}

5. Tipos de arquivo aceitos

Para evidências de disputa, são aceitos os formatos PDF, PNG e JPEG. Outros formatos enviados para a API de arquivos são recusados com erro 415.

6. Erros comuns

• 403 DISPUTE_EVIDENCE_FILE_ID_NOT_ALLOWED — sua conta não tem a funcionalidade habilitada para enviar evidência por fileId. Fale com o suporte.

• 415 — o tipo do arquivo enviado não é aceito.

• 413 — o arquivo enviado é maior do que o limite permitido.