> ## 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 /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. A chave de deduplicação é ocupada pela EXECUÇÃO, não pelo caso de revisão: enquanto uma execução do mesma conta, subject e entrypoint estiver `queued`, `running` ou `waiting_human`, uma chamada repetida retorna a MESMA execução em vez de iniciar uma segunda, tenha ela chegado a um nó de mesa ou não. A chave só é liberada quando essa execução chega a `succeeded`, `failed` ou `cancelled`; decidir o caso de revisão sozinho não libera a chave enquanto o workflow ainda tem que rodar até seu nó final.



## OpenAPI

````yaml /anti-fraud-openapi.yaml post /workflow-endpoints/{entrypoint_key}
openapi: 3.1.0
info:
  description: >-
    API de Anti Fraude da NL Labs: análise de contraparte, relatórios, mídia
    adversa e webhooks, para clientes autenticados por chave de API.
  title: NL Labs API de Anti Fraude
  version: 0.1.0
servers:
  - url: https://api.nlbs.ai
security: []
tags:
  - description: Busca de entidades.
    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 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 /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. A chave
        de deduplicação é ocupada pela EXECUÇÃO, não pelo caso de revisão:
        enquanto uma execução do mesma conta, subject e entrypoint estiver
        `queued`, `running` ou `waiting_human`, uma chamada repetida retorna a
        MESMA execução em vez de iniciar uma segunda, tenha ela chegado a um nó
        de mesa ou não. A chave só é liberada quando essa execução chega a
        `succeeded`, `failed` ou `cancelled`; decidir o caso de revisão sozinho
        não libera a chave enquanto o workflow ainda tem que rodar até seu nó
        final.
      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
                `/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 pertence a um cliente de API sem empresa, então uma
            execução iniciada por ela nunca poderia ser lida de volta (detail:
            "workflow_api_client_without_company").
        '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 que não é um objeto JSON responde
            detail "workflow_invalid_json_body"; um objeto JSON com campo
            ausente ou de tipo errado responde 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"). O header `Retry-After` traz os segundos
            até a janela reiniciar.
      security:
        - APIKeyHeader: []
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 mesa.
            Numa chamada deduplicada, é o caso ABERTO da execução que já ocupava
            a chave de deduplicação (hoje uma execução não-terminal do mesma
            conta, subject e entrypoint, não mais um caso aberto), não a
            execução em si: se esse caso já foi decidido, o campo vem nulo aqui
            mesmo com a execução ainda em andamento, porque a leitura filtra por
            caso aberto.
          title: Case Uuid
        deduplicated:
          default: false
          description: >-
            True quando esta chamada NÃO criou uma execução porque já existe uma
            aberta para o mesma conta, subject e entrypoint. O identificador
            retornado é o dessa execução existente.
          title: Deduplicated
          type: boolean
        desk_uuid:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: >-
            Mesa do caso aberto, quando houver um e ele estiver em alguma fila
            agora. Nulo se não há caso aberto, ou se o caso está aberto mas
            entre posições, como no meio de uma escalada.
          title: Desk Uuid
        execution_uuid:
          description: Identificador público da execução, para consulta.
          format: uuid
          title: Execution Uuid
          type: string
        queue_uuid:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: >-
            Fila em que o caso aberto está AGORA, que pode não ser aquela em que
            entrou: uma escalada move o caso dentro da mesma mesa. Nulo se não
            há caso aberto, ou se o caso está aberto mas entre posições, como no
            meio de uma escalada.
          title: Queue Uuid
        status:
          $ref: '#/components/schemas/WorkflowExecutionStatus'
          description: >-
            Estado no momento da resposta. `queued` significa aceito e não
            iniciado, seja porque a conta 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
  securitySchemes:
    APIKeyHeader:
      in: header
      name: X-API-Key
      type: apiKey

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.