> ## 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. # Invocar um workflow pelo seu entrypoint HTTP > Inicia um workflow para um CPF ou CNPJ. A resposta é sempre imediata e nunca carrega um resultado: retorna o identificador da execução, consultado via GET /v1/workflow-executions/{execution_uuid} com a mesma chave de API. A chave precisa ser a vinculada a este entrypoint; qualquer outra chave responde 404, exista ou não o entrypoint. Enquanto um caso de revisão do mesmo subject e entrypoint estiver aberto, uma chamada repetida retorna a MESMA execução em vez de iniciar uma segunda. ## OpenAPI ````yaml POST /workflow-endpoints/{entrypoint_key} openapi: 3.1.0 info: description: Superfície pública da API para clientes autenticados por chave de API. title: NL Labs Gateway (Public API) version: 0.1.0 servers: - url: https://api.nlbs.ai security: [] tags: - description: Busca de entidades canônicas. name: entities - description: Criação, leitura, grafo e dossiê de análises. name: analyses - description: Relatório regulatório (COAF/SUSEP). name: reports - description: Triagem de mídia adversa. name: adverse-media - description: Versões do manifesto regulatório. name: regulatory - description: Versões do catálogo de regras do motor de risco. name: rules - description: Endpoints e eventos de webhook. name: webhooks - description: >- Entrypoints HTTP de workflow: invocar um workflow e consultar sua execução. name: workflow-endpoints paths: /workflow-endpoints/{entrypoint_key}: post: tags: - workflow-endpoints summary: Invocar um workflow pelo seu entrypoint HTTP description: >- Inicia um workflow para um CPF ou CNPJ. A resposta é sempre imediata e nunca carrega um resultado: retorna o identificador da execução, consultado via GET /v1/workflow-executions/{execution_uuid} com a mesma chave de API. A chave precisa ser a vinculada a este entrypoint; qualquer outra chave responde 404, exista ou não o entrypoint. Enquanto um caso de revisão do mesmo subject e entrypoint estiver aberto, uma chamada repetida retorna a MESMA execução em vez de iniciar uma segunda. operationId: invoke_workflow_entrypoint parameters: - description: Segmento de URL do entrypoint. in: path name: entrypoint_key required: true schema: description: Segmento de URL do entrypoint. title: Entrypoint Key type: string requestBody: content: application/json: schema: additionalProperties: false description: >- The payload an external client POSTs to `/v1/workflow-endpoints/{entrypoint_key}`. Exactly two fields, per the epic: the subject's document and free-form typed metadata. The model forbids unknown fields like every other model here, so a client that invents a third top-level key hears about it instead of having it silently dropped. properties: document: description: >- CPF ou CNPJ do subject. Aceito formatado ou não; é normalizado e seus dígitos verificadores são checados antes de qualquer outra coisa. minLength: 1 title: Document type: string metadata: additionalProperties: true description: >- Objeto livre carregado junto com o subject. Campos declarados no metadata_schema do entrypoint são validados por tipo e ficam legíveis pelas condições do workflow; campos não declarados são aceitos e armazenados, mas nenhuma condição os lê. Ver WorkflowEntrypointSummary.metadata_schema para o formato da declaração. title: Metadata type: object required: - document title: WorkflowEntrypointInvokeRequest type: object required: true responses: '202': content: application/json: schema: $ref: '#/components/schemas/WorkflowExecutionAcceptedResponse' description: Successful Response '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Chave de API ausente, malformada, expirada ou inválida. '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: A chave de API autenticada não tem o escopo necessário. '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Nenhum entrypoint alcançável nessa chave com essa credencial. '409': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- O workflow está pausado (detail: "workflow_paused"), o entrypoint está desligado (detail: "workflow_entrypoint_disabled"), ou o workflow não tem versão publicada ativa (detail: "workflow_not_published"). '413': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- O corpo excede o limite de payload do entrypoint (detail: "workflow_payload_too_large") ou a metadata excede o limite de metadata (detail: "workflow_metadata_too_large"). '422': content: application/json: schema: $ref: '#/components/schemas/WorkflowMetadataInvalidResponse' description: >- O documento não é um CPF ou CNPJ válido (detail: "workflow_invalid_document"), ou a metadata não satisfaz o schema declarado (detail: "workflow_metadata_invalid"), com cada campo problemático em `issues`. Um corpo de requisição malformado também cai aqui, com o `detail` padrão do FastAPI. '429': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- A chave de API excedeu o limite por minuto do entrypoint (detail: "workflow_rate_limited"). components: schemas: WorkflowExecutionAcceptedResponse: additionalProperties: false properties: case_uuid: anyOf: - format: uuid type: string - type: 'null' description: >- Identificador público do caso de revisão humana que esta execução abriu, ou nulo quando a execução ainda não chegou a um nó de fila. Numa chamada deduplicada, é o caso ABERTO que ocupava a chave de deduplicação, o mesmo que `execution_uuid` aponta. title: Case Uuid deduplicated: default: false description: >- True quando esta chamada NÃO criou uma execução porque já existe uma aberta para o mesmo tenant, subject e entrypoint. O identificador retornado é o dessa execução existente. title: Deduplicated type: boolean execution_uuid: description: Identificador público da execução, para consulta. format: uuid title: Execution Uuid type: string status: $ref: '#/components/schemas/WorkflowExecutionStatus' description: >- Estado no momento da resposta. `queued` significa aceito e não iniciado, seja porque o tenant está no teto de concorrência, seja porque o orquestrador ainda não pegou a execução. required: - execution_uuid - status title: WorkflowExecutionAcceptedResponse type: object ErrorResponse: properties: detail: description: Mensagem de erro pública e estável. examples: - Resource not found. title: Detail type: string required: - detail title: ErrorResponse type: object WorkflowMetadataInvalidResponse: additionalProperties: false properties: detail: description: Código estável de erro de negócio. title: Detail type: string issues: description: Cada campo de metadata que falhou, uma entrada por campo. items: $ref: '#/components/schemas/WorkflowValidationIssue' title: Issues type: array required: - detail title: WorkflowMetadataInvalidResponse type: object WorkflowExecutionStatus: enum: - queued - running - waiting_human - succeeded - failed - cancelled title: WorkflowExecutionStatus type: string WorkflowValidationIssue: additionalProperties: false properties: code: description: Identificador estável e legível por máquina do problema. title: Code type: string message: description: Explicação legível do problema. title: Message type: string node_key: anyOf: - type: string - type: 'null' description: >- Nó a que o problema pertence; nulo quando o problema é do grafo inteiro. title: Node Key required: - code - message title: WorkflowValidationIssue type: object ````