Pular para o conteúdo principal
Roberty Studio
CODECode

API e webhook

Dispare e acompanhe execuções do projeto de código em Produção pela API pública, autenticada por uma chave de API do workspace.

API e webhook

Sistemas externos podem disparar o projeto pela API pública da Roberty, enviar argumentos e consultar o resultado. Essas execuções usam o gatilho Webhook e rodam sempre em Produção. As configurações do projeto, aba API & Webhook, mostram os endpoints, um exemplo de requisição e a coleção Postman.

Credencial​

Toda requisição leva o header x-roberty-api-key com uma chave de API do workspace com o escopo Projetos de código cobrindo este projeto.

informação

Só administradores do workspace criam e gerenciam chaves de API. A chave só é exibida uma vez, na criação — guarde-a em um lugar seguro.

O {codeId} dos endpoints é o ID do projeto, exibido em Configurações, aba Geral.

Endpoints​

PassoEndpointPara quê
1GET https://api.roberty.app/v4/public/webhook/code/arguments/{codeId}Descobrir argumentos: devolve os inputs e outputs declarados na seção webhook do roberty.json do deploy de Produção ativo.
2POST https://api.roberty.app/v4/public/webhook/code/request/{codeId}Executar: cria uma execução em Produção com os argumentos enviados e responde 202 com requestId e deviceId.
3GET https://api.roberty.app/v4/public/webhook/code/response/{requestId}Consultar resultado: devolve o status da execução e, em sucesso, o resultado escrito pelo robô.

1. Descobrir argumentos​

bash
curl -H "x-roberty-api-key: $ROBERTY_API_KEY" \
https://api.roberty.app/v4/public/webhook/code/arguments/$CODE_ID

2. Executar​

O body tem args, que vira o JSON do arquivo de argumentos do robô, e 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​

Consulte até o status ser success ou 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": "…" }
}
CampoDescrição
statuspending, running, success ou failure.
responseSó em success: o que o robô escreveu no arquivo de roberty-output-file-path. JSON válido volta como objeto; texto que não é JSON volta como string. Se o robô não escreveu nada, o campo não aparece.
outputTruncatedtrue quando o resultado passou de 256 KB e foi cortado.
errorSó em failure: a mensagem de erro. Em falha, o resultado não é enviado.
startedAt, finishedAt, durationMsInício, fim e duração da execução, quando disponíveis.

Argumentos e webhook.inputs​

A seção webhook do roberty.json documenta o contrato do robô: quais chaves ele lê (inputs) e quais escreve (outputs). A plataforma usa essa declaração no endpoint Descobrir argumentos e para montar o exemplo de requisição e a coleção Postman. Veja Seção webhook.

  • Se um input marcado como required não vier em args, o disparo falha com 400 e o erro MISSING_REQUIRED_INPUT_ARGUMENT, indicando os inputs que faltaram. Nada é enviado ao dispositivo.
  • Tipos e chaves extras não são validados: os args chegam ao robô exatamente como foram enviados.
  • Sem inputs declarados, os args também chegam como foram enviados — só não há contrato publicado.

Escolha do dispositivo e fila​

  • Sem deviceId — a plataforma escolhe, entre os dispositivos de Produção online e com deploy ativo, o que tiver menos execuções pendentes do projeto.
  • Com deviceId — a execução é fixada naquele dispositivo, que precisa ser de Produção, estar online e ter deploy ativo.

Cada dispositivo roda uma execução do projeto por vez: disparos seguidos entram em fila e são executados assim que o dispositivo fica livre. O dispositivo de Preview nunca recebe execuções pela API.

Erros​

SituaçãoResultado
Não há deploy ativo em ProduçãoO endpoint responde 409. Faça um deploy em Produção para o webhook responder. Veja Deploys.
Input required ausente400 com MISSING_REQUIRED_INPUT_ARGUMENT.
Nenhum dispositivo de Produção online503 com NO_DEVICE_ONLINE. Veja Dispositivos.
Projeto desativadoO disparo é bloqueado até o projeto ser reativado em Configurações.

Testar no Postman​

Na aba API & Webhook, Baixar coleção gera uma coleção Postman com os três endpoints, os headers e um body montado a partir dos inputs declarados. A coleção usa o placeholder YOUR_API_KEY: troque-o por uma chave com o escopo Projetos de código.

Como o robô participa​

  • A execução roda com roberty-trigger igual a webhook, e os args chegam no arquivo de roberty-args-file-path.
  • O que o robô escrever no arquivo de roberty-output-file-path volta em response quando o processo termina com exit code 0.

Veja Preparar o projeto.

Veja também​