Saltearse al contenido

Subir archivos

La carga se realiza en tres pasos: solicitar una dirección de carga, enviar el archivo y confirmar el documento. Una dirección de carga puede generarse una sola vez y permanece válida hasta por 1 hora.

POST /api/v1/upload/presign
X-API-Key: sk_your_key
Content-Type: application/json
{
"filename": "report.docx",
"file_size": 45678
}
CampoTipoObligatorioDescripción
filenamecadena✅Nombre de archivo; el servidor determina el tipo de archivo a partir de la extensión
file_sizeentero✅Tamaño exacto en bytes, mayor que 0
mime_typecadena—Opcional; el servidor no lo utiliza

Respuesta:

{
"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
}

Envíe un PUT a upload_url con los bytes del archivo sin procesar como cuerpo, y envíe cada encabezado en upload_headers exactamente tal como se indica.

Ventana de terminal
# UPLOAD_URL and UPLOAD_CONTENT_TYPE come from upload_url and upload_headers["Content-Type"] in the previous response
curl --fail-with-body -X PUT "$UPLOAD_URL" \
-H "Content-Type: $UPLOAD_CONTENT_TYPE" \
-H "If-None-Match: *" \
--upload-file "report.docx"

No envíe su clave API OmniDoc en este paso. Si la dirección caduca o la transferencia falla, solicite una nueva.

POST /api/v1/upload/finalize
X-API-Key: sk_your_key
Content-Type: application/json
{"finalize_token":"short_lived_token"}

En caso de éxito, se devuelve el documento:

{
"document": {
"id": "4q8mx2q9z1k7p6ra",
"basename": "report.docx",
"file_size": 45678,
"mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"created_at": "2026-10-01T12:00:00Z"
}
}

Solo después de la confirmación el documento ingresa a la biblioteca de archivos y queda disponible para su uso en los trabajos.

filename es solo para visualización; no lo utilice como ruta ni como identificador único. El servidor reemplaza los caracteres no válidos y genera un nombre de descarga seguro para los nombres que sean demasiado largos.

EstadoCausa
400Nombre o tamaño de archivo no válido, o el tamaño cargado difiere del solicitado
401Credencial o finalize_token no válida o caducada
403El finalize_token pertenece a otra cuenta
410No se encontró el archivo cargado (transferencia incompleta o dirección caducada); solicite una nueva dirección
413Supera el límite de tamaño por archivo
415Formato no compatible, o el contenido no coincide con la extensión
422El archivo Office está dañado o presenta inseguridad estructural.
429Demasiadas subidas
503El servicio de carga está temporalmente no disponible; inténtelo más tarde