Arquivos

Os arquivos são os anexos do atendimento: prints, logs, documentos. O upload vai para o provedor de armazenamento do workspace (workspaceStorageId configurado na instância) e o registro fica na instância, pronto para ser vinculado a tickets e threads pelo atributo fileIds.

O recurso existe nos dois domínios, com escopos diferentes: o staff lista e gerencia todos os arquivos da instância, enquanto o cliente só enxerga e remove os próprios uploads — arquivos de terceiros retornam 404 Not Found.

Headers obrigatórios

Todas as requisições devem incluir o header X-Helpdesk-Id (UUID) e Authorization: Bearer {token} — token do agente na área de staff, token do cliente no portal.

---

Estrutura de Dados Principal

Campo	Tipo	Descrição
id	Number	Identificador do arquivo.
name	String	Nome original do arquivo.
hash	String	Hash do arquivo no storage.
extension	String	Extensão do arquivo.
size	Number	Tamanho em bytes.
mime	String	Tipo MIME.
url	String	URL pública do arquivo no storage.
helpdeskUserId / helpdeskAgentId	Number	Autor do upload (cliente ou agente).

Upload

O upload é feito em multipart/form-data, no campo file, com as seguintes restrições:

Restrição	Valor
Tamanho máximo	10 MB
Extensões permitidas	pdf, doc, docx, txt, md, png, jpg, jpeg, webp, zip

Storage obrigatório

Se a instância não tiver um provedor de armazenamento vinculado (workspaceStorageId), o upload falha com 422 ("Nenhum provedor de armazenamento configurado").

Fluxo recomendado para anexar arquivos a uma conversa:

1. Faça o upload de cada arquivo (POST .../files) e guarde os ids retornados.
2. Envie os IDs em fileIds ao criar o ticket ou a thread — os vínculos são criados na mesma transação da mensagem.

---

Endpoints do Staff

Listar Arquivos

Lista os arquivos da instância, com paginação e filtros por autor.

GET /v1/helpdesk/agent/files

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
page	number	Não	O número da página (mínimo: 1).
perPage	number	Não	Itens por página (entre 1 e 100, padrão: 25).
helpdeskUserId	number	Não	Filtra uploads de um cliente.
helpdeskAgentId	number	Não	Filtra uploads de um agente.
orderBy	string	Não	Campo de ordenação: id, name ou createdAt.
orderDirection	string	Não	Direção: asc ou desc.

Respostas

200 OK

Retorna um objeto de paginação contendo a lista de arquivos.

Enviar Arquivo

POST /v1/helpdesk/agent/files

Exemplo de Requisição

curl -X POST "https://api.us.basis.tavares.in/v1/helpdesk/agent/files" \
  -H "X-Helpdesk-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -F "file=@/caminho/para/print-erro.png"

Respostas

201 Created

Retorna o ID e a URL do arquivo — use o id em fileIds de tickets e threads.

{
  "id": 4,
  "url": "https://s3.sa-east-1.amazonaws.com/tavares-dev/files/7af7ff84-4b0e-4ee8-becb-308d88dc7997.png"
}

Obter Arquivo por ID

GET /v1/helpdesk/agent/files/:id

Respostas

200 OK

Retorna os dados do arquivo.

404 Not Found

Ocorre quando o arquivo não existe na instância.

Remover Arquivo

Remove o registro do arquivo (exclusão lógica). Se o provedor de storage tiver destroyOnDelete ativo, o arquivo físico também é removido.

DELETE /v1/helpdesk/agent/files/:id

Respostas

204 No Content

Remoção concluída com sucesso.

---

Endpoints do Cliente

Mesmas operações da área de staff, sob /v1/helpdesk/customer/files, com duas diferenças de escopo:

• Listar (GET) retorna apenas os uploads do próprio cliente — sem filtros por autor.
• Obter (GET /:id) e remover (DELETE /:id) retornam 404 Not Found para arquivos de outros autores.

GET /v1/helpdesk/customer/files
POST /v1/helpdesk/customer/files
GET /v1/helpdesk/customer/files/:id
DELETE /v1/helpdesk/customer/files/:id

Parâmetros de Query (listagem)

Nome	Tipo	Obrigatório	Descrição
page	number	Não	O número da página (mínimo: 1).
perPage	number	Não	Itens por página (entre 1 e 100, padrão: 25).
orderBy	string	Não	Campo de ordenação: id, name ou createdAt.
orderDirection	string	Não	Direção: asc ou desc.