Modos de procesamiento

Matil ofrece tres formas de procesar documentos a través de un deployment. Las tres usan el mismo formato de entrada y devuelven la misma estructura de resultado.

Síncrono

La petición se bloquea hasta que el procesamiento termina. El resultado se devuelve directamente en la respuesta.

POST /v3/deployments/{deployment_id}

Úsalo cuando necesites el resultado inmediatamente y puedas esperar la respuesta (normalmente 1-10 segundos).

Asíncrono

La petición devuelve inmediatamente un entry_id y status: "pending". El resultado se entrega a tu URL de webhook cuando está listo.

POST /v3/deployments/{deployment_id}/async

Incluye un objeto webhook en el cuerpo de la petición:

{
  "documents": [{"type": "url", "url": "https://ejemplo.com/factura.pdf"}],
  "webhook": {
    "url": "https://tu-servidor.com/webhook",
    "secret": "tu-secreto-webhook"
  }
}

Úsalo cuando no necesites el resultado de forma inmediata y quieras desacoplar el envío de la gestión de resultados.

Por lotes

Envía hasta 100 elementos en una sola petición. Devuelve un batch_id y el número total de elementos. Los resultados se entregan vía webhook.

POST /v3/deployments/{deployment_id}/batch

{
  "requests": [
    {
      "metadata": {"pedido_id": "PED-001"},
      "documents": [{"type": "url", "url": "https://ejemplo.com/factura-1.pdf"}]
    },
    {
      "metadata": {"pedido_id": "PED-002"},
      "documents": [{"type": "url", "url": "https://ejemplo.com/factura-2.pdf"}]
    }
  ],
  "webhook": {
    "url": "https://tu-servidor.com/webhook",
    "secret": "tu-secreto-webhook",
    "incremental": true
  }
}

El flag incremental controla la entrega:

Valor	Comportamiento
`true`	Se envía un webhook a medida que cada elemento se completa.
`false`	Se envía un único webhook cuando el lote completo termina.

Consulta el progreso del lote en cualquier momento:

GET /v3/batches/{batch_id}

API Reference

Endpoints

Síncrono

Asíncrono

Por lotes

​Síncrono

​Asíncrono

​Por lotes

Síncrono

Asíncrono

Por lotes