Workflow endpoints

Permite a um sistema externo disparar um workflow (pipeline de automação) configurado pelo tenant, sem acesso ao painel do workflow. Cada chave de API é vinculada a um único entrypoint.

`POST /workflow-endpoints/{entrypoint_key}`

Inicia a execução para um CPF/CNPJ. Resposta sempre imediata (202), nunca carrega o resultado. Escopo: workflow_endpoints:invoke

Corpo da requisição

Campo	Tipo	Descrição
`document`	string	CPF ou CNPJ do subject, formatado ou não. Normalizado e validado (dígito verificador) antes de tudo.
`metadata`	object	Opcional. Campos declarados no `metadata_schema` do entrypoint são validados e ficam legíveis pelas condições do workflow; campos não declarados são aceitos e armazenados, mas nenhuma condição os lê.

{ "document": "12345678901", "metadata": { "priority": "high" } }

Resposta (`202`, `WorkflowExecutionAcceptedResponse`)

Campo	Descrição
`execution_uuid`	Identificador da execução, usado para consultar o resultado.
`status`	Estado no momento da resposta — normalmente `queued`.
`deduplicated`	`true` quando esta chamada não criou uma execução nova: já existe uma aberta para o mesmo subject+entrypoint, e `execution_uuid` aponta pra ela.
`case_uuid`	Caso de revisão humana aberto por esta execução, ou `null` se ainda não chegou num nó de fila.

Erros

Status	Quando
`404`	Nenhum entrypoint alcançável nessa chave com essa credencial (chave errada ou entrypoint inexistente respondem igual).
`409`	Workflow pausado (`workflow_paused`), entrypoint desligado (`entrypoint_disabled`), ou sem versão publicada ativa (`workflow_not_published`).
`413`	Corpo maior que o limite do entrypoint (`payload_too_large`) ou `metadata` maior que o limite (`metadata_too_large`).
`422`	`document` não é CPF/CNPJ válido (`invalid_document`), ou `metadata` não satisfaz o schema declarado (`metadata_invalid`, com cada campo problemático em `issues`).
`429`	Chave excedeu o limite por minuto do entrypoint (`rate_limited`).

Catálogo completo em Erros.

`GET /workflow-executions/{execution_uuid}`

Consulta uma execução com a mesma chave que a iniciou. Escopo: workflow_executions:read

Resposta (`WorkflowExecutionReadResponse`)

Campo	Descrição
`execution_uuid`, `entrypoint_key`	Identificadores da execução e do entrypoint que a recebeu.
`status`	`queued` \| `running` \| `waiting_human` \| `succeeded` \| `failed` \| `cancelled`. `waiting_human` é a pausa enquanto um caso de revisão está aberto.
`created_at`, `completed_at`	`completed_at` é `null` enquanto a execução não chega a um estado terminal.
`case_uuid`	Caso de revisão humana associado, se houver. Permanece preenchido após o caso fechar.
`output`	Apenas os campos que o `output_whitelist` do entrypoint declara. Whitelist vazia (padrão) retorna objeto vazio. Metadata enviada, payload de entrada, snapshot do grafo, anexos e evidências nunca aparecem aqui.

Uma execução com status: "failed" não traz mensagem de erro nesta resposta — é interna, visível só pela API de lifecycle (fora do escopo público).

Erros

Status	Quando
`404`	Nenhuma execução com esse identificador é legível por essa credencial.

Primeiros passos

Conceitos

`POST /workflow-endpoints/{entrypoint_key}`

Corpo da requisição

Resposta (`202`, `WorkflowExecutionAcceptedResponse`)

Erros

`GET /workflow-executions/{execution_uuid}`

Resposta (`WorkflowExecutionReadResponse`)

Erros

​POST /workflow-endpoints/{entrypoint_key}

​Corpo da requisição

​Resposta (202, WorkflowExecutionAcceptedResponse)

​Erros

​GET /workflow-executions/{execution_uuid}

​Resposta (WorkflowExecutionReadResponse)

​Erros

`POST /workflow-endpoints/{entrypoint_key}`

Corpo da requisição

Resposta (`202`, `WorkflowExecutionAcceptedResponse`)

Erros

`GET /workflow-executions/{execution_uuid}`

Resposta (`WorkflowExecutionReadResponse`)

Erros