API y webhook
Procesa documentos con una plantilla de IDP a través de la API pública: solicita la ejecución, envía el documento a la URL firmada y consulta el resultado.
API y webhook
Los sistemas externos pueden procesar documentos con la plantilla a través de la API pública de Roberty. La llamada se hace en tres pasos: solicitar la ejecución, enviar el documento y consultar el resultado. Estas ejecuciones usan siempre la versión activa y aparecen en el entorno Producción, en Ejecuciones.
La sección API y Webhook de la configuración de la plantilla muestra los endpoints con el ID de la plantilla ya completado, un ejemplo de body y la colección de Postman.
El plan del workspace debe incluir solicitudes de IDP y webhooks. Cada documento procesado cuenta en el consumo de Solicitudes IDP del workspace; una ejecución solicitada cuyo documento nunca se envió no cuenta.
Credencial
Las solicitudes de los pasos 1 y 3, y la de descubrimiento, llevan el header x-roberty-api-key con una clave de API del workspace cuyo alcance Plantillas IDP cubra esta plantilla. El envío del documento (paso 2) no lleva el header: la URL ya viene firmada.
Solo los administradores del workspace crean y gestionan claves de API. La clave solo se muestra una vez, al crearla — guárdala en un lugar seguro.
Endpoints
| Paso | Endpoint | Para qué |
|---|---|---|
| 1 | POST https://api.roberty.app/v4/public/webhook/idp/request/{templateId} | Solicitar la ejecución: reserva la ejecución y devuelve el requestId y la URL temporal para enviar el documento. |
| 2 | PUT {uploadUrl} | Enviar el documento: los bytes del archivo van a la URL devuelta en el paso 1. Este envío es lo que dispara el procesamiento. |
| 3 | GET https://api.roberty.app/v4/public/webhook/idp/response/{requestId} | Seguir y obtener el resultado: devuelve el estado de la ejecución y, al finalizar, el resultado. |
| — | GET https://api.roberty.app/v4/public/webhook/idp/arguments/{templateId} | Descubrir el contrato: devuelve los formatos aceptados y lo que espera recibir la versión activa. |
1. Solicitar la ejecución
| Campo del body | Obligatorio | Descripción |
|---|---|---|
filename | Sí | El nombre del archivo. La extensión define cómo se lee el documento y debe ser pdf, png, jpg, jpeg, webp, tiff, tif o bmp. |
page | No | Rango de páginas de esta ejecución, por ejemplo 1-3,5, en lugar del alcance configurado en la plantilla. Solo se acepta cuando la versión activa permite que la API sobrescriba las páginas. Consulta Documento y páginas. |
params | No | Un objeto con parámetros que el pipeline puede usar, por ejemplo en las etapas de posprocesamiento. Consulta Posprocesamiento. |
curl -X POST -H "x-roberty-api-key: $ROBERTY_API_KEY" -H "content-type: application/json" \
-d '{ "filename": "documento.pdf", "params": {} }' \
https://api.roberty.app/v4/public/webhook/idp/request/$TEMPLATE_ID
La respuesta tiene el estado 202:
{
"requestId": "…",
"uploadUrl": "https://…",
"expiresAt": "…"
}
2. Enviar el documento
Envía los bytes del archivo con PUT a la uploadUrl, sin el header de la clave de API. La URL es válida durante 15 minutos.
curl -X PUT --upload-file documento.pdf "$UPLOAD_URL"
En cuanto termina el envío, la ejecución entra en la cola y el pipeline empieza.
3. Seguir y obtener el resultado
Consulta hasta que el estado sea finished, error o expired.
curl -H "x-roberty-api-key: $ROBERTY_API_KEY" \
https://api.roberty.app/v4/public/webhook/idp/response/$REQUEST_ID
{
"requestId": "…",
"templateId": "…",
"versionId": "…",
"status": "finished",
"createdAt": "…",
"uploadedAt": "…",
"startedAt": "…",
"finishedAt": "…",
"durationMs": 9000,
"result": { "…": "…" }
}
| Estado | Significado |
|---|---|
waiting_upload | La ejecución se reservó y espera el envío del documento. |
pending | El documento llegó y la ejecución espera para empezar. |
running | El pipeline está procesando el documento. |
finished | El pipeline llegó al final. Esto incluye documentos rechazados en la identificación y resultados reprobados en las validaciones. |
error | La ejecución falló. El mensaje viene en error. |
expired | El documento no se envió a tiempo y la reserva expiró. |
| Campo | Descripción |
|---|---|
result | Solo en finished: el resultado de cada etapa — preProcessing, identification, extraction, postProcessing y validations — y el tiempo total en totalMs. La salida final es el output del último elemento de postProcessing o, sin posprocesamiento, extraction.text. |
error | Solo en error: el mensaje de fallo del pipeline. |
versionId | La versión que procesó el documento. |
durationMs | El tiempo entre el envío del documento y el fin de la ejecución. |
Cuando la identificación rechaza el documento, result.identification.passed viene en false y las etapas siguientes no se ejecutan. El veredicto de cada validación viene en result.validations, con passed y reason. Consulta Identificación y Validaciones.
Descubrir el contrato
curl -H "x-roberty-api-key: $ROBERTY_API_KEY" \
https://api.roberty.app/v4/public/webhook/idp/arguments/$TEMPLATE_ID
Devuelve el nombre de la plantilla, el número de la versión activa, las extensiones de archivo aceptadas (inputs.file.accept) y si la llamada puede enviar page (inputs.page.allowed), junto con el rango configurado en la plantilla (inputs.page.configuredRange).
Errores
| Estado | Error | Situación |
|---|---|---|
400 | UNSUPPORTED_FILE_EXTENSION | La extensión de filename no se acepta. |
400 | PAGE_OVERRIDE_NOT_ALLOWED | La llamada envió page, pero la versión activa no permite que la API sobrescriba las páginas. |
403 | API_KEY_NOT_AUTHORIZED_FOR_THIS_TEMPLATE | La clave de API no tiene el alcance Plantillas IDP para esta plantilla. |
404 | TEMPLATE_NOT_FOUND | La plantilla no existe en este workspace. |
404 | REQUEST_NOT_FOUND | El requestId consultado no existe o no pertenece a este workspace. |
409 | NO_ACTIVE_VERSION | La plantilla no tiene una versión activa. Publica una en Versiones. |
409 | STORAGE_LIMIT_REACHED | El workspace alcanzó su límite de almacenamiento. |
Cuando la plantilla todavía no tiene una versión activa, la sección API y Webhook muestra un aviso.
Probar en Postman
En la sección API y Webhook, Descargar colección genera una colección de Postman con los cuatro endpoints y un body de ejemplo. La colección usa el placeholder YOUR_API_KEY: cámbialo por una clave con el alcance Plantillas IDP. Completa las variables requestId y uploadUrl con los valores devueltos por el paso 1 y, en el paso 2, selecciona el archivo en la pestaña Body (binary).
El body de la colección siempre muestra el campo page. Quítalo si la plantilla no permite que la API sobrescriba las páginas. El Ejemplo de solicitud de la sección ya muestra el body correcto para la plantilla.
Para probar la llamada sin una clave de API y sin publicar, usa Simular API, que ejecuta el borrador. Consulta Playground y Simular API.