Pular para o conteúdo principal

Arquivos e processamento assíncrono

O upload de arquivos usa uma autorização curta para o armazenamento de objetos. A API mantém o registro e verifica o acesso antes de emitir as URLs. O consumidor não recebe uma credencial permanente do bucket.

Enviar um arquivo​

  1. Chame POST /api/v1/files com module, mime, size_bytes e, quando previsto, checksum.
  2. Guarde id, code, storage_key, put_url, expires_in e headers da resposta.
  3. Envie os bytes por PUT diretamente para put_url, com os headers retornados.
  4. Chame POST /api/v1/files/{file_id}/complete, usando o código público.
  5. Associe o arquivo ao recurso pelo endpoint de domínio correspondente.

A criação exige files.objects.write. O módulo, MIME e tamanho passam pela allowlist de upload. O registro no banco, sozinho, não significa que os bytes foram enviados. A confirmação verifica o objeto e suas propriedades.

Ler e remover​

GET /api/v1/files/{file_id} retorna metadados. GET /api/v1/files/{file_id}/url retorna uma URL de download com expiração. As duas leituras exigem files.objects.read e o escopo de organização.

DELETE /api/v1/files/{file_id} exige escrita e remove o registro e o objeto pelo fluxo implementado. Antes de apagar, respeite as regras do documento ou evidência que referencia o arquivo. Alguns módulos possuem endpoints próprios de anexos e não devem ser substituídos pelo fluxo genérico.

URLs assinadas são autorizações temporárias. Não as inclua em logs públicos ou as utilize como identificador permanente. Quando expirarem, solicite uma nova pela API.

Eventos, outbox e notificações​

Eventos de domínio descrevem fatos reconhecidos pela aplicação. A outbox permite que o worker execute efeitos posteriores à transação. Webhooks são uma projeção externa dos tipos de evento habilitados. Auditoria mantém a trilha de ações. Notificações formam a caixa de entrada de uma pessoa.

Esses mecanismos têm finalidades diferentes. A existência de uma notificação não prova entrega de e-mail, e uma linha de outbox não prova que o destinatário recebeu a mensagem.

Atualização da interface​

O módulo de notificações oferece streaming SSE por ticket emitido para o contexto da sessão. Não coloque a chave de API na URL de um stream e não trate a caixa de entrada humana como um barramento genérico de integração. Algumas rotas de notificações recusam explicitamente atores api_key.

Para integrar eventos de negócio entre servidores, prefira o catálogo de webhooks e acompanhe os estados das operações assíncronas.