Skip to main content
API v2 Na v2, um arquivo nunca vai dentro do JSON de uma escrita. Você envia o arquivo antes, recebe o id do arquivo e passa esse id no endpoint que vai usar o anexo.

Como funciona o upload de arquivos?

O anexo acontece em duas etapas:
1

Envie o arquivo

POST /api/v2/attachment/upload, com o arquivo em multipart/form-data. A resposta traz o id do arquivo em id.
2

Use o id na escrita

No corpo JSON do endpoint de escrita, informe o id no campo de anexos, como attachments na importação de avaliação de checklist.
Cada chamada de upload recebe um arquivo e devolve um id. Para anexar vários arquivos, faça um upload por arquivo e junte os ids no array.

Etapa 1: envie o arquivo

O endpoint de upload é comum a todos os módulos e não pertence a nenhum deles: O corpo é multipart/form-data, com o arquivo na parte file: A referência, com playground, está em Enviar arquivo. O token vai no header Authorization, puro, como em qualquer chamada da v2. Não informe o Content-Type à mão: a biblioteca HTTP monta o multipart/form-data com o separador (boundary) certo.
O upload responde 200 OK, com o id do arquivo:
Guarde o id: é ele que liga o arquivo enviado ao registro da próxima etapa. Até ser usado ou expirar, uma hora depois do upload, o arquivo fica disponível e ocupa uma das 100 vagas descritas em Disponibilidade e o limite de 100.

Etapa 2: use o id na escrita

Informe os ids no campo de anexos do endpoint de escrita. Hoje, o endpoint que recebe anexos é a importação de avaliação de checklist: cada resposta do array answer aceita attachments, um array com os ids dos arquivos daquela questão.
Nesse exemplo, a resposta da questão 366 leva dois arquivos, enviados em dois uploads.

Disponibilidade e o limite de 100

Todo arquivo enviado nasce disponível. Ele deixa de estar disponível quando o id é usado em um endpoint de escrita, como a importação de avaliação, ou quando expira. Os disponíveis são os que aparecem na listagem de arquivos.

Quanto tempo tenho para usar o arquivo?

Uma hora a partir do upload. A listagem mostra o prazo de cada arquivo em expiresAt. Depois dele, o arquivo expira: fica indisponível para os endpoints de escrita, deixa de aparecer na listagem e libera a vaga no limite de 100. Para anexar o mesmo conteúdo, faça um upload novo e use o id novo. Por isso, faça o upload perto da escrita que vai usar o arquivo, e não horas antes.

Quantos arquivos disponíveis posso ter?

Até 100. Com 100 arquivos disponíveis, o upload responde erro e não devolve id novo. Para voltar a enviar, use os ids que já tem num endpoint de escrita, remova os disponíveis que não vai usar ou espere algum expirar: arquivo expirado não conta no limite. Na prática, isso pede duas cautelas:
  • Envie só o que vai usar logo. Não faça o upload de um lote grande “para depois”: cada id sem uso ocupa uma vaga.
  • Limpe o que ficou para trás. Se uma importação falhou depois dos uploads, os arquivos dela continuam disponíveis e ocupando vaga até expirar. Remova-os, ou reaproveite os ids ao reenviar a importação corrigida dentro do prazo.

Como listar os arquivos enviados?

GET /api/v2/attachment/list traz os arquivos disponíveis para uso nos endpoints de escrita, com o id, o nome, o tamanho em bytes (fileLength), a data do upload (uploadedAt) e a data de expiração (expiresAt, uma hora depois do upload), as duas em UTC. Arquivos já usados ou expirados não aparecem, então a listagem mostra exatamente os que ocupam vaga no limite. Não há filtros. A referência está em Listar arquivos.
A resposta é um array:

Como remover um arquivo?

DELETE /api/v2/attachment/remove, com o id do arquivo na query string, o mesmo devolvido pelo upload, remove um arquivo disponível e libera a vaga dele. A resposta é o status 200 sem corpo. Só arquivos disponíveis podem ser removidos: os já usados não. A referência está em Remover arquivo. O exemplo abaixo lista os disponíveis e remove os enviados há mais de 30 minutos, que dificilmente ainda serão usados. Os arquivos recentes ficam, porque podem ser de uma importação em andamento. Entre uma remoção e outra, a pausa de meio segundo respeita o limite de 2 requisições por segundo.

Erros do upload

O upload segue o contrato de erros da v2: 401 para token ausente ou inválido e 429 quando o limite de 2 requisições por segundo, por IP, é excedido. Com 100 arquivos disponíveis, ele também responde erro, até que você use ou remova algum deles, ou até algum expirar. Cada arquivo é uma requisição, então uma avaliação com muitos anexos consome o limite de requisições rápido: espace os uploads como numa varredura, descrita em Limites de requisição.

Próximos passos

Importar avaliação

O corpo completo da importação, com attachments em cada resposta.

Listar arquivos

Os arquivos disponíveis, com a data de expiração de cada um.

Remover arquivo

Libere vagas no limite de 100 removendo o que não vai usar.

Erros

O catálogo de falhas e como tratar cada uma.