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

# Obter status de um run

> Retorna o status e resultado de um run específico.

- Run em execução → `202` com `status: running`
- Run finalizado → `200` com decisão completa




## OpenAPI

````yaml GET /api/v1/bureau/runs/{run_id}
openapi: 3.0.3
info:
  title: kycert API
  version: '2026-06-03'
  description: >
    API KYC/AML para corretoras de câmbio autorizadas pelo Banco Central do
    Brasil.

    Permite rodar verificações de bureau em CPF ou CNPJ e receber o resultado
    via webhook.


    **Fluxo principal:**

    ```

    POST /runs → 202 (run_id) → [bureau processa 5–30s] → webhook entregue →
    agir

    ```
  contact:
    name: kycert
    url: https://kycert.com.br
  license:
    name: Proprietário
    url: https://kycert.com.br
servers:
  - url: https://admin.kycert.com.br
    description: Produção (sk_live_...)
  - url: https://admin.kycert.com.br
    description: Sandbox (sk_test_...)
security:
  - ApiKeyHeader: []
  - BearerToken: []
tags:
  - name: Runs
    description: Execução de bureau para CPF ou CNPJ
  - name: Customers
    description: Gestão de clientes do tenant
paths:
  /api/v1/bureau/runs/{run_id}:
    get:
      tags:
        - Runs
      summary: Obter status de um run
      description: |
        Retorna o status e resultado de um run específico.

        - Run em execução → `202` com `status: running`
        - Run finalizado → `200` com decisão completa
      operationId: getRun
      parameters:
        - name: run_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: ID do run retornado pelo POST /runs
        - name: x-kycert-api-version
          in: header
          required: false
          schema:
            type: string
            example: '2026-06-03'
      responses:
        '200':
          description: Run finalizado — resultado disponível
          headers:
            X-Request-Id:
              schema:
                type: string
                format: uuid
            X-Kycert-Api-Version:
              schema:
                type: string
            X-RateLimit-Limit:
              schema:
                type: integer
            X-RateLimit-Remaining:
              schema:
                type: integer
            X-RateLimit-Reset:
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunResult'
              example:
                run_id: 550e8400-e29b-41d4-a716-446655440000
                status: completed
                decision: approved
                operative_decision: null
                risk_band: baixo
                external_id: cust_abc123
                metadata:
                  channel: app_mobile
                created_at: '2026-06-12T14:00:00Z'
                completed_at: '2026-06-12T14:00:18Z'
                livemode: true
        '202':
          description: Run ainda em execução — aguarde o webhook com o resultado
          headers:
            X-Request-Id:
              schema:
                type: string
                format: uuid
            X-RateLimit-Remaining:
              schema:
                type: integer
          content:
            application/json:
              schema:
                type: object
                properties:
                  run_id:
                    type: string
                    format: uuid
                  status:
                    type: string
                    enum:
                      - running
                  livemode:
                    type: boolean
              example:
                run_id: 550e8400-e29b-41d4-a716-446655440000
                status: running
                livemode: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    RunResult:
      type: object
      properties:
        run_id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - queued
            - pending
            - running
            - completed
            - blocked
            - pending_review
            - partial
            - failed
          description: |
            Status atual do run:
            - queued / pending / running — em processamento
            - completed — finalizado com resultado
            - blocked — bloqueado por regra crítica
            - pending_review — aguardando análise manual do compliance officer
            - partial — resultado parcial (algumas fontes falharam)
            - failed — falha técnica — reenvie o run
        decision:
          type: string
          nullable: true
          enum:
            - approved
            - rejected
            - review
          description: |
            Decisão do bureau:
            - approved — aprovado para prosseguir
            - rejected — bloqueado por regra crítica (run com status blocked)
            - review — requer análise manual do compliance officer
            - null — run ainda em andamento ou com falha técnica
        operative_decision:
          type: string
          nullable: true
          enum:
            - approved
            - rejected
            - hold
          description: >
            Decisão operacional — difere de `decision` apenas quando fontes
            tier-1 falharam

            por erro técnico durante a execução.


            Valores possíveis: `approved`, `rejected`, `hold`, `null`.

            - hold — fontes críticas não concluíram; resultado incerto (ver
            `/analysis` para detalhes)

            - rejected — fonte crítica retornou INVALID com bloqueio

            - approved — todas as fontes críticas concluíram sem restrição


            **Quando `operative_decision` é `null`:** `run_analysis` ainda não
            foi gerado — tratar `decision` como definitivo.
        risk_band:
          type: string
          nullable: true
          enum:
            - baixo
            - medio
            - alto
          description: |
            Classificação de risco calculada pelo engine:
            - baixo — risco baixo, sem apontamentos relevantes
            - medio — risco médio, apontamentos de pendência identificados
            - alto — risco alto, apontamentos críticos identificados
            - null — run ainda não concluído
        external_id:
          type: string
          nullable: true
        metadata:
          type: object
          nullable: true
        created_at:
          type: string
          format: date-time
        completed_at:
          type: string
          nullable: true
          format: date-time
        template_name:
          type: string
          nullable: true
          description: Nome do template usado neste run
        summary_message:
          type: string
          nullable: true
          description: Mensagem human-readable da decisão gerada pelo engine
        manual_review:
          type: boolean
          description: >-
            true quando o run está aguardando revisão manual do compliance
            officer
        livemode:
          type: boolean
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
                - invalid_request_error
                - authentication_error
                - authorization_error
                - billing_error
                - server_error
            code:
              type: string
              description: Código específico do erro
            message:
              type: string
              description: Descrição legível do erro
            param:
              type: string
              nullable: true
              description: Campo que causou o erro (quando aplicável)
  responses:
    Unauthorized:
      description: API key ausente ou inválida
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            missing_api_key:
              value:
                error:
                  type: authentication_error
                  code: missing_api_key
                  message: API key ausente.
                  param: null
            invalid_api_key:
              value:
                error:
                  type: authentication_error
                  code: invalid_api_key
                  message: API key inválida ou inativa.
                  param: null
    Forbidden:
      description: Escopo insuficiente para esta operação
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              type: authorization_error
              code: insufficient_scope
              message: Esta chave não tem permissão para criar runs.
              param: null
    NotFound:
      description: Run não encontrado ou não pertence ao tenant
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              type: invalid_request_error
              code: run_not_found
              message: Run não encontrado.
              param: null
    InternalError:
      description: Falha interna — tente novamente com backoff exponencial
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              type: server_error
              code: internal_error
              message: Erro interno. Tente novamente.
              param: null
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: API key no header x-api-key (recomendado)
    BearerToken:
      type: http
      scheme: bearer
      description: API key como Bearer token no header Authorization

````