API y webhook
Dispara y sigue ejecuciones del proyecto de código en Producción a través de la API pública, autenticada con una clave de API del workspace.
API y webhook
Los sistemas externos pueden disparar el proyecto a través de la API pública de Roberty, enviar argumentos y consultar el resultado. Estas ejecuciones usan el disparador Webhook y se ejecutan siempre en Producción. La configuración del proyecto, pestaña API & Webhook, muestra los endpoints, un ejemplo de solicitud y la colección de Postman.
Credencial
Toda solicitud lleva el header x-roberty-api-key con una clave de API del workspace cuyo alcance Proyectos de código cubra este proyecto.
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.
El {codeId} de los endpoints es el ID del proyecto, que aparece en Configuración, pestaña General.
Endpoints
| Paso | Endpoint | Para qué |
|---|---|---|
| 1 | GET https://api.roberty.app/v4/public/webhook/code/arguments/{codeId} | Descubrir argumentos: devuelve los inputs y outputs declarados en la sección webhook del roberty.json del deploy de Producción activo. |
| 2 | POST https://api.roberty.app/v4/public/webhook/code/request/{codeId} | Ejecutar (producción): crea una ejecución en Producción con los argumentos enviados y responde 202 con requestId y deviceId. |
| 3 | GET https://api.roberty.app/v4/public/webhook/code/response/{requestId} | Consultar resultado: devuelve el estado de la ejecución y, en éxito, el resultado que escribió el robot. |
1. Descubrir argumentos
curl -H "x-roberty-api-key: $ROBERTY_API_KEY" \
https://api.roberty.app/v4/public/webhook/code/arguments/$CODE_ID
2. Ejecutar
El body tiene args, que se convierte en el JSON del archivo de argumentos del robot, y deviceId, opcional.
curl -X POST -H "x-roberty-api-key: $ROBERTY_API_KEY" -H "content-type: application/json" \
-d '{ "args": { "cpf": "12345678900" } }' \
https://api.roberty.app/v4/public/webhook/code/request/$CODE_ID
{ "requestId": "…", "deviceId": "…" }
3. Consultar resultado
Consulta hasta que el estado sea success o failure.
curl -H "x-roberty-api-key: $ROBERTY_API_KEY" \
https://api.roberty.app/v4/public/webhook/code/response/$REQUEST_ID
{
"requestId": "…",
"deviceId": "…",
"status": "success",
"startedAt": "…",
"finishedAt": "…",
"durationMs": 1234,
"response": { "status": "ok", "processedAt": "…" }
}
| Campo | Descripción |
|---|---|
status | pending, running, success o failure. |
response | Solo en success: lo que el robot escribió en el archivo de roberty-output-file-path. El JSON válido vuelve como objeto; el texto que no es JSON vuelve como string. Si el robot no escribió nada, el campo no aparece. |
outputTruncated | true cuando el resultado superó los 256 KB y se cortó. |
error | Solo en failure: el mensaje de error. En caso de fallo, el resultado no se envía. |
startedAt, finishedAt, durationMs | Inicio, fin y duración de la ejecución, cuando están disponibles. |
Argumentos y webhook.inputs
La sección webhook del roberty.json documenta el contrato del robot: qué claves lee (inputs) y cuáles escribe (outputs). La plataforma usa esa declaración en el endpoint Descubrir argumentos y para armar el ejemplo de solicitud y la colección de Postman. Consulta Sección webhook.
- Si un input marcado como
requiredno viene enargs, el disparo falla con400y el errorMISSING_REQUIRED_INPUT_ARGUMENT, indicando los inputs que faltaron. No se envía nada al dispositivo. - Los tipos y las claves extra no se validan: los
argsllegan al robot exactamente como se enviaron. - Sin inputs declarados, los
argstambién llegan como se enviaron — solo no hay contrato publicado.
Elección del dispositivo y cola
- Sin
deviceId— la plataforma elige, entre los dispositivos de Producción online y con deploy activo, el que tenga menos ejecuciones pendientes del proyecto. - Con
deviceId— la ejecución se fija en ese dispositivo, que debe ser de Producción, estar online y tener deploy activo.
Cada dispositivo ejecuta una ejecución del proyecto a la vez: los disparos seguidos entran en cola y se ejecutan en cuanto el dispositivo queda libre. El dispositivo de Preview nunca recibe ejecuciones por la API.
Errores
| Situación | Resultado |
|---|---|
| No hay deploy activo en Producción | El endpoint responde 409. Haz un deploy en Producción para que el webhook responda. Consulta Deploys. |
Falta un input required | 400 con MISSING_REQUIRED_INPUT_ARGUMENT. |
| Ningún dispositivo de Producción en línea | 503 con NO_DEVICE_ONLINE. Consulta Dispositivos. |
| Proyecto desactivado | El disparo queda bloqueado hasta que el proyecto se reactive en Configuración. |
Probar en Postman
En la pestaña API & Webhook, Descargar colección genera una colección de Postman con los tres endpoints, los headers y un body armado a partir de los inputs declarados. La colección usa el placeholder YOUR_API_KEY: sustitúyelo por una clave con el alcance Proyectos de código.
Cómo participa el robot
- La ejecución se hace con
roberty-triggerigual awebhook, y losargsllegan en el archivo deroberty-args-file-path. - Lo que el robot escriba en el archivo de
roberty-output-file-pathvuelve enresponsecuando el proceso termina con exit code0.
Consulta Preparar el proyecto.
Consulta también
- Ejecutar proyecto Code — ejecutar el proyecto desde un robot RPA.
- Claves de API
- Ejecuciones