Carregar arquivos
O carregamento ocorre em três etapas: solicitar um endereço de upload, enviar o arquivo e confirmar o documento. Um endereço de upload pode ser gerado uma única vez e permanece válido por até 1 hora.
1. Solicite um endereço de upload
Seção intitulada “1. Solicite um endereço de upload”POST /api/v1/upload/presignX-API-Key: sk_your_keyContent-Type: application/json{ "filename": "report.docx", "file_size": 45678}| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
filename | string | ✅ | Nome do arquivo; o servidor determina o tipo de arquivo pela extensão |
file_size | inteiro | ✅ | Tamanho exato em bytes, maior que 0 |
mime_type | string | — | Opcional; o servidor não o utiliza |
Resposta:
{ "document_id": "4q8mx2q9z1k7p6ra", "upload_url": "https://upload.example/...", "upload_headers": { "Content-Type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "If-None-Match": "*" }, "finalize_token": "short_lived_token", "expires_in": 3600}2. Envie o arquivo
Seção intitulada “2. Envie o arquivo”Envie um PUT para upload_url com os bytes do arquivo bruto como corpo e envie cada cabeçalho em upload_headers exatamente conforme fornecido.
# UPLOAD_URL and UPLOAD_CONTENT_TYPE come from upload_url and upload_headers["Content-Type"] in the previous responsecurl --fail-with-body -X PUT "$UPLOAD_URL" \ -H "Content-Type: $UPLOAD_CONTENT_TYPE" \ -H "If-None-Match: *" \ --upload-file "report.docx"Não envie sua chave API OmniDoc nesta etapa. Se o endereço expirar ou a transferência falhar, solicite uma nova.
3. Confirme o documento
Seção intitulada “3. Confirme o documento”POST /api/v1/upload/finalizeX-API-Key: sk_your_keyContent-Type: application/json{"finalize_token":"short_lived_token"}Em caso de sucesso, o documento é retornado:
{ "document": { "id": "4q8mx2q9z1k7p6ra", "basename": "report.docx", "file_size": 45678, "mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "created_at": "2026-10-01T12:00:00Z" }}Somente após a confirmação o documento entra na biblioteca de arquivos e passa a estar disponível para uso em trabalhos.
Nomes de arquivos
Seção intitulada “Nomes de arquivos”filename é apenas para exibição; não o utilize como um caminho ou identificador exclusivo. O servidor substitui caracteres ilegais e gera um nome de download seguro para nomes que sejam muito longos.
| Status | Causa |
|---|---|
400 | Nome ou tamanho do arquivo inválido, ou o tamanho enviado difere do solicitado |
401 | Credencial ou finalize_token inválida ou expirada |
403 | O finalize_token pertence a outra conta |
410 | O arquivo carregado não foi encontrado (transferência incompleta ou endereço expirado); solicite um novo endereço |
413 | Excede o limite de tamanho por arquivo |
415 | Formato não suportado ou o conteúdo não corresponde à extensão |
422 | O arquivo Office está danificado ou estruturalmente inseguro |
429 | Uploads em excesso |
503 | O serviço de envio está temporariamente indisponível; tente novamente mais tarde |