Como fazer upload de um arquivo?

O endpoint de arquivos guarda um arquivo na Woovi e devolve os metadados dele junto com uma URL de download temporária. Use esse arquivo em outras APIs da Woovi que consomem documentos, como a evidência de uma disputa ou o comprovante de um pedido de aumento de limite, sem precisar hospedar o arquivo por conta própria.

O purpose diz qual é esse uso, e cada API só aceita o purpose dela: um arquivo subido como DISPUTE_EVIDENCE não serve num pedido de limite, e vice-versa.

purpose	Usado por
DISPUTE_EVIDENCE	Evidência de disputa
ACCOUNT_LIMIT_REQUEST	Pedido de aumento de limite
ACCOUNT_REGISTER_DOCUMENT	Onboarding KYC 100% via API: documentos da empresa, dos sócios e respostas de RFI

Requisitos

• Um AppID com o escopo FILE_POST (como adicionar escopos).
• Um arquivo por requisição, de até 10 MiB (10485760 bytes).
• Content type entre application/pdf, image/png, image/jpeg e image/webp. Os bytes iniciais do arquivo precisam bater com o content type declarado.

1. Fazer a requisição

O arquivo é enviado como multipart/form-data no campo file, junto com o purpose, que descreve para que o arquivo serve.

curl -X POST "https://api.woovi.com/api/v1/files" \
  -H "Authorization: <appID>" \
  -F "file=@evidence.png" \
  -F "purpose=DISPUTE_EVIDENCE" \
  -F "correlationID=evidence-2026-08-1042"

Campo	Obrigatório	Descrição
file	Sim	O arquivo em si.
purpose	Sim	Para que o arquivo será usado. Aceita DISPUTE_EVIDENCE, ACCOUNT_LIMIT_REQUEST e ACCOUNT_REGISTER_DOCUMENT.
correlationID	Não	Seu identificador para o upload. Quando não enviado, um UUID é gerado para você.

2. Entendendo o retorno

Um upload novo responde 201:

{
  "file": {
    "id": "6712c2ac7c2f1e0012a4b8d1",
    "correlationID": "evidence-2026-08-1042",
    "purpose": "DISPUTE_EVIDENCE",
    "fileName": "evidence.png",
    "contentType": "image/png",
    "size": 20480,
    "url": "https://woovi-files.s3.amazonaws.com/company/6712c1f07c2f1e0012a4b8c9/dispute_evidence/6712c2ac7c2f1e0012a4b8d1?X-Amz-Signature=...",
    "urlExpiresAt": "2026-08-22T15:30:00.000Z",
    "createdAt": "2026-08-22T14:30:00.000Z"
  }
}

A url é pré-assinada e para de funcionar em urlExpiresAt. Peça o arquivo novamente para obter uma URL nova.

Repetindo a requisição com segurança

Quando você envia um correlationID, repetir a requisição com o mesmo correlationID e o mesmo purpose devolve o arquivo já armazenado com status 200, em vez de subir uma segunda cópia. Isso torna o envio seguro para retentativa.

Sem correlationID, cada chamada gera um novo arquivo.

Erros

Código	Quando acontece
400	purpose desconhecido, correlationID vazio, campo file ausente ou mais de um arquivo enviado.
401	Credenciais ausentes ou inválidas.
403	A aplicação não tem o escopo FILE_POST.
413	Arquivo maior que o tamanho máximo aceito.
415	Content type fora da lista permitida, ou bytes iniciais que não batem com o content type declarado.
502	O arquivo não pôde ser armazenado. A requisição pode ser repetida.

O corpo do erro traz a mensagem no idioma da empresa que fez a requisição (pt-BR, en ou es):

{
  "error": "Invalid value for the field purpose"
}

Usando o arquivo em outra API

Pegue o file.id do retorno e envie no campo correspondente da API que vai consumir o documento. Para disputas, ele vai no fileId de cada item de documents em POST /api/v1/dispute/{id}/evidence — veja Como adicionar uma nova evidência em uma disputa?.

Casos de Uso

• Envio de evidências de disputa