Documentación de la API de DocAI

DocAI ofrece una API REST para extraer datos estructurados de documentos subidos o adjuntos de correo normalizados. Los trabajos persistentes, la aprobación humana, los webhooks firmados y las exportaciones contables permiten automatizaciones en Make, n8n, Zapier o integraciones personalizadas.

¿Trabaja con un agente de codificación en lugar de código de aplicación? DocAI MCP conecta Codex, Claude Code, Gemini CLI y otros agentes compatibles con MCP a esta misma API.

Autenticación

Cree y gestione las claves de API en la página Configuración de desarrollador. Envíe la clave como token bearer; los scopes y la cuota mensual de páginas de la clave se aplican en cada solicitud.

Authorization: Bearer sk_docai_<your_key>

Las claves de API empiezan por sk_docai_. Mantenlas en secreto. Solo se muestran una vez al crearlas.

Usa el ámbito extract para enviar y supervisar trabajos. Añade el ámbito history para recuperar resultados guardados y exportaciones contables. Estos son los únicos ámbitos admitidos para las claves API.

Límites de frecuencia

El uso del análisis se rige por la cuota de páginas y la cuota de almacenamiento de tu plan. No hay un límite separado por solicitud ni por día.

Las claves de API además contabilizan las páginas de OCR en la cuota mensual de páginas de la clave.

Las solicitudes que se quedan sin páginas o almacenamiento devuelven HTTP 402; una clave de API que supera su cuota mensual de páginas devuelve HTTP 429 con una indicación Retry-After.

Formato de error

{
  "detail": "File too large. Maximum upload size is 15 MB.",
  "request_id": "abc123"
}

Extracción síncrona de documentos

POST/api/v1/analyze

Sube un documento y obtén los resultados de extracción de forma síncrona. Ideal para documentos pequeños (< 2 páginas).

Solicitud

Datos de formulario multipart:

Campo	Tipo		Descripción
`file`	file	obligatorio	PDF, PNG, JPG, HEIC, AVIF, TIFF, BMP o WEBP (máx. 15 MB)
`filename`	string	opcional	Sustituye el nombre de archivo mostrado

Ejemplo

curl -X POST https://docai.synairo.com/api/v1/analyze \
  -H "Authorization: Bearer sk_docai_..." \
  -F "file=@purchase_order.pdf"

Respuesta

{
  "request_id": "3fa8...",
  "filename": "purchase_order.pdf",
  "document_type": "purchase_order",
  "document_type_confidence": 0.94,
  "summary": "Purchase order from Acme Corp to Widget Co.",
  "language": "en",
  "extracted_fields": [
    {
      "field": "po_number",
      "value": "PO-2026-0042",
      "confidence": 0.97,
      "page": 1,
      "evidence": "PO-2026-0042"
    }
  ],
  "warnings": [],
  "ocr": { "pages": 1, "tokens": 312, "language": "eng+pol" },
  "llm": { "status": "success", "provider": "openai", "model": "gpt-4o-mini" }
}

Extracción por streaming (SSE)

POST/api/v1/analyze/stream

Igual que la síncrona, pero transmite Server-Sent Events que muestran el progreso del procesamiento. Ideal para interfaces en tiempo real.

Crear trabajo asíncrono

POST/api/v1/jobs

Sube un documento y obtén un ID de trabajo. El procesamiento se realiza en segundo plano.

curl -X POST https://docai.synairo.com/api/v1/jobs \
  -H "Authorization: Bearer sk_docai_..." \
  -F "file=@invoice.pdf"

{ "job_id": "abc123", "status": "queued", "request_id": "xyz..." }

Ingerir adjuntos de correo

POST/api/v1/ingest/email

Puente de correo entrante independiente del proveedor. Postmark, Mailgun, SendGrid, Amazon SES, Make, n8n u otro adaptador debe analizar la carga útil del proveedor y enviar los adjuntos aceptados como datos de formulario multipart. DocAI no aloja un buzón ni analiza MIME de forma específica para cada proveedor.

Campo	Tipo		Descripción
`message_id`	string	obligatorio	Identificador de mensaje estable del proveedor
`source_namespace`	string	obligatorio	Ámbito estable de proveedor/cuenta, como postmark:server-123
`files`	file[]	obligatorio	Repetir para cada adjunto admitido
`organization_id`	string	opcional	Espacio de trabajo de destino; quien llama debe tener permiso de carga

curl -X POST https://docai.synairo.com/api/v1/ingest/email \
  -H "Authorization: Bearer sk_docai_..." \
  -F "message_id=provider-message-42" \
  -F "source_namespace=postmark:server-123" \
  -F "organization_id=org_..." \
  -F "files=@invoice.pdf;type=application/pdf" \
  -F "files=@receipt.jpg;type=image/jpeg"

{
  "message_id": "provider-message-42",
  "source_namespace": "postmark:server-123",
  "accepted_count": 1,
  "duplicate_count": 1,
  "jobs": [
    {"job_id": "job-new", "status": "queued", "filename": "invoice.pdf", "duplicate": false},
    {"job_id": "job-old", "status": "completed", "filename": "receipt.jpg", "duplicate": true}
  ]
}

La idempotencia incluye al propietario autenticado, el espacio de nombres de proveedor/cuenta, el destino, el ID del mensaje, el nombre de archivo normalizado, el contenido del archivo y la aparición entre adjuntos idénticos. Los reintentos reordenados del proveedor devuelven los ID de trabajo originales. Una ingesta fallida puede volver a poner en cola el mismo trabajo con bytes nuevos hasta tres intentos en total; los trabajos activos y completados nunca se procesan dos veces.

Obtener estado del trabajo

GET/api/v1/jobs/{job_id}

curl https://docai.synairo.com/api/v1/jobs/abc123 \
  -H "Authorization: Bearer sk_docai_..."

{
  "id": "abc123",
  "status": "completed",
  "progress_pct": 100,
  "document_type": "invoice",
  "pages_processed": 2
}

Estados posibles: queued, processing, review_required, completed, failed, cancelled.

Obtener resultado del trabajo

GET/api/v1/jobs/{job_id}/result

Devuelve el resultado completo de la extracción cuando el trabajo tiene el estado completed o review_required. Las claves de API necesitan el ámbito history.

curl https://docai.synairo.com/api/v1/jobs/abc123/result \
  -H "Authorization: Bearer sk_docai_..."

Exportar JSON

POST/api/v1/export/json

Envía el resultado de la extracción como cuerpo JSON y obtén un archivo de exportación limpio.

curl -X POST https://docai.synairo.com/api/v1/export/json \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_docai_..." \
  -d '{"request_id":"...","extracted_fields":[...]}' \
  -o export.json

Exportar CSV

POST/api/v1/export/csv

curl -X POST https://docai.synairo.com/api/v1/export/csv \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_docai_..." \
  -d '{"request_id":"...","extracted_fields":[...]}' \
  -o fields.csv

Exportar XLSX

POST/api/v1/export/xlsx

Devuelve un libro de Excel con hojas de Resumen, Campos, Líneas de detalle, Advertencias y Metadatos.

Listar historial

GET/api/v1/history

curl https://docai.synairo.com/api/v1/history \
  -H "Authorization: Bearer sk_docai_..."

Flujo de revisión y aprobación

POST/api/v1/history/{record_id}/workflow

Aplica una transición controlada del flujo de trabajo a un registro guardado. Esta ruta requiere una sesión interactiva de Clerk: las claves API no pueden aprobar documentos. Los miembros del espacio de trabajo pueden revisar; los administradores pueden aprobar, solicitar cambios o rechazar. El propietario de un registro personal desempeña ambas funciones.

{
  "action": "approve",
  "comment": "Ready to post"
}

Acciones: start_review, complete_review, reopen_review, submit_for_approval, approve, request_changes, reject y accept_partial_analysis. La aprobación confirma conjuntamente el evento de auditoría del flujo de trabajo y el evento de bandeja de salida document.approved.

Eliminar todo el historial

DELETE/api/v1/history

Elimina permanentemente todos los análisis guardados de tu cuenta.

Listar claves de API

GET/api/v1/keys

Crear clave de API

POST/api/v1/keys

curl -X POST https://docai.synairo.com/api/v1/keys \
  -H "Authorization: Bearer <clerk_session_token>" \
  -H "Content-Type: application/json" \
          -d '{"name": "My automation key", "scopes": "extract,history"}'

{
  "id": "...",
  "name": "My automation key",
  "key": "sk_docai_...",   // shown ONCE - save it now
  "prefix": "sk_docai_abc",
  "scopes": "extract,history",
  "created_at": "2026-06-10T12:00:00Z"
}

Revocar clave de API

DELETE/api/v1/keys/{key_id}

Crear webhook

POST/api/v1/webhooks

curl -X POST https://docai.synairo.com/api/v1/webhooks \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
          -d '{"name": "My webhook", "endpoint_url": "https://my.app/hook", "event_types": ["document.completed", "document.review_required", "document.approved", "document.failed"]}'

La respuesta incluye un secret para la verificación de la firma. Guárdalo ahora, no se volverá a mostrar.

Tipos de eventos de webhook

Evento	Cuándo se activa
`document.completed`	La extracción se completó y se guardó el resultado
`document.review_required`	La validación o el enrutamiento por confianza requiere revisión humana; también se activa con document.completed
`document.approved`	Un aprobador autorizado confirmó la decisión de aprobación; úsalo para registros contables
`document.failed`	El procesamiento falló; los trabajos ingeridos por correo incluyen metadatos de posibilidad de reintento e intentos

Usa document.approved, no document.completed, como punto de control para registrar datos en un sistema contable. La extracción puede completarse aunque los campos todavía requieran corrección.

Probar webhook

POST/api/v1/webhooks/{webhook_id}/test

Verificar la firma del webhook

Cada entrega incluye estas cabeceras:

X-DocAI-Event: tipo de evento (p. ej., document.completed)
X-DocAI-Timestamp: marca de tiempo ISO 8601 en UTC
X-DocAI-Signature: sha256=<hmac>

import hashlib, hmac

def verify(secret, body_str, timestamp, signature_header):
    msg = f"{timestamp}.{body_str}"
    digest = hmac.new(secret.encode(), msg.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"sha256={digest}", signature_header)

Eventos duraderos fallidos

DocAI vuelve a intentar automáticamente las entregas salientes. Si un evento duradero de bandeja de salida no se puede ampliar después de cinco intentos, se convierte en mensaje no entregable. El propietario puede inspeccionar los metadatos sin exponer la carga útil almacenada y volver a ejecutar el evento después de corregir la causa.

GET/api/v1/webhook-outbox/failed

curl https://docai.synairo.com/api/v1/webhook-outbox/failed \
  -H "Authorization: Bearer sk_docai_..."

POST/api/v1/webhook-outbox/{event_id}/replay

curl -X POST https://docai.synairo.com/api/v1/webhook-outbox/EVENT_ID/replay \
  -H "Authorization: Bearer sk_docai_..."

Los mismos controles están disponibles en Configuración para desarrolladores → Eventos que requieren atención. Los registros de entrega y de bandeja de salida terminal se conservan durante 30 días.

Uso con Make / n8n / Zapier

Para cargas directas, llama a /api/v1/jobs. Para correo entrante, deja que el proveedor analice los adjuntos y llame a /api/v1/ingest/email con un ID de mensaje y un espacio de nombres de origen estables. Ambas rutas crean los mismos trabajos persistentes y usan el mismo flujo de revisión.

Suscríbete a los eventos de finalización y revisión para conocer el estado, y luego usa document.approved para activar acciones contables posteriores controladas. Los webhooks firmados eliminan la necesidad de sondeo.