Pular para o conteúdo principal
Roberty Studio
IDPConfigurações

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.

informação

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​

PassoEndpointPara quê
1POST 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.
2PUT {uploadUrl}Enviar o documento: os bytes do arquivo vão para a URL devolvida no passo 1. É este envio que dispara o processamento.
3GET 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 bodyObrigatórioDescrição
filenameSimO nome do arquivo. A extensão define como o documento é lido e precisa ser pdf, png, jpg, jpeg, webp, tiff, tif ou bmp.
pageNãoIntervalo 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.
paramsNãoUm objeto com parâmetros que o pipeline pode usar, por exemplo nas etapas de pós-processamento. Veja Pós-processamento.
bash
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:

json
{
"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.

bash
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.

bash
curl -H "x-roberty-api-key: $ROBERTY_API_KEY" \
https://api.roberty.app/v4/public/webhook/idp/response/$REQUEST_ID
json
{
"requestId": "…",
"templateId": "…",
"versionId": "…",
"status": "finished",
"createdAt": "…",
"uploadedAt": "…",
"startedAt": "…",
"finishedAt": "…",
"durationMs": 9000,
"result": { "…": "…" }
}
StatusSignificado
waiting_uploadA execução foi reservada e aguarda o envio do documento.
pendingO documento chegou e a execução aguarda para começar.
runningO pipeline está processando o documento.
finishedO pipeline chegou ao fim. Isso inclui documentos rejeitados na identificação e resultados reprovados nas validações.
errorA execução falhou. A mensagem vem em error.
expiredO documento não foi enviado a tempo e a reserva expirou.
CampoDescrição
resultSó 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.
errorSó em error: a mensagem de falha do pipeline.
versionIdA versão que processou o documento.
durationMsO 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​

bash
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​

StatusErroSituação
400UNSUPPORTED_FILE_EXTENSIONA extensão de filename não é aceita.
400PAGE_OVERRIDE_NOT_ALLOWEDA chamada enviou page, mas a versão ativa não permite que a API sobrescreva as páginas.
403API_KEY_NOT_AUTHORIZED_FOR_THIS_TEMPLATEA chave de API não tem o escopo Templates IDP para este template.
404TEMPLATE_NOT_FOUNDO template não existe neste workspace.
404REQUEST_NOT_FOUNDO requestId consultado não existe ou não pertence a este workspace.
409NO_ACTIVE_VERSIONO template não tem uma versão ativa. Publique uma em Versões.
409STORAGE_LIMIT_REACHEDO 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.

Veja também​