Endpoint de disparo

O endpoint de disparo deixa outro sistema rodar uma tarefa específica com um POST HTTP, sem token da Conta Kobana: cada tarefa tem a própria URL e a própria credencial. É o caminho para um ERP, um formulário ou um webhook de terceiros acionar o Kadu.

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

Staging: https://api.staging.kadu.ia.br/run-task/{task_id}. A URL de cada tarefa aparece em Configurações → Endpoints, com um exemplo de chamada.

Habilitar

O endpoint de uma tarefa é habilitado pelo Playbook (task.endpoint), e a credencial é cadastrada no Kadu, nunca no repositório. Ver Endpoints e Agendamento, endpoint e executor.

Autenticação

Uma das quatro, conforme a configuração da tarefa:

Tipo	Como enviar
HTTP Basic	Authorization: Basic <base64(usuario:senha)>
Bearer Token	Authorization: Bearer <token>
Header	o header configurado, com o valor configurado (X-Api-Key: …)
Parâmetro na URL	?<nome>=<valor> na URL. Evite: a URL aparece em logs de proxies.

Corpo

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	Obrigatório	Regra
environment_id	sim	UUID do ambiente em que a tarefa roda
reference_date	não	AAAA-MM-DD; padrão: a data de hoje
parameters	não	objeto validado contra o parameters_schema da tarefa; padrão {}
locale	não	idioma da execução (pt-BR, en)
additional_instructions	não	texto livre enviado ao agente junto com a skill, até 8.000 caracteres

O corpo é só JSON, de até 1 MiB: uma tarefa disparada pelo endpoint não recebe arquivos de entrada.

Respostas

201 quando a execução foi criada. Ela entra na fila da tarefa e começa sozinha:

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

Resposta	Quando
400 validation_failed	corpo fora do formato acima
401 unauthorized	credencial ausente ou errada
403 ENTITLEMENT_REQUIRED	a organização não tem o Kadu no plano
404 not_found	tarefa inexistente, removida ou com o endpoint desabilitado. A resposta é a mesma nos três casos, para não revelar se a tarefa existe.
409	conflito de X-Idempotency-Key (Idempotência)
413 payload_too_large	corpo acima de 1 MiB
422 unprocessable_entity	parameters não passou no parameters_schema (details traz os erros)
422 environment_required	environment_id ausente ou inválido
422 missing_secrets	secrets exigidos pela tarefa sem valor no ambiente (details diz quais)
422 cost_limit_reached	a organização atingiu o teto mensal de custo
429 rate_limited	mais de 60 chamadas por minuto do mesmo IP para a mesma tarefa

Com X-Idempotency-Key, repetir a mesma chamada devolve a resposta original com X-Idempotent-Replay: true, sem criar outra execução.

Para saber quando a execução terminou, assine execution.completed e execution.failed nos webhooks.

Webhook do Inbox Autônomo

O endpoint recebe direto o webhook do Inbox Autônomo da Kobana. Uma entrega com o header X-Kobana-App: inbox traz o envelope do Inbox no lugar do corpo acima, e o Kadu converte:

• data.email vira os parameters, filtrado pelas propriedades do parameters_schema da tarefa (sem schema, vai o objeto inteiro);
• a data de delivered_at vira a reference_date;
• o ambiente vem da query, porque o Inbox não deixa mudar o corpo.

Cadastre no Inbox a URL https://api.kadu.ia.br/run-task/{task_id}?environment_id=<uuid> e configure a autenticação opcional do webhook do Inbox (Basic, Bearer ou header) com a credencial da tarefa.