API e webhook
Processe documentos com um template de IDP pela API pública: solicite a execução, envie o documento na URL assinada e consulte o resultado.
API e webhook
Sistemas externos podem processar documentos com o template pela API pública da Roberty. A chamada é feita em três passos: solicitar a execução, enviar o documento e consultar o resultado. Essas execuções rodam sempre a versão ativa e aparecem no ambiente Produção, em Execuções.
A seção API & Webhook das configurações do template mostra os endpoints já com o ID do template, um exemplo de body e a coleção Postman.
O plano do workspace precisa incluir requisições de IDP e webhooks. Cada documento processado conta no consumo de Requisições IDP do workspace; uma execução solicitada cujo documento nunca foi enviado não conta.
Credencial
As requisições dos passos 1 e 3, e a de descoberta, levam o header x-roberty-api-key com uma chave de API do workspace com o escopo Templates IDP cobrindo este template. O envio do documento (passo 2) não leva o header: a URL já vem assinada.
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.
Endpoints
| Passo | Endpoint | Para quê |
|---|---|---|
| 1 | POST https://api.roberty.app/v4/public/webhook/idp/request/{templateId} | Solicitar a execução: reserva a execução e devolve o requestId e a URL temporária para enviar o documento. |
| 2 | PUT {uploadUrl} | Enviar o documento: os bytes do arquivo vão para a URL devolvida no passo 1. É este envio que dispara o processamento. |
| 3 | GET https://api.roberty.app/v4/public/webhook/idp/response/{requestId} | Acompanhar e obter o resultado: devolve o status da execução e, ao terminar, o resultado. |
| — | GET https://api.roberty.app/v4/public/webhook/idp/arguments/{templateId} | Descobrir o contrato: devolve os formatos aceitos e o que a versão ativa espera receber. |
1. Solicitar a execução
| Campo do body | Obrigatório | Descrição |
|---|---|---|
filename | Sim | O nome do arquivo. A extensão define como o documento é lido e precisa ser pdf, png, jpg, jpeg, webp, tiff, tif ou bmp. |
page | Não | Intervalo de páginas desta execução, por exemplo 1-3,5, no lugar do escopo configurado no template. Só é aceito quando a versão ativa permite que a API sobrescreva as páginas. Veja Documento e páginas. |
params | Não | Um objeto com parâmetros que o pipeline pode usar, por exemplo nas etapas de pós-processamento. Veja Pós-processamento. |
curl -X POST -H "x-roberty-api-key: $ROBERTY_API_KEY" -H "content-type: application/json" \
-d '{ "filename": "documento.pdf", "params": {} }' \
https://api.roberty.app/v4/public/webhook/idp/request/$TEMPLATE_ID
A resposta tem o status 202:
{
"requestId": "…",
"uploadUrl": "https://…",
"expiresAt": "…"
}
2. Enviar o documento
Envie os bytes do arquivo com PUT na uploadUrl, sem o header da chave de API. A URL vale 15 minutos.
curl -X PUT --upload-file documento.pdf "$UPLOAD_URL"
Assim que o envio termina, a execução entra na fila e o pipeline começa.
3. Acompanhar e obter o resultado
Consulte até o status ser finished, error ou expired.
curl -H "x-roberty-api-key: $ROBERTY_API_KEY" \
https://api.roberty.app/v4/public/webhook/idp/response/$REQUEST_ID
{
"requestId": "…",
"templateId": "…",
"versionId": "…",
"status": "finished",
"createdAt": "…",
"uploadedAt": "…",
"startedAt": "…",
"finishedAt": "…",
"durationMs": 9000,
"result": { "…": "…" }
}
| Status | Significado |
|---|---|
waiting_upload | A execução foi reservada e aguarda o envio do documento. |
pending | O documento chegou e a execução aguarda para começar. |
running | O pipeline está processando o documento. |
finished | O pipeline chegou ao fim. Isso inclui documentos rejeitados na identificação e resultados reprovados nas validações. |
error | A execução falhou. A mensagem vem em error. |
expired | O documento não foi enviado a tempo e a reserva expirou. |
| Campo | Descrição |
|---|---|
result | Só em finished: o resultado de cada etapa — preProcessing, identification, extraction, postProcessing e validations — e o tempo total em totalMs. A saída final é o output do último item de postProcessing ou, sem pós-processamento, extraction.text. |
error | Só em error: a mensagem de falha do pipeline. |
versionId | A versão que processou o documento. |
durationMs | O tempo entre o envio do documento e o fim da execução. |
Quando a identificação rejeita o documento, result.identification.passed vem false e as etapas seguintes não rodam. O veredito de cada validação vem em result.validations, com passed e reason. Veja Identificação e Validações.
Descobrir o contrato
curl -H "x-roberty-api-key: $ROBERTY_API_KEY" \
https://api.roberty.app/v4/public/webhook/idp/arguments/$TEMPLATE_ID
Devolve o nome do template, o número da versão ativa, as extensões de arquivo aceitas (inputs.file.accept) e se a chamada pode enviar page (inputs.page.allowed), junto com o intervalo configurado no template (inputs.page.configuredRange).
Erros
| Status | Erro | Situação |
|---|---|---|
400 | UNSUPPORTED_FILE_EXTENSION | A extensão de filename não é aceita. |
400 | PAGE_OVERRIDE_NOT_ALLOWED | A chamada enviou page, mas a versão ativa não permite que a API sobrescreva as páginas. |
403 | API_KEY_NOT_AUTHORIZED_FOR_THIS_TEMPLATE | A chave de API não tem o escopo Templates IDP para este template. |
404 | TEMPLATE_NOT_FOUND | O template não existe neste workspace. |
404 | REQUEST_NOT_FOUND | O requestId consultado não existe ou não pertence a este workspace. |
409 | NO_ACTIVE_VERSION | O template não tem uma versão ativa. Publique uma em Versões. |
409 | STORAGE_LIMIT_REACHED | O workspace atingiu o limite de armazenamento. |
Quando o template ainda não tem uma versão ativa, a seção API & Webhook mostra um aviso.
Testar no Postman
Na seção API & Webhook, Baixar coleção gera uma coleção Postman com os quatro endpoints e um body de exemplo. A coleção usa o placeholder YOUR_API_KEY: troque-o por uma chave com o escopo Templates IDP. Preencha as variáveis requestId e uploadUrl com os valores devolvidos pelo passo 1 e, no passo 2, selecione o arquivo na aba Body (binary).
O body da coleção sempre mostra o campo page. Remova-o se o template não permite que a API sobrescreva as páginas. O Exemplo de requisição da seção já mostra o body certo para o template.
Para experimentar a chamada sem uma chave de API e sem publicar, use o Simular API, que executa o rascunho. Veja Playground e Simular API.