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.
1. Solicite una dirección de carga
Sección titulada «1. Solicite una dirección de carga»POST /api/v1/upload/presignX-API-Key: sk_your_keyContent-Type: application/json{ "filename": "report.docx", "file_size": 45678}| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
filename | cadena | ✅ | Nombre de archivo; el servidor determina el tipo de archivo a partir de la extensión |
file_size | entero | ✅ | Tamaño exacto en bytes, mayor que 0 |
mime_type | cadena | — | 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}2. Envíe el archivo
Sección titulada «2. Envíe el archivo»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.
# 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"No envíe su clave API OmniDoc en este paso. Si la dirección caduca o la transferencia falla, solicite una nueva.
3. Confirme el documento
Sección titulada «3. Confirme el documento»POST /api/v1/upload/finalizeX-API-Key: sk_your_keyContent-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.
Nombres de archivo
Sección titulada «Nombres de archivo»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.
Errores
Sección titulada «Errores»| Estado | Causa |
|---|---|
400 | Nombre o tamaño de archivo no válido, o el tamaño cargado difiere del solicitado |
401 | Credencial o finalize_token no válida o caducada |
403 | El finalize_token pertenece a otra cuenta |
410 | No se encontró el archivo cargado (transferencia incompleta o dirección caducada); solicite una nueva dirección |
413 | Supera el límite de tamaño por archivo |
415 | Formato no compatible, o el contenido no coincide con la extensión |
422 | El archivo Office está dañado o presenta inseguridad estructural. |
429 | Demasiadas subidas |
503 | El servicio de carga está temporalmente no disponible; inténtelo más tarde |