Endpoint de lanzamiento

El endpoint de lanzamiento permite que otro sistema ejecute una tarea específica con un POST HTTP, sin token de la Cuenta Kobana: cada tarea tiene su propia URL y su propia credencial. Es el camino para que un ERP, un formulario o un webhook de terceros active a Kadu.

POST https://api.kadu.ia.br/run-task/{task_id}

Staging: https://api.staging.kadu.ia.br/run-task/{task_id}. La URL de cada tarea aparece en Configuración → Endpoints, con un ejemplo de llamada.

Habilitar

El endpoint de una tarea lo habilita el Playbook (task.endpoint), y la credencial se registra en Kadu, nunca en el repositorio. Ver Endpoints y Programación, endpoint y ejecutor.

Autenticación

Una de las cuatro, según la configuración de la tarea:

Tipo	Cómo enviar
HTTP Basic	Authorization: Basic <base64(usuario:contraseña)>
Bearer Token	Authorization: Bearer <token>
Header	el header configurado, con el valor configurado (X-Api-Key: …)
Parámetro en la URL	?<nombre>=<valor> en la URL. Evítalo: la URL aparece en logs de proxies.

Cuerpo

curl -X POST "https://api.kadu.ia.br/run-task/2f1c…" \
  -H "Authorization: Bearer $TOKEN_DA_TAREFA" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: pedido-48213" \
  -d '{
    "environment_id": "8a40…",
    "reference_date": "2026-10-30",
    "parameters": { "pedido": "48213" },
    "locale": "pt-BR"
  }'

Campo	Obligatorio	Regla
environment_id	sí	UUID del entorno en el que corre la tarea
reference_date	no	AAAA-MM-DD; predeterminado: la fecha de hoy
parameters	no	objeto validado contra el parameters_schema de la tarea; predeterminado {}
locale	no	idioma de la ejecución (pt-BR, en)
additional_instructions	no	texto libre enviado al agente junto con la skill, hasta 8.000 caracteres

El cuerpo es solo JSON, de hasta 1 MiB: una tarea lanzada por el endpoint no recibe archivos de entrada.

Respuestas

201 cuando se creó la ejecución. Entra en la cola de la tarea y empieza sola:

{ "execution_id": "c7d2…", "status": "queued" }

Respuesta	Cuándo
400 validation_failed	cuerpo fuera del formato de arriba
401 unauthorized	credencial ausente o incorrecta
403 ENTITLEMENT_REQUIRED	la organización no tiene Kadu en el plan
404 not_found	tarea inexistente, eliminada o con el endpoint deshabilitado. La respuesta es la misma en los tres casos, para no revelar si la tarea existe.
409	conflicto de X-Idempotency-Key (Idempotencia)
413 payload_too_large	cuerpo por encima de 1 MiB
422 unprocessable_entity	parameters no pasó el parameters_schema (details trae los errores)
422 environment_required	environment_id ausente o inválido
422 missing_secrets	secrets exigidos por la tarea sin valor en el entorno (details dice cuáles)
422 cost_limit_reached	la organización alcanzó el tope mensual de costo
429 rate_limited	más de 60 llamadas por minuto de la misma IP a la misma tarea

Con X-Idempotency-Key, repetir la misma llamada devuelve la respuesta original con X-Idempotent-Replay: true, sin crear otra ejecución.

Para saber cuándo terminó la ejecución, suscríbete a execution.completed y execution.failed en los webhooks.

Webhook de el Inbox Autónomo

El endpoint recibe directamente el webhook del Inbox Autónomo de Kobana. Una entrega con el header X-Kobana-App: inbox trae el envelope del Inbox en lugar del cuerpo de arriba, y Kadu lo convierte:

• data.email se convierte en los parameters, filtrado por las propiedades del parameters_schema de la tarea (sin schema, va el objeto completo);
• la fecha de delivered_at se convierte en la reference_date;
• el entorno viene del query, porque el Inbox no permite cambiar el cuerpo.

Registra en el Inbox la URL https://api.kadu.ia.br/run-task/{task_id}?environment_id=<uuid> y configura la autenticación opcional del webhook del Inbox (Basic, Bearer o header) con la credencial de la tarea.