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.
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
| Passo | Endpoint | Para quê |
|---|---|---|
| 1 | GET 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. |
| 2 | POST 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. |
| 3 | GET 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
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.
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
Consulte até o status ser success ou 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 | Descrição |
|---|---|
status | pending, running, success ou failure. |
response | Só 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. |
outputTruncated | true quando o resultado passou de 256 KB e foi cortado. |
error | Só em failure: a mensagem de erro. Em falha, o resultado não é enviado. |
startedAt, finishedAt, durationMs | Iní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
requirednão vier emargs, o disparo falha com400e o erroMISSING_REQUIRED_INPUT_ARGUMENT, indicando os inputs que faltaram. Nada é enviado ao dispositivo. - Tipos e chaves extras não são validados: os
argschegam ao robô exatamente como foram enviados. - Sem inputs declarados, os
argstambé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ção | Resultado |
|---|---|
| Não há deploy ativo em Produção | O endpoint responde 409. Faça um deploy em Produção para o webhook responder. Veja Deploys. |
Input required ausente | 400 com MISSING_REQUIRED_INPUT_ARGUMENT. |
| Nenhum dispositivo de Produção online | 503 com NO_DEVICE_ONLINE. Veja Dispositivos. |
| Projeto desativado | O 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-triggerigual awebhook, e osargschegam no arquivo deroberty-args-file-path. - O que o robô escrever no arquivo de
roberty-output-file-pathvolta emresponsequando o processo termina com exit code0.
Veja Preparar o projeto.
Veja também
- Executar projeto Code — executar o projeto a partir de um robô RPA.
- Chaves de API
- Execuções