Saltar al contenido principal
Roberty Studio
CODECode

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.

información

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​

PasoEndpointPara qué
1GET 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.
2POST 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.
3GET 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​

bash
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.

bash
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
json
{ "requestId": "…", "deviceId": "…" }

3. Consultar resultado​

Consulta hasta que el estado sea success o failure.

bash
curl -H "x-roberty-api-key: $ROBERTY_API_KEY" \
https://api.roberty.app/v4/public/webhook/code/response/$REQUEST_ID
json
{
"requestId": "…",
"deviceId": "…",
"status": "success",
"startedAt": "…",
"finishedAt": "…",
"durationMs": 1234,
"response": { "status": "ok", "processedAt": "…" }
}
CampoDescripción
statuspending, running, success o failure.
responseSolo 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.
outputTruncatedtrue cuando el resultado superó los 256 KB y se cortó.
errorSolo en failure: el mensaje de error. En caso de fallo, el resultado no se envía.
startedAt, finishedAt, durationMsInicio, 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 required no viene en args, el disparo falla con 400 y el error MISSING_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 args llegan al robot exactamente como se enviaron.
  • Sin inputs declarados, los args tambié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ónResultado
No hay deploy activo en ProducciónEl endpoint responde 409. Haz un deploy en Producción para que el webhook responda. Consulta Deploys.
Falta un input required400 con MISSING_REQUIRED_INPUT_ARGUMENT.
Ningún dispositivo de Producción en línea503 con NO_DEVICE_ONLINE. Consulta Dispositivos.
Proyecto desactivadoEl 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-trigger igual a webhook, y los args llegan en el archivo de roberty-args-file-path.
  • Lo que el robot escriba en el archivo de roberty-output-file-path vuelve en response cuando el proceso termina con exit code 0.

Consulta Preparar el proyecto.

Consulta también​