> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nlbs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflow endpoints

> Invocar um workflow publicado do tenant e ler sua execução

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

```json theme={null}
{ "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](/concepts/errors).

## `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. |