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.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.
200 OK, com o id do arquivo:
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 arrayanswer aceita attachments, um array com os ids dos arquivos daquela questão.
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 emexpiresAt. 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.
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.