openapi: 3.1.0
info:
  title: Shiel ID Documentação
  description: >
    A API RESTful do serviço KYC da Shiel ID permite que os desenvolvedores acessem e interajam com recursos relacionados à verificação de identidade de clientes. 
     
    O KYC é essencial para garantir a conformidade regulatória e a segurança nas operações financeiras.
  version: 1.2.0
  contact:
    name: Shiel ID
    url: "https://shielid.com"
servers:
  - url: "https://api.shielid.com/api"
security:
  - basicAuth: []
tags:
  - name: Basic Auth
    description: |
      A autenticação básica (basic authentication) é um esquema de autenticação simples incorporado no protocolo HTTP, onde o cliente envia solicitações HTTP com o cabeçalho de autorização Authorization, que contém a palavra Basic seguida de um espaço e um nome de usuário e senha em texto plano, separados por dois pontos (:) utilizando base64.  
        
      Por exemplo, para autorizar o usuário 'test' com senha '@55w0rd', onde o usuário seria a API KEY e a senha a API SECRET. O cliente enviaria na requisição:  

      Authorization: Basic dGVzdDpANTV3MHJk

      Utilizando o postman ou o próprio test request e selecionando Basic Auth, a conversão para Base64 é feita automaticamente e para se autenticar basta inserir o Username e Password.
  - name: Webhook
    description: |
      Na Shiel ID, o Webhook é utilizado para notificar outros sistemas ou aplicativos sobre o progresso ou conclusão de processos de verificação.

      Quando um evento específico, como a finalização de uma verificação ou a alteração de status, ocorre, o Webhook envia uma notificação contendo os dados relevantes para a URL de destino configurada.

      Para configurar o webhook pelo dashboard, devemos seguir os seguintes passos:

      1. O primeiro passo é realizar o login no dashboard.
      2. Na coluna lateral, acesse "Configurações" > "Configuração de Webhook".
      3. Insira o endereço do endpoint que deseja receber as chamadas. (O endpoint precisa aceitar o método POST)

      Também é possível configurar via API — veja `setWebhook`, `removeWebhook`, `addOptionalWebhook`, `removeOptionalWebhook` e `getWebhooks` abaixo. A autenticação dessas chamadas usa as credenciais de API da conta (Basic Auth com `api_key`/`api_secret` — ver aba "Basic Auth"), da mesma forma que os demais endpoints.

      **URLs opcionais**

      Além da URL **principal**, é possível configurar até **3 URLs opcionais** que recebem o mesmo payload enviado à principal. Todas as URLs (principal + opcionais) compartilham o mesmo segredo da conta: a cada disparo, a Shiel ID envia o header `X-SHIELID-SECRET-TOKEN` para que o cliente verifique que a chamada recebida realmente veio da Shiel ID.

      Regras:
      - Uma URL opcional só pode ser adicionada se já existir uma principal configurada.
      - Remover a principal é bloqueado (`400`) enquanto houver opcionais — remova as opcionais antes.
      - Trocar a principal (`setWebhook`) é permitido mesmo com opcionais configuradas.
      - Adicionar uma URL já existente na lista de opcionais não tem efeito (idempotente); adicionar uma URL igual à principal é rejeitado (`400`).
      - Limite de 3 URLs opcionais por conta; adicionar além do limite é rejeitado (`400`).

      <details>
        <summary>Exemplo de estrutura para pessoas físicas a ser recebida pelo webhook</summary>
        
        ```json
        {
          "version": "v1.0",
          "document": {
            "type": "CNH",
            "spoofing": 0,
            "images": {
              "front": [
                "https://shielid.example.com/api/data/images/sample123/sample123/uniqueHash/document/frontImage.jpg"
              ],
              "back": [
                "https://shielid.example.com/api/data/images/sample123/sample123/uniqueHash/document/backImage.jpg"
              ]
            }
          },
          "face": {
            "gender": "M",
            "genderProb": 1,
            "age": "(25-32)",
            "ageProb": 0.85,
            "spoofing": 0,
            "images": [
              "https://shielid.example.com/api/data/images/sample123/sample123/uniqueHash/face/image1.jpg",
              "https://shielid.example.com/api/data/images/sample123/sample123/uniqueHash/face/image2.jpg",
              "https://shielid.example.com/api/data/images/sample123/sample123/uniqueHash/face/image3.jpg"
            ]
          },
          "ocr": [
            {
              "label": "name",
              "value": "JOÃO DA SILVA"
            },
            {
              "label": "cpf",
              "value": "123.456.789-00"
            },
            {
              "label": "birthday",
              "value": "01/01/1990"
            },
            {
              "label": "valid",
              "value": "01/01/2025"
            },
            {
              "label": "cnh",
              "value": "12345678900"
            },
            {
              "label": "rg",
              "value": "1234567"
            },
            {
              "label": "first_issue",
              "value": "01/01/2015"
            },
            {
              "label": "issue",
              "value": "02/01/2015"
            },
            {
              "label": "document_origin",
              "value": "RIO DE JANEIRO, RJ"
            }
          ],
          "status": "approved",
          "devices": [
            {
              "timestamp": 1732655395,
              "browser": "Mobile Safari",
              "browser_version": "18.1.1",
              "os": "iOS",
              "os_version": "18.1.1",
              "device": "iPhone",
              "brand": "Apple",
              "model": "iPhone",
              "device_type": "mobile",
              "ip": "123.45.67.89",
              "country": "BR",
              "state": "RJ",
              "city": "Rio de Janeiro",
              "zipcode": "20000",
              "provider": "Example ISP",
              "as": "AS12345 Example Network"
            }
          ],
          "currentStep": false,
          "hash": "uniqueHash",
          "userId": "sample123",
          "score": 95,
          "url": "https://shielid.example.com/kyc/sample123/uniqueHash",
          "email": {
            "id": 108,
            "client_id": "sample123",
            "hash": "uniqueHash",
            "status": 1,
            "updated_at": "2024-11-26 18:09:03",
            "created_at": "2024-11-26 18:08:50",
            "email": "example@email.com",
            "token": "123456",
            "token_created": "2024-11-26 18:08:50",
            "tries": 0,
            "database": "exampleDB"
          },
          "createdTimestamp": 1732655317,
          "finishedTimestamp": 1732661004
        }
        ```
      </details>

  - name: postMessage
    description: |
      **Visão Geral** 

      A integração via postMessage permite receber, em tempo real, o status do KYC na janela pai (aplicação que incorpora o iframe).

      **Como funciona**

      Sempre que o status do processo mudar, o Shiel ID enviará uma mensagem para a janela pai (parent window) com os dados da atualização.

      **Estrutura da mensagem**

      ```json
      {
        "status": "approved",
        "timestamp": "2025-08-12T15:30:45.123Z"
      }
      ```

      **Status possíveis**

      - `approved` – Verificação aprovada
      - `rejected` – Verificação rejeitada

      **Fluxo de integração**

      - Gere uma hash para a sessão e obtenha o hashChecker.
      - Insira o iframe do Shiel ID passando `hashChecker` e `hash` na URL.
      - O usuário realiza o KYC dentro do iframe.
      - O Shiel ID envia mensagens para a janela pai com o status atual.
      - Sua aplicação escuta o postMessage e toma ações (ex.: redirecionar, atualizar UI).

      Exemplo de listener (cliente)
      ```javascript
      // Verifique a origem conforme seu ambiente (produção/homologação)
      const ALLOWED_ORIGINS = [
        'https://api.shielid.com',
        'https://kyc.shielid.com'
      ];

      window.addEventListener('message', (event) => {
        if (!ALLOWED_ORIGINS.includes(event.origin)) return;

        const data = event.data;
        if (!data || typeof data !== 'object') return;

        const { status, timestamp } = data;

        switch (status) {
          case 'approved':
            // exemplo: redirecionar ou liberar acesso
            break;
          case 'rejected':
            // exemplo: exibir mensagem e permitir nova tentativa
            break;
          default:
            // outros estados intermediários, se aplicável
            break;
        }
      });
      ```

  - name: KYC e transações
    description: |
      Geração de hash para sessões de KYC (pessoas físicas e jurídicas) e para validação facial em transações.

  - name: Consultas de hash
    description: |
      Listagem de hashes por usuário e obtenção do detalhamento de uma hash (status, etapas, dados OCR, etc.).

  - name: KYB
    description: |
      Consulta de onboardings de pessoas jurídicas (KYB), incluindo lista paginada e dados completos de cada processo.

  - name: Validação e bases
    description: |
      Validação facial contra bases e consultas cadastrais/documentais (CPF).

  - name: Verificação por e-mail
    description: Envio e validação de token de verificação por e-mail.

  - name: Verificação por telefone
    description: Envio e validação de token de verificação por SMS/telefone.

  - name: Estatísticas
    description: |
      Métricas agregadas da sua conta, como contagem total de onboardings e transações por status.

  - name: Blacklist
    description: |
      Gerenciamento da blacklist de CPFs do grupo diretamente via API. Permite listar, adicionar e
      remover CPFs bloqueados.

      **Efeito do bloqueio:** um CPF na blacklist não pode realizar onboarding (KYC) nem validação
      facial em transação (transacional). Enquanto o bloqueio estiver ativo, a geração de hash para
      esse CPF é recusada. O bloqueio deixa de valer automaticamente quando expira (`until` no passado)
      ou ao ser removido via `removeBlacklist`.

      O campo `blocked_by` registra quem fez o bloqueio, para auditoria — texto livre cujo formato
      varia pela origem:
      - Bloqueado pelo **painel**: nome e e-mail do usuário do dashboard (ex.: `"Fulano de Tal (fulano@empresa.com)"`).
      - Bloqueado pela **API**: identifica a empresa dona da credencial, não uma pessoa — a API não tem
        conceito de usuário individual (ex.: `"API: Empresa LTDA (usr_abc123)"`).

  - name: Changelog
    description: |
      Todas as modificações relevantes da documentação pública da API Shiel ID são documentadas nesta seção.

      O formato segue [Keep a Changelog](https://keepachangelog.com/pt-BR/1.1.0/) e o projeto adere ao [Versionamento Semântico](https://semver.org/lang/pt-BR/). A versão da especificação (`info.version`) acompanha esta seção e as release notes abaixo.

      ## Release notes

      As release notes descrevem o que mudou na API para os integradores. Consulte também a especificação OpenAPI (`openapi.yaml`), que é a fonte canônica dos endpoints, parâmetros, corpos e respostas.

      ## [1.2.0] - 2026-08-17

      ### Adicionado

      - Endpoints para listar onboardings KYB de pessoas jurídicas e consultar os dados completos de um onboarding por hash.

      ## [1.1.1] - 2026-08-10

      ### Corrigido

      - Removidas propriedades locais inválidas de parâmetros reutilizáveis em `getNewHashKYC` e `getNewTransactionKYC`.
      - Alinhado o parâmetro de `getNewTransactionKYC` ao contrato implementado: `document` (CPF), em vez de `documentTransaction`.
      - Corrigidas estruturas incompatíveis com OpenAPI 3.1 em schemas anuláveis, responses reutilizáveis e corpos dos endpoints de OTP.

      ## [1.1.0] - 2026-08-05

      ### Corrigido

      - **Validade formal da especificação OpenAPI 3.1**
        - Declarada a versão do padrão no documento (`openapi: 3.1.0`).
        - Chaves de `paths` corrigidas para a sintaxe do padrão (barra inicial em todas as rotas).
        - Códigos de resposta com espaço em branco corrigidos para códigos HTTP válidos.
        - Esquema de autenticação `basicAuth` definido em `components.securitySchemes` e resolvido pelo requisito de segurança global.
        - Endpoint `checkFace` migrado de sintaxe OAS 2.0 (`in: body`) para `requestBody` compatível com OAS 3.x.

      ### Ajustes de consistência

      - Corrigida referência a `checkToken400` (definido como schema).
      - Normalizados tipos inválidos (`type: String`, `type: null`).
      - Schema `getHashs.hashList` alinhado ao formato real de resposta (lista de objetos).

      ## [1.0.0]

      Versão inicial da documentação pública da API.

x-tagGroups:
  - name: Autenticação
    tags:
      - Basic Auth
  - name: Referência da API
    tags:
      - Webhook
      - KYC e transações
      - Consultas de hash
      - KYB
      - Validação e bases
      - Verificação por e-mail
      - Verificação por telefone
      - Estatísticas
      - Blacklist
  - name: Changelog
    tags:
      - Changelog
paths:
  /getNewHashKYC:
    post:
      tags:
        - KYC e transações
      summary: Criar sessão de onboarding
      description: |
        Gera um novo hash para o processo de KYC. Existem dois tipos de processos na geração 
        do hash: o primeiro é voltado para pessoas físicas (PF), com a execução do KYC, e o segundo para
        pessoas jurídicas (PJ), no qual ocorre o envio de documento(s) para a extração de informações 
        dos sócios, permitindo que cada sócio realize seu respectivo KYC. Por padrão, quando uma
        hash de KYC é gerada, os módulos e regras dessa sessão são aplicados a partir da customização 
        de jornada do onboarding no dashboard.

      operationId: getNewHashKYC
      parameters:
        - $ref: "#/components/parameters/userId"
          description: (PF e PJ) String alphanumerico de até 48 caracteres para identificar o usuário, se não for enviado, iremos gerar uma nova e retornar ela na mensagem.
        - $ref: "#/components/parameters/customId"
          description: String alphanumerico de até 48 caracteres para identificar o usuário, este Id é customizável pelo usuário.
        - $ref: "#/components/parameters/personType"
          description: (PF e PJ) Tipo de pessoa, se física (pf - padrão) ou jurídica (pj).
        - $ref: "#/components/parameters/documentType"
          description:
            (PF) Tipo de documento, brasileiro (brazilian) ou estrangeiro (foreign). Caso não seja enviado, iremos considerar o documento como brasileiro
            e validar como CPF.
        - $ref: "#/components/parameters/documentExpected"
        - $ref: "#/components/parameters/returnUrl"
          description: (PF e PJ) URL para redirecionar o usuário após o KYC.
      responses:
        "200":
          description: |
            Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/getNewHashKYC"
        "400":
          $ref: "#/components/responses/BadRequest"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/notFound"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/unAuthorized"
  /getNewTransactionKYC:
    post:
      tags:
        - KYC e transações
      summary: Criar sessão de validação facial em transação
      description:
        Esta rota permite gerar novas hashes para processos de validação facial em transações.
        Ao gerar uma nova hash de transação, é necessário informar ao menos um dos parâmetros
        userId ou document (CPF), utilizados para identificar o usuário e associá-lo ao seu último KYC aprovado. Na etapa de validação facial,
        o usuário deve mover o rosto em duas direções diferentes, determinadas aleatoriamente pelo backend.

      operationId: getNewTransactionKYC
      parameters:
        - $ref: "#/components/parameters/userId"
          description: String alphanumerico de até 48 caracteres para identificar o usuário.
        - $ref: "#/components/parameters/document"
        - $ref: "#/components/parameters/returnUrl"
          description: URL para redirecionar o usuário após a aprovação da validação facial.
        - $ref: "#/components/parameters/customId"
          description: String alphanumerico de até 48 caracteres para identificar o usuário, este Id é customizável pelo usuário.
      responses:
        "200":
          description: |
            Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/getNewTransactionKYC"
        "400":
          $ref: "#/components/responses/BadRequest"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/notFound"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/unAuthorized"
  /getHashs:
    get:
      tags:
        - Consultas de hash
      summary: Listar hashes do usuário
      description: Obtenha as hashs especificas de um usuário, ou todos os hashs de KYC.
      operationId: getHashs
      parameters:
        - $ref: "#/components/parameters/userId"
          description: string alphanumerico de até 16 caracteres para identificar um usuário específico, se não for enviado, iremos retornar todos os hashs de todos os usuários.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/getHashs"
        "400":
          $ref: "#/components/responses/BadRequest"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/notFound"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/unAuthorized"

  /getHashData:
    get:
      tags:
        - Consultas de hash
      summary: Consultar detalhes da hash
      description: |
        Obtenha os detalhes a partir de uma hash do KYC. Os possíveis status da hash são: created, started, approved, rejected e pending.

        **Exemplo: resposta da etapa do documento frontal com status started**
        ```json
        {
            "success": true,
            "data": {
                "currentStep": "document_front",
                "hash": "NQeq3xvqoyx1g15FZaV1CGA3hpH0dZVK",
                "userId": "TCin0gJcqjhQYHV6",
                "score": 0,
                "status": "started",
                "url": "https://shielid.com/kyc/CwXwUh0QD9OpzACl/NQeq3xvqoyx1g15FZaV1CGA3hpH0dZVK",
                "email": {
                    "id": 109,
                    "client_id": "TCin0gJcqjhQYHV6",
                    "hash": "NQeq3xvqoyx1g15FZaV1CGA3hpH0dZVK",
                    "status": 1,
                    "updated_at": "2025-08-12 13:51:01",
                    "created_at": "2025-08-12 13:48:51",
                    "email": "email_exemplo@mail.com",
                    "token": "219438",
                    "token_created": "2025-08-12 13:48:51",
                    "tries": 0,
                    "database": "banco_exemplo"
                },
                "phone": "+5511123456789",
                "createdTimestamp": 1755017304,
                "finishedTimestamp": 1755017567
            }
        }
        ```
        **Exemplo: resposta final com o status de approved**
        ```json
        {
          "success": true,
          "data": {
              "type": "kyc",
              "document": {
                  "type": "CNH",
                  "spoofing": 0,
                  "images": {
                      "front": [
                          "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/TCin0gJcqjhQYHV6/NQeq3xvqoyx1g15FZaV1CGA3hpH0dZVK/document/front_[nome-da-imagem].jpg"
                      ],
                      "back": [
                          "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/TCin0gJcqjhQYHV6/NQeq3xvqoyx1g15FZaV1CGA3hpH0dZVK/document/back_[nome-da-imagem].jpg"
                      ]
                  }
              },
              "face": {
                  "gender": "M",
                  "genderProb": 0.8,
                  "age": "(48-58)",
                  "ageProb": 0.9,
                  "spoofing": 0,
                  "images": [
                      "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/TCin0gJcqjhQYHV6/NQeq3xvqoyx1g15FZaV1CGA3hpH0dZVK/face/look_forward_123456789_000.jpg",
                      "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/TCin0gJcqjhQYHV6/NQeq3xvqoyx1g15FZaV1CGA3hpH0dZVK/face/look_forward_123456789_001.jpg",
                      "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/TCin0gJcqjhQYHV6/NQeq3xvqoyx1g15FZaV1CGA3hpH0dZVK/face/look_forward_123456789_002.jpg",
                      "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/TCin0gJcqjhQYHV6/NQeq3xvqoyx1g15FZaV1CGA3hpH0dZVK/face/tilt_right_123456789_003.jpg",
                      "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/TCin0gJcqjhQYHV6/NQeq3xvqoyx1g15FZaV1CGA3hpH0dZVK/face/tilt_right_123456789_004.jpg",
                      "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/TCin0gJcqjhQYHV6/NQeq3xvqoyx1g15FZaV1CGA3hpH0dZVK/face/tilt_right_123456789_005.jpg",
                      "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/TCin0gJcqjhQYHV6/NQeq3xvqoyx1g15FZaV1CGA3hpH0dZVK/face/tilt_left_123456789_006.jpg",
                      "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/TCin0gJcqjhQYHV6/NQeq3xvqoyx1g15FZaV1CGA3hpH0dZVK/face/tilt_left_123456789_007.jpg",
                      "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/TCin0gJcqjhQYHV6/NQeq3xvqoyx1g15FZaV1CGA3hpH0dZVK/face/tilt_left_123456789_008.jpg",
                      "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/TCin0gJcqjhQYHV6/NQeq3xvqoyx1g15FZaV1CGA3hpH0dZVK/face/tilt_up_123456789_009.jpg",
                      "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/TCin0gJcqjhQYHV6/NQeq3xvqoyx1g15FZaV1CGA3hpH0dZVK/face/tilt_up_123456789_010.jpg",
                      "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/TCin0gJcqjhQYHV6/NQeq3xvqoyx1g15FZaV1CGA3hpH0dZVK/face/tilt_up_123456789_011.jpg",
                      "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/TCin0gJcqjhQYHV6/NQeq3xvqoyx1g15FZaV1CGA3hpH0dZVK/face/tilt_down_123456789_012.jpg",
                      "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/TCin0gJcqjhQYHV6/NQeq3xvqoyx1g15FZaV1CGA3hpH0dZVK/face/tilt_down_123456789_013.jpg",
                      "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/TCin0gJcqjhQYHV6/NQeq3xvqoyx1g15FZaV1CGA3hpH0dZVK/face/tilt_down_123456789_014.jpg"
                  ]
              },
              "ocr": [
                  {
                      "label": "name",
                      "value": "Nome exemplo"
                  },
                  {
                      "label": "cpf",
                      "value": "123.456.789-00"
                  },
                  {
                      "label": "document_number",
                      "value": "123456789"
                  },
                  {
                      "label": "birthday",
                      "value": "01/01/2001"
                  },
                  {
                      "label": "parents",
                      "value": "Nome do pai, nome da mãe"
                  },
                  {
                      "label": "confidence",
                      "value": "0.9"
                  },
                  {
                      "label": "useful_fields_count",
                      "value": "4"
                  },
                  {
                      "label": "fields_found",
                      "value": "['name', 'cpf_number', 'document_number', 'birth_date']"
                  },
                  {
                      "label": "rg",
                      "value": "00.000.000-0"
                  }
              ],
              "status": "approved",
              "devices": [
                  {
                      "timestamp": 1755017620,
                      "browser": "Chrome Mobile",
                      "browser_version": "139.0.0",
                      "os": "Android",
                      "os_version": "10",
                      "device": "K",
                      "brand": "Generic_Android",
                      "model": "K",
                      "device_type": "mobile",
                      "ip": "177.94.154.72",
                      "country": "BR",
                      "state": "SP",
                      "city": "São Paulo",
                      "zipcode": "01000",
                      "provider": "Vivo",
                      "as": "AS27699 TELEFÔNICA BRASIL S.A"
                  }
              ],
              "finishedTimestamp": 1755017807,
              "version": "v1.0",
              "consult": {
                  "name": null,
                  "document": "123.456.789-00",
                  "documentType": "cpf"
              },
              "currentStep": false,
              "hash": "NQeq3xvqoyx1g15FZaV1CGA3hpH0dZVK",
              "userId": "TCin0gJcqjhQYHV6",
              "score": 73,
              "url": "https://shielid.com/kyc/CwXwUh0QD9OpzACl/NQeq3xvqoyx1g15FZaV1CGA3hpH0dZVK",
              "email": {
                  "id": 109,
                  "client_id": "TCin0gJcqjhQYHV6",
                  "hash": "NQeq3xvqoyx1g15FZaV1CGA3hpH0dZVK",
                  "status": 1,
                  "updated_at": "2025-08-12 13:51:01",
                  "created_at": "2025-08-12 13:48:51",
                  "email": "email_exemplo@mail.com",
                  "token": "219438",
                  "token_created": "2025-08-12 13:48:51",
                  "tries": 0,
                  "database": "banco_exemplo"
              },
              "phone": "+5511123456789",
              "createdTimestamp": 1755017304
          }
        }
        ```
      operationId: getHashData
      parameters:
        - $ref: "#/components/parameters/hash"
          description: string alphanumerico de 32 caracteres usado para identificar uma hash de procedimento do KYC.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/getHashData"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/getHashData400"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/notFound"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/unAuthorized"

  /getKybHashes:
    get:
      tags:
        - KYB
      summary: Listar onboardings KYB
      description: |
        Retorna lista paginada de onboardings de pessoas jurídicas (KYB) vinculados à conta autenticada.

        Use `search` para localizar processos por dados da empresa e `status` para filtrar pelo estado
        do onboarding. Por padrão, resultados são ordenados por data de criação, do mais recente para
        o mais antigo.
      operationId: getKybHashes
      parameters:
        - name: page
          in: query
          required: false
          description: Página da lista a ser retornada.
          schema:
            type: integer
            minimum: 1
            default: 1
            example: 1
        - name: per_page
          in: query
          required: false
          description: Quantidade de itens por página.
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
            example: 50
        - name: search
          in: query
          required: false
          description: Termo de busca para localizar onboardings.
          schema:
            type: string
            maxLength: 255
            example: "Empresa Exemplo"
        - name: status
          in: query
          required: false
          description: Status do onboarding a ser retornado. Use `all` para não filtrar por status.
          schema:
            type: string
            enum:
              - approved
              - rejected
              - analysis
              - pending
              - all
            default: all
            example: all
        - name: order_by
          in: query
          required: false
          description: Campo usado para ordenar resultados.
          schema:
            type: string
            enum:
              - created_at
              - status
              - document_expected
            default: created_at
            example: created_at
        - name: order_direction
          in: query
          required: false
          description: Direção da ordenação.
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
            example: desc
      responses:
        "200":
          description: Lista paginada de onboardings KYB.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/KybHashListResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/unAuthorized"
        "422":
          description: Unprocessable Entity — parâmetros de consulta inválidos.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /getKybHashData:
    get:
      tags:
        - KYB
      summary: Consultar detalhes de onboarding KYB
      description: |
        Retorna dados completos de um onboarding de pessoa jurídica (KYB) a partir de sua hash.

        A hash deve pertencer à conta autenticada.
      operationId: getKybHashData
      parameters:
        - name: hash
          in: query
          required: true
          description: Hash do onboarding KYB.
          schema:
            type: string
            minLength: 1
            maxLength: 255
            example: "NQeq3xvqoyx1g15FZaV1CGA3hpH0dZVK"
      responses:
        "200":
          description: Dados completos do onboarding KYB.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/KybHashDetailResponse"
        "400":
          description: Bad Request — parâmetro `hash` ausente ou inválido.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/unAuthorized"
        "404":
          description: Not Found — hash inexistente ou não disponível para conta autenticada.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /getStats:
    get:
      tags:
        - Estatísticas
      summary: Estatísticas agregadas
      description: |
        Retorna a contagem agregada de onboardings e transações da sua conta, agrupadas por status.

        **Status considerados:**
        - `total` representa a soma de `approved` + `rejected`. Onboardings e transações em status intermediários (`created`, `started`, `pending`, etc.) **não** entram na contagem.
        - `approved`: onboardings/transações com status `approved`.
        - `rejected`: onboardings/transações com status `rejected`.

        **Cache:** o resultado é atualizado a cada 60 segundos. Mudanças recentes podem demorar até 1 minuto para refletir.

        **Rate limit:** 60 requisições por minuto.

        **Exemplo de resposta:**
        ```json
        {
          "onboardings": {
            "total": 1099,
            "approved": 912,
            "rejected": 187
          },
          "transactions": {
            "total": 4422,
            "approved": 4320,
            "rejected": 102
          }
        }
        ```
      operationId: getStats
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/getStats"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/unAuthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          description: Too Many Requests — rate limit (60/min) excedido.
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/getStats500"

  /getBlacklist:
    get:
      tags:
        - Blacklist
      summary: Listar CPFs bloqueados
      description: |
        Retorna a lista paginada dos CPFs atualmente bloqueados na blacklist do grupo. Entradas
        expiradas (com `until` no passado) são excluídas do resultado.

        Cada item contém:
        - `document`: CPF sem máscara (11 dígitos).
        - `until`: data de expiração no formato `"Y-m-d H:i:s"`.
        - `reason`: motivo do bloqueio (texto livre) ou `null`.
        - `blocked_by`: quem fez o bloqueio, para auditoria (texto livre). Ver descrição da aba "Blacklist".
      operationId: getBlacklist
      parameters:
        - name: limit
          in: query
          required: false
          description: Itens por página.
          schema:
            type: integer
            default: 25
            examples:
              - 25
        - name: page
          in: query
          required: false
          description: Página (padrão de paginação, `?page=N`).
          schema:
            type: integer
            default: 1
            examples:
              - 1
        - name: orderBy
          in: query
          required: false
          description: Ordena por `created_at`.
          schema:
            type: string
            default: desc
            enum:
              - asc
              - desc
            examples:
              - desc
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/getBlacklist"
        "403":
          $ref: "#/components/responses/Forbidden"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/unAuthorized"

  /checkBlacklist:
    get:
      tags:
        - Blacklist
      summary: Verificar se um CPF está bloqueado
      description: |
        Verifica se **um** CPF específico está bloqueado na blacklist do grupo — sem paginação,
        resposta única `blocked: true/false`. Para a lista paginada completa, use `getBlacklist`.

        **Grupo pai/filho:** um bloqueio feito por qualquer empresa do grupo (conta pai ou uma de suas
        contas filho) é espelhado em todos os tenants do grupo. Uma conta **pai** já vê os CPFs
        bloqueados pelos filhos, e uma conta **filho** também vê os bloqueados pelo pai ou por outro
        filho do mesmo grupo — é sempre a lista do grupo inteiro.

        Campos da resposta:
        - `blocked`: `true` se o CPF está bloqueado (e não expirado), `false` caso contrário.
        - `document`: CPF sem máscara (11 dígitos), sempre presente mesmo quando `blocked: false`.
        - `until`: `"Y-m-d H:i:s"` data de expiração.
        - `reason`: motivo do bloqueio.
        - `blocked_by`: quem bloqueou (auditoria). Ver descrição da aba "Blacklist".

        Entradas **expiradas** (`until` no passado) contam como `blocked: false`. O CPF pode ser enviado
        com ou sem máscara; a resposta sempre retorna sem máscara.
      operationId: checkBlacklist
      parameters:
        - name: cpf
          in: query
          required: true
          description: CPF com ou sem máscara.
          schema:
            type: string
            examples:
              - "529.982.247-25"
              - "52998224725"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/checkBlacklist"
        "422":
          description: |
            Unprocessable Entity — `cpf` ausente (`{ "success": false, "message": "O campo \"cpf\" é obrigatório" }`)
            ou com formato/dígito verificador inválido (`{ "success": false, "message": "Parâmetro \"cpf\" inválido." }`).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/blacklistError"
        "401":
          description: |
            Unauthorized — Basic Auth ausente/inválida, ou conta inativa.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/unAuthorized"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/blacklistError"

  /addBlacklist:
    post:
      tags:
        - Blacklist
      summary: Adicionar CPF na blacklist
      description: |
        Adiciona um CPF à blacklist do grupo. Falha se o CPF já estiver bloqueado.
      operationId: addBlacklist
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - cpf
                - until
              properties:
                cpf:
                  type: string
                  description: CPF com ou sem máscara.
                  example: "529.982.247-25"
                until:
                  type: string
                  description: Data futura de expiração no formato `Y-m-d H:i:s`. Obrigatório.
                  example: "2026-08-15 00:00:00"
                reason:
                  type: string
                  maxLength: 255
                  description: Motivo do bloqueio.
                  example: "fraude confirmada"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/addBlacklist"
        "400":
          description: |
            Bad Request — documento já bloqueado, ex.: `{ "success": false, "message": "Este documento já está bloqueado." }`
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/blacklistError"
        "422":
          description: |
            Unprocessable Entity — erro de validação (campo faltando, CPF com formato inválido, `until` no passado, etc.).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/blacklistError"
        "403":
          $ref: "#/components/responses/Forbidden"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/unAuthorized"

  /removeBlacklist:
    delete:
      tags:
        - Blacklist
      summary: Remover CPF da blacklist
      description: |
        Remove um CPF da blacklist do grupo. **Idempotente** — remover um CPF que não está bloqueado
        retorna `200`.
      operationId: removeBlacklist
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - cpf
              properties:
                cpf:
                  type: string
                  description: CPF com ou sem máscara.
                  example: "529.982.247-25"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/removeBlacklist"
        "422":
          description: |
            Unprocessable Entity — `cpf` ausente ou inválido, ex.: `{ "success": false, "message": "O campo \"cpf\" é obrigatório" }`
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/blacklistError"
        "403":
          $ref: "#/components/responses/Forbidden"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/unAuthorized"

  /setWebhook:
    post:
      tags:
        - Webhook
      summary: Configurar URL de webhook (principal)
      description: |
        Configura ou troca a URL **principal** do webhook. Afeta somente a principal — para URLs opcionais, use `addOptionalWebhook`/`removeOptionalWebhook`. A troca é permitida mesmo com opcionais já configuradas.
        O webhook será ativado para eventos específicos, enviando dados na URL configurada.
        Os status possíveis da hash são: created, started, approved, rejected e pending.
        A seguir, estão exemplos de status do KYC retornados pelo webhook:

        **Retorno com o status created**
        ```json
        {
          "currentStep": "email",
          "hash": "JSk9sBDdUa0y3OLTsdN9F1ZgjO6nV8CE",
          "userId": "aQhDXUsM3gO1I4ZC",
          "score": 0,
          "status": "created",
          "url": "https://shielid.com/kyc/CwXwUh0QD9OpzACl/JSk9sBDdUa0y3OLTsdN9F1ZgjO6nV8CE",
          "email": null,
          "phone": null,
          "createdTimestamp": 1755004604,
          "finishedTimestamp": 1755004604
        }
        ```

        **Retorno com o status started**
        ```json
        {
          "currentStep": "facial",
          "hash": "JSk9sBDdUa0y3OLTsdN9F1ZgjO6nV8CE",
          "userId": "aQhDXUsM3gO1I4ZC",
          "score": 0,
          "status": "started",
          "url": "https://shielid.com/kyc/CwXwUh0QD9OpzACl/JSk9sBDdUa0y3OLTsdN9F1ZgjO6nV8CE",
          "email": {
            "id": 105,
            "client_id": "aQhDXUsM3gO1I4ZC",
            "hash": "JSk9sBDdUa0y3OLTsdN9F1ZgjO6nV8CE",
            "status": 1,
            "updated_at": "2025-08-12 10:18:19",
            "created_at": "2025-08-12 10:17:58",
            "email": "email_exemplo@mail.com",
            "token": "908530",
            "token_created": "2025-08-12 10:17:58",
            "tries": 0,
            "database": "banco_exemplo"
          },
          "phone": "+5511123456789",
          "createdTimestamp": 1755004604,
          "finishedTimestamp": 1755004789
        }
        ```

        **Retorno com o status approved**
        ```json
        {
          "type": "kyc",
          "document": {
            "type": "CNH",
            "spoofing": 0,
            "images": {
              "front": [
                "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/aQhDXUsM3gO1I4ZC/JSk9sBDdUa0y3OLTsdN9F1ZgjO6nV8CE/document/[nome-da-imagem].jpg"
              ],
              "back": [
                "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/aQhDXUsM3gO1I4ZC/JSk9sBDdUa0y3OLTsdN9F1ZgjO6nV8CE/document/[nome-da-imagem].jpg"
              ]
            }
          },
          "face": {
            "gender": "M",
            "genderProb": 0.8,
            "age": "(28-38)",
            "ageProb": 0.9,
            "spoofing": 0,
            "images": [
              "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/aQhDXUsM3gO1I4ZC/JSk9sBDdUa0y3OLTsdN9F1ZgjO6nV8CE/face/look_forward_123456789_000.jpg",
              "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/aQhDXUsM3gO1I4ZC/JSk9sBDdUa0y3OLTsdN9F1ZgjO6nV8CE/face/look_forward_123456789_001.jpg",
              "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/aQhDXUsM3gO1I4ZC/JSk9sBDdUa0y3OLTsdN9F1ZgjO6nV8CE/face/look_forward_123456789_002.jpg",
              "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/aQhDXUsM3gO1I4ZC/JSk9sBDdUa0y3OLTsdN9F1ZgjO6nV8CE/face/tilt_right_123456789_003.jpg",
              "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/aQhDXUsM3gO1I4ZC/JSk9sBDdUa0y3OLTsdN9F1ZgjO6nV8CE/face/tilt_right_123456789_004.jpg",
              "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/aQhDXUsM3gO1I4ZC/JSk9sBDdUa0y3OLTsdN9F1ZgjO6nV8CE/face/tilt_right_123456789_005.jpg",
              "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/aQhDXUsM3gO1I4ZC/JSk9sBDdUa0y3OLTsdN9F1ZgjO6nV8CE/face/tilt_left_123456789_006.jpg",
              "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/aQhDXUsM3gO1I4ZC/JSk9sBDdUa0y3OLTsdN9F1ZgjO6nV8CE/face/tilt_left_123456789_007.jpg",
              "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/aQhDXUsM3gO1I4ZC/JSk9sBDdUa0y3OLTsdN9F1ZgjO6nV8CE/face/tilt_left_123456789_008.jpg",
              "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/aQhDXUsM3gO1I4ZC/JSk9sBDdUa0y3OLTsdN9F1ZgjO6nV8CE/face/tilt_up_123456789_009.jpg",
              "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/aQhDXUsM3gO1I4ZC/JSk9sBDdUa0y3OLTsdN9F1ZgjO6nV8CE/face/tilt_up_123456789_010.jpg",
              "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/aQhDXUsM3gO1I4ZC/JSk9sBDdUa0y3OLTsdN9F1ZgjO6nV8CE/face/tilt_up_123456789_011.jpg",
              "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/aQhDXUsM3gO1I4ZC/JSk9sBDdUa0y3OLTsdN9F1ZgjO6nV8CE/face/tilt_down_123456789_012.jpg",
              "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/aQhDXUsM3gO1I4ZC/JSk9sBDdUa0y3OLTsdN9F1ZgjO6nV8CE/face/tilt_down_123456789_013.jpg",
              "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/aQhDXUsM3gO1I4ZC/JSk9sBDdUa0y3OLTsdN9F1ZgjO6nV8CE/face/tilt_down_123456789_014.jpg"
            ]
          },
          "ocr": [
            {
              "label": "name",
              "value": "Nome exemplo"
            },
            {
              "label": "cpf",
              "value": "123.456.789-00"
            },
            {
              "label": "document_number",
              "value": "1234567890"
            },
            {
              "label": "birthday",
              "value": "01/01/2001"
            },
            {
              "label": "parents",
              "value": "Nome do pai, nome da mãe"
            },
            {
              "label": "confidence",
              "value": "0.9"
            },
            {
              "label": "useful_fields_count",
              "value": "4"
            },
            {
              "label": "fields_found",
              "value": "['name', 'cpf_number', 'document_number', 'birth_date']"
            },
            {
              "label": "rg",
              "value": "00.000.000-0"
            }
          ],
          "status": "approved",
          "devices": [
            {
              "timestamp": 1755004766,
              "browser": "Chrome Mobile",
              "browser_version": "139.0.0",
              "os": "Android",
              "os_version": "10",
              "device": "K",
              "brand": "Generic_Android",
              "model": "K",
              "device_type": "mobile",
              "ip": "177.94.154.72",
              "country": "BR",
              "state": "SP",
              "city": "São Paulo",
              "zipcode": "01000",
              "provider": "Vivo",
              "as": "AS27699 TELEFÔNICA BRASIL S.A"
            }
          ],
          "finishedTimestamp": 1755004842,
          "version": "v1.0",
          "consult": {
            "name": null,
            "document": "123.456.789-00",
            "documentType": "cpf"
          },
          "currentStep": false,
          "hash": "JSk9sBDdUa0y3OLTsdN9F1ZgjO6nV8CE",
          "userId": "aQhDXUsM3gO1I4ZC",
          "score": 74,
          "url": "https://shielid.com/kyc/CwXwUh0QD9OpzACl/JSk9sBDdUa0y3OLTsdN9F1ZgjO6nV8CE",
          "email": {
            "id": 105,
            "client_id": "aQhDXUsM3gO1I4ZC",
            "hash": "JSk9sBDdUa0y3OLTsdN9F1ZgjO6nV8CE",
            "status": 1,
            "updated_at": "2025-08-12 10:18:19",
            "created_at": "2025-08-12 10:17:58",
            "email": "email_exemplo@mail.com",
            "token": "908530",
            "token_created": "2025-08-12 10:17:58",
            "tries": 0,
            "database": "banco_exemplo"
          },
          "phone": "+5511123456789",
          "createdTimestamp": 1755004604
        }
        ```

         **Retorno com o status rejected**
        ```json
        {
          "type": "kyc",
          "document": {
            "type": "CNH",
            "spoofing": 0,
            "images": {
             "front": [
                "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/aQhDXUsM3gO1I4ZC/JSk9sBDdUa0y3OLTsdN9F1ZgjO6nV8CE/document/[nome-da-imagem].jpg"
              ],
              "back": [
                "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/aQhDXUsM3gO1I4ZC/JSk9sBDdUa0y3OLTsdN9F1ZgjO6nV8CE/document/[nome-da-imagem].jpg"
              ]
            }
          },
          "face": {
            "gender": "M",
            "genderProb": 0.8,
            "age": "(28-38)",
            "ageProb": 0.9,
            "spoofing": 0,
            "images": [
              "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/aQhDXUsM3gO1I4ZC/JSk9sBDdUa0y3OLTsdN9F1ZgjO6nV8CE/face/look_forward_123456789_000.jpg",
              "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/aQhDXUsM3gO1I4ZC/JSk9sBDdUa0y3OLTsdN9F1ZgjO6nV8CE/face/look_forward_123456789_001.jpg",
              "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/aQhDXUsM3gO1I4ZC/JSk9sBDdUa0y3OLTsdN9F1ZgjO6nV8CE/face/look_forward_123456789_002.jpg",
              "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/aQhDXUsM3gO1I4ZC/JSk9sBDdUa0y3OLTsdN9F1ZgjO6nV8CE/face/tilt_right_123456789_003.jpg",
              "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/aQhDXUsM3gO1I4ZC/JSk9sBDdUa0y3OLTsdN9F1ZgjO6nV8CE/face/tilt_right_123456789_004.jpg",
              "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/aQhDXUsM3gO1I4ZC/JSk9sBDdUa0y3OLTsdN9F1ZgjO6nV8CE/face/tilt_right_123456789_005.jpg",
              "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/aQhDXUsM3gO1I4ZC/JSk9sBDdUa0y3OLTsdN9F1ZgjO6nV8CE/face/tilt_left_123456789_006.jpg",
              "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/aQhDXUsM3gO1I4ZC/JSk9sBDdUa0y3OLTsdN9F1ZgjO6nV8CE/face/tilt_left_123456789_007.jpg",
              "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/aQhDXUsM3gO1I4ZC/JSk9sBDdUa0y3OLTsdN9F1ZgjO6nV8CE/face/tilt_left_123456789_008.jpg",
              "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/aQhDXUsM3gO1I4ZC/JSk9sBDdUa0y3OLTsdN9F1ZgjO6nV8CE/face/tilt_up_123456789_009.jpg",
              "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/aQhDXUsM3gO1I4ZC/JSk9sBDdUa0y3OLTsdN9F1ZgjO6nV8CE/face/tilt_up_123456789_010.jpg",
              "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/aQhDXUsM3gO1I4ZC/JSk9sBDdUa0y3OLTsdN9F1ZgjO6nV8CE/face/tilt_up_123456789_011.jpg",
              "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/aQhDXUsM3gO1I4ZC/JSk9sBDdUa0y3OLTsdN9F1ZgjO6nV8CE/face/tilt_down_123456789_012.jpg",
              "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/aQhDXUsM3gO1I4ZC/JSk9sBDdUa0y3OLTsdN9F1ZgjO6nV8CE/face/tilt_down_123456789_013.jpg",
              "https://kyc.shielid.com/api/v1/media/images/CwXwUh0QD9OpzACl/aQhDXUsM3gO1I4ZC/JSk9sBDdUa0y3OLTsdN9F1ZgjO6nV8CE/face/tilt_down_123456789_014.jpg"
            ]
          },
          "ocr": [
            {
              "label": "cpf",
              "value": "111.111.111-00"
            },
            {
              "label": "document_number",
              "value": "123456789"
            },
            {
              "label": "cpf_validation_failed",
              "value": "True"
            },
            {
              "label": "status",
              "value": "document_back_rejected"
            },
            {
              "label": "validation_reason",
              "value": "cpf_missing_or_invalid"
            },
            {
              "label": "useful_fields_count",
              "value": "2"
            },
            {
              "label": "fields_found",
              "value": "['cpf_number', 'document_number']"
            },
            {
              "label": "birthday",
              "value": "01/01/1990"
            },
            {
              "label": "rg",
              "value": "00.000.000-0"
            }
          ],
          "status": "rejected",
          "devices": [
            {
              "timestamp": 1755006491,
              "browser": "Chrome Mobile",
              "browser_version": "139.0.0",
              "os": "Android",
              "os_version": "10",
              "device": "K",
              "brand": "Generic_Android",
              "model": "K",
              "device_type": "mobile",
              "ip": "177.94.154.72",
              "country": "BR",
              "state": "SP",
              "city": "São Paulo",
              "zipcode": "01000",
              "provider": "Vivo",
              "as": "AS27699 TELEFÔNICA BRASIL S.A"
            }
          ],
          "finishedTimestamp": 1755006733,
          "version": "v1.0",
          "consult": {
            "name": null,
            "document": "111.111.111-00",
            "documentType": "cpf"
          },
          "currentStep": false,
          "hash": "c726s8LHzeLEPfyLLaTm979T4DDZxK8j",
          "userId": "iRJvCBV88VGtwHL0",
          "score": 25,
          "url": "https://shielid.com/kyc/CwXwUh0QD9OpzACl/c726s8LHzeLEPfyLLaTm979T4DDZxK8j",
          "email": {
            "id": 106,
            "client_id": "iRJvCBV88VGtwHL0",
            "hash": "c726s8LHzeLEPfyLLaTm979T4DDZxK8j",
            "status": 1,
            "updated_at": "2025-08-12 10:44:31",
            "created_at": "2025-08-12 10:43:59",
            "email": "email_exemplo@mail.com",
            "token": "400733",
            "token_created": "2025-08-12 10:43:59",
            "tries": 0,
            "database": "banco_exemplo"
          },
          "phone": "+5511123456789",
          "createdTimestamp": 1755006183,
        }
        ```
      operationId: setWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - url
              properties:
                url:
                  type: string
                  description: Endereço completo (URL) onde o webhook enviará os dados. Deve ser uma URL válida, acessível via HTTP ou HTTPS.
                  example: "https://example.com/webhook"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/setWebhook"
        "400":
          $ref: "#/components/responses/BadRequest"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/notFound"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/unAuthorized"

  /removeWebhook:
    post:
      tags:
        - Webhook
      summary: Remover webhook (principal)
      description: |
        Remove a URL **principal**. Bloqueado com `400` enquanto houver URLs opcionais configuradas — remova as opcionais primeiro (`removeOptionalWebhook`), para evitar opcionais órfãs.
      operationId: removeWebhook
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/removeWebhook"
        "400":
          description: |
            Bad Request — ex.: `{ "success": false, "message": "Remova as URLs opcionais antes de remover a principal." }`
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/notFound"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/unAuthorized"

  /addOptionalWebhook:
    post:
      tags:
        - Webhook
      summary: Adicionar URL opcional de webhook
      description: |
        Adiciona uma URL **opcional** à lista (até 3 por conta). Faz append — não remove as URLs já existentes. Exige que a principal já esteja configurada (`setWebhook`).

        - URL repetida (já presente na lista): idempotente, não retorna erro.
        - URL igual à principal: rejeitada com `400`.
        - Lista já no limite de 3: rejeitada com `400`.
      operationId: addOptionalWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - url
              properties:
                url:
                  type: string
                  description: Endereço completo (URL) a adicionar como opcional. Deve ser uma URL válida, acessível via HTTP ou HTTPS.
                  example: "https://backup.example.com/webhook"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/addOptionalWebhook"
        "400":
          description: |
            Bad Request — ex.: `{ "success": false, "message": "Limite de 3 URLs opcionais atingido. Remova uma antes de adicionar." }`
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/notFound"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/unAuthorized"

  /removeOptionalWebhook:
    post:
      tags:
        - Webhook
      summary: Remover URL opcional de webhook
      description: |
        Remove **apenas** a URL opcional informada — nunca limpa a lista inteira. A URL precisa existir na lista de opcionais, senão retorna `400`.
      operationId: removeOptionalWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - url
              properties:
                url:
                  type: string
                  description: URL opcional a remover (precisa bater exatamente com a URL configurada).
                  example: "https://backup.example.com/webhook"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/removeOptionalWebhook"
        "400":
          description: |
            Bad Request — ex.: `{ "success": false, "message": "URL não encontrada na lista de opcionais." }`
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/notFound"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/unAuthorized"

  /getWebhooks:
    get:
      tags:
        - Webhook
      summary: Consultar URLs de webhook configuradas
      description: |
        Retorna a URL principal e a lista de URLs opcionais configuradas na conta. Nunca retorna o segredo compartilhado.
      operationId: getWebhooks
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/getWebhooks"
        "400":
          $ref: "#/components/responses/BadRequest"
        "403":
          $ref: "#/components/responses/Forbidden"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/unAuthorized"

  /checkFace:
    post:
      tags:
        - Validação e bases
      summary: Validar face com base cadastral
      description: |
        Utiliza a base de dados para validação da face enviada com o documento (CPF).
      operationId: checkFace
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/checkFaceRequest"
      responses:
        "200":
          description: |
            Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/checkFace"
        "400":
          $ref: "#/components/responses/BadRequest"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/notFound"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/unAuthorized"

  /consultDocument:
    post:
      tags:
        - Validação e bases
      summary: Consultar CPF na base
      description: |
        Consulta modular de CPF nas bases integradas. O parâmetro `consultType` define quais módulos
        serão retornados — pode ser um único módulo, vários módulos combinados pelo separador `+`,
        ou `full` para retornar a consulta completa.

        > **Importante:** os módulos disponíveis para consulta são definidos **por contrato**. Apenas
        > os módulos contratados pelo cliente podem ser solicitados. Solicitações a módulos não
        > contratados resultam em erro ou em retorno vazio para o bloco correspondente. Para revisar
        > ou alterar os módulos contratados, contate o time comercial da Shielid.

        **Módulos disponíveis (`consultType`):**
        - `full` — consulta completa, limitada aos módulos contratados. Padrão quando o parâmetro é omitido.
        - `dados_cadastrais` — status do CPF, nome, data de nascimento, gênero, nome da mãe, etc.
        - `telefone` — telefones associados ao CPF.
        - `email` — e-mails associados ao CPF.
        - `endereco` — endereços associados ao CPF.
        - `pep_listas` — PEP (pessoa politicamente exposta), sanções e histórico.
        - `beneficios_governo` — benefícios sociais (ex.: Bolsa Família).
        - `impedidos_apostar` — restrições de apostas esportivas.
        - `dados_financeiros` — dados financeiros do CPF. Módulo extra, **não incluso no `full`** — deve ser habilitado separadamente por contrato e combinado via `+` quando necessário.
        - `consult_cnh` — dados da CNH (Carteira Nacional de Habilitação). Módulo extra, **não incluso no `full`** — habilitado separadamente por contrato.

        > **Consulta de veículo:** para consulta por placa, utilize o endpoint `/consultVehicle` (requer habilitação separada por contrato).

        **Combinação de módulos:** envie os módulos separados por `+` **no body** da requisição. Exemplos:
        - `{"consultType": "telefone+email"}`
        - `{"consultType": "dados_cadastrais+pep_listas+endereco"}`

        **Compatibilidade:** o valor numérico legado `6` é aceito e equivale a `full` (usa o `module_consult`
        configurado para o usuário; quando ausente, retorna `full`).
      operationId: consultDocument
      parameters:
        - $ref: "#/components/parameters/consultDocument"
        - $ref: "#/components/parameters/consulType"
      responses:
        "200":
          description: |
            Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/consultDocumentCPF"
        "400":
          $ref: "#/components/responses/BadRequest"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/notFound"
        "422":
          description: |
            Unprocessable Entity — `consultType` inválido (módulo desconhecido).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/consultTypeInvalid"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/unAuthorized"

  /consultVehicle:
    post:
      tags:
        - Validação e bases
      summary: Consultar veículo por placa
      description: |
        Consulta dados completos de um veículo a partir da placa (formato antigo AAA0000 ou Mercosul AAA0A00).

        > **Importante:** este endpoint é independente do `/consultDocument`. O acesso é controlado
        > pelo módulo `consult_vehicle` no contrato do cliente. Para habilitar, contate o time comercial da Shielid.

        Os dados retornados incluem: marca, modelo, ano de fabricação/modelo, cor, renavam, situação,
        município/UF de registro, proprietário (documento mascarado) e demais atributos disponíveis na base Netrin.
      operationId: consultVehicle
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - plate
              properties:
                plate:
                  type: string
                  description: Placa do veículo. Aceita formato antigo (AAA0000) ou Mercosul (AAA0A00). Caracteres não alfanuméricos são ignorados.
                  examples:
                    - "ABC1234"
                    - "ABC1D23"
      responses:
        "200":
          description: Ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    examples:
                      - true
                  data:
                    type: object
                    description: Dados do veículo (dadosVeiculoCompleto da Netrin).
                    properties:
                      placa:
                        type: string
                        example: "AAA0000"
                      chassi:
                        type: [string, "null"]
                        example: "9BWZZZ000YB000000"
                      numeroMotor:
                        type: [string, "null"]
                        example: "X00000000"
                      estadoPlaca:
                        type: [string, "null"]
                        example: "SP"
                      cidadePlaca:
                        type: [string, "null"]
                        example: "SAO PAULO"
                      renavam:
                        type: [string, "null"]
                        example: "00000000000"
                      tipoDocumentoFaturado:
                        type: [string, "null"]
                        example: "CNPJ"
                      numeroIdentificacaoFaturado:
                        type: [string, "null"]
                        example: "00000000000000"
                      estadoNotaFiscal:
                        type: [string, "null"]
                        example: "PR"
                      anoFabricacao:
                        type: [integer, "null"]
                        example: 2007
                      anoModelo:
                        type: [integer, "null"]
                        example: 2007
                      capacidadeMaxTracao:
                        type: [integer, "null"]
                        example: 210
                      pesoBrutoTotal:
                        type: [integer, "null"]
                        example: null
                      indicadorRestricaoRenainf:
                        type: [boolean, "null"]
                        example: false
                      indicadorRestricaoRenajud:
                        type: [boolean, "null"]
                        example: false
                      indicadorRestricaoRfb:
                        type: [boolean, "null"]
                        example: false
                      rouboOuFurto:
                        type: [boolean, "null"]
                        example: false
                      ocorrencia:
                        type: [string, "null"]
                        example: "SEM RESTRIÇÃO"
                      recall:
                        type: [boolean, "null"]
                        example: false
                      reclamacaoSeguro:
                        type: [boolean, "null"]
                        example: false
                      statusVeiculo:
                        type: [string, "null"]
                        example: null
                      marcaModelo:
                        type: [string, "null"]
                        example: "MARCA/MODELO EXEMPLO"
                      tipoVeiculo:
                        type: [string, "null"]
                        example: "AUTOMÓVEL"
                      tipoTracao:
                        type: [string, "null"]
                        example: "PASSAGEIRO"
                      cor:
                        type: [string, "null"]
                        example: "CINZA"
                      combustivel:
                        type: [string, "null"]
                        example: "ALCOOL/GASOLINA"
                      categoria:
                        type: [string, "null"]
                        example: "PARTICULAR"
                      origem:
                        type: [string, "null"]
                        example: "NACIONAL"
                      potencia:
                        type: [integer, "null"]
                        example: 79
                      eixo:
                        type: [integer, "null"]
                        example: 2
                      capacidade:
                        type: [integer, "null"]
                        example: 5
                      capacidadeTanqueCombustivel:
                        type: [integer, "null"]
                        example: 44
                      capacidadeCargaKg:
                        type: [integer, "null"]
                        example: 460
                      anoUltimaLicenca:
                        type: [integer, "null"]
                        example: 2025
                      nomeProprietario:
                        type: [string, "null"]
                        example: "NOME DO PROPRIETÁRIO"
                      documentoProprietario:
                        type: [string, "null"]
                        description: CPF ou CNPJ do proprietário.
                        example: "00000000000"
                      tipoDocumentoProprietario:
                        type: [string, "null"]
                        example: "CPF"
                      statusLicensa:
                        type: [string, "null"]
                        example: "regular"
                      dataFimLicensa:
                        type: [string, "null"]
                        example: "regular até 31 de outubro de 2026"
                  queriedAt:
                    type: [string, "null"]
                    description: Data e hora da consulta na fonte.
                    examples:
                      - "2026-05-14T12:00:00"
        "400":
          $ref: "#/components/responses/BadRequest"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          description: Unprocessable Entity — placa ausente ou formato inválido.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    examples:
                      - false
                  message:
                    type: string
                    examples:
                      - "Placa inválida. Utilize o formato AAA0000 (antigo) ou AAA0A00 (Mercosul)."
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/unAuthorized"

  /sendEmailToken:
    post:
      tags:
        - Verificação por e-mail
      summary: Enviar token por e-mail
      description: Envia um token de verificação para o e-mail do usuário.
      operationId: sendEmailToken
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - userId
              properties:
                email:
                  type: string
                  description: E-mail do usuário para envio do token de verificação.
                  example: "example@example.com.br"
                userId:
                  type: string
                  description: string alphanumerico de até 16 caracteres para identificar o usuário.
                  example: "lTXniLwvQdncO8ZQ"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/sendEmailToken"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/sendEmailToken400"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/notFound"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/unAuthorized"

  /checkEmailToken:
    post:
      tags:
        - Verificação por e-mail
      summary: Validar token de e-mail
      description: Verifica o token de verificação enviado para o e-mail do usuário.
      operationId: checkEmailToken
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - userId
                - email
                - code
              properties:
                userId:
                  type: string
                  description: string alphanumerico de até 16 caracteres para identificar o usuário.
                  example: "lTXniLwvQdncO8ZQ"
                email:
                  type: string
                  description: E-mail em que o token foi enviado.
                  example: "example@example.com.br"
                code:
                  type: string
                  description: Código de verificação enviado para o e-mail do usuário enviado pela chamada sendEmailToken.
                  example: "123456"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/checkEmailToken"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/checkToken400"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/notFound"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/unAuthorized"

  /sendPhoneToken:
    post:
      tags:
        - Verificação por telefone
      summary: Enviar token por SMS
      description: Envia um token de verificação para o número de telefone do usuário.
      operationId: sendPhoneToken
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - userId
                - countryCode
                - phone
              properties:
                userId:
                  type: string
                  description: string alphanumerico de até 16 caracteres para identificar o usuário.
                  example: "lTXniLwvQdncO8ZQ"
                countryCode:
                  type: string
                  description: Código do país do número de telefone do usuário.
                  example: "55"
                phone:
                  type: string
                  description: Número de telefone em que o token foi enviado.
                  example: "11999999999"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/sendPhoneToken"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/sendPhoneToken400"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/notFound"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/unAuthorized"

  /checkPhoneToken:
    post:
      tags:
        - Verificação por telefone
      summary: Validar token de telefone
      description: Verifica o token de verificação enviado para o número de telefone do usuário.
      operationId: checkPhoneToken
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - userId
                - code
                - countryCode
                - phone
              properties:
                userId:
                  type: string
                  description: string alphanumerico de até 16 caracteres para identificar o usuário.
                  example: "lTXniLwvQdncO8ZQ"
                code:
                  type: string
                  description: Código de verificação enviado para o número de telefone do usuário enviado pela chamada sendPhoneToken.
                  example: "123456"
                countryCode:
                  type: string
                  description: Código do país do número de telefone do usuário.
                  example: "55"
                phone:
                  type: string
                  description: Número de telefone em que o token foi enviado.
                  example: "11999999999"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/checkPhoneToken"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/checkToken400"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/notFound"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/unAuthorized"

components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic

  parameters:
    allowPep:
      name: allowPep
      in: query
      required: false
      schema:
        type: boolean
        default: "true"
        examples:
          - true
    allowBettingBan:
      name: allowBettingBan
      in: query
      required: false
      schema:
        type: boolean
        default: "true"
        examples:
          - true
    allowSocialBenefits:
      name: allowSocialBenefits
      in: query
      required: false
      schema:
        type: boolean
        default: "true"
        examples:
          - true
    userId:
      name: userId
      in: query
      required: false
      schema:
        type: string
        examples:
          - "a1b2c3d4f5"
    document:
      name: document
      in: query
      required: false
      description: Número do CPF (sem pontos ou traços) para identificar o usuário.
      schema:
        type: string
        examples:
          - "12345678910"
    documentType:
      name: documentType
      in: query
      required: false
      schema:
        type: string
        examples:
          - brazilian
          - foreign
    consultDocument:
      name: document
      in: query
      required: true
      description: CPF (somente dígitos, sem formatação) a ser consultado.
      schema:
        type: string
        pattern: "^[0-9]{11}$"
        example: "07068093868"
    consulType:
      name: consultType
      in: query
      required: false
      description: |
        Tipo de consulta modular. Aceita um único módulo, vários módulos combinados por `+`, ou `full`.
        Quando omitido, usa o `module_consult` configurado para o usuário (ou `full` se não houver).
        Valores aceitos: `full`, `dados_cadastrais`, `telefone`, `email`, `endereco`,
        `pep_listas`, `beneficios_governo`, `impedidos_apostar`, `dados_financeiros`, `consult_cnh`.
        Valor legado: `6` (equivale a `full`). O módulo `consult_vehicle` **não é aceito** neste endpoint
        — use `/consultVehicle` para consulta de veículo.
        **Os módulos efetivamente disponíveis são definidos por contrato** — apenas módulos
        contratados pelo cliente podem ser solicitados.
      schema:
        type: string
        examples:
          - "full"
          - "dados_cadastrais"
          - "telefone+email"
          - "dados_cadastrais+pep_listas+endereco"
          - "6"
    clientId:
      name: clientId
      in: query
      required: true
      schema:
        type: string
        examples:
          - "a1b2c3d4f5"
    customId:
      name: customId
      in: query
      required: false
      schema:
        type: string
        examples:
          - "a1b2c3d4f5"
    phone:
      name: phone
      in: query
      required: false
      schema:
        type: boolean
        default: "false"
        examples:
          - false
    email:
      name: email
      in: query
      required: false
      schema:
        type: boolean
        default: "false"
        examples:
          - true
    facial:
      name: facial
      in: query
      required: false
      schema:
        type: boolean
        default: "true"
        examples:
          - true
    checkEmail:
      name: email
      in: query
      required: true
      schema:
        type: string
        examples:
          - example@example.com.br
    checkPhone:
      name: phone
      in: query
      required: true
      schema:
        type: string
        examples:
          - "11999999999"
    countryCode:
      name: countryCode
      in: query
      required: false
      schema:
        type: string
        examples:
          - "55"
    checkDocument:
      name: checkDocument
      in: query
      required: false
      schema:
        type: boolean
        examples:
          - true
    validateData:
      name: validateData
      in: query
      required: false
      schema:
        type: boolean
        examples:
          - true
    returnUrl:
      name: returnUrl
      in: query
      required: false
      schema:
        type: string
        examples:
          - https://shielid.com
    code:
      name: code
      in: query
      required: true
      schema:
        type: string
        examples:
          - "123456"
    hash:
      name: hash
      in: query
      required: true
      schema:
        type: string
        examples:
          - dRkar0x5aUEvoKnZhhvxAp6oIBklMk0K
    personType:
      name: personType
      in: query
      required: false
      schema:
        type: string
        examples:
          - pf
          - pj
    documentExpected:
      name: documentExpected
      in: query
      required: true
      description: (PF) Número de CPF do usuário, aceito com ou sem máscara (por exemplo, `12345678900` ou `123.456.789-00`).
      schema:
        type: string
        examples:
          - "12345678900"
          - "123.456.789-00"
  responses:
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    NotFound:
      description: NotFound
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
  schemas:
    Authentication:
      type: string
    BRBTC-FROM-ACCOUNT:
      type: string
    ErrorResponse:
      type: object
      required:
        - success
        - message
      properties:
        success:
          type: boolean
          const: false
        message:
          type: string
    KybHashListResponse:
      type: object
      required:
        - success
        - data
        - meta
      properties:
        success:
          type: boolean
          const: true
        data:
          type: array
          items:
            $ref: "#/components/schemas/KybHashListItem"
        meta:
          $ref: "#/components/schemas/PaginationMeta"
    KybHashListItem:
      type: object
      required:
        - hash
        - cnpj
        - razao_social
        - situacao
        - status
        - status_label
        - display_status
        - database
        - created_at
      properties:
        hash:
          type: string
        cnpj:
          type:
            - string
            - "null"
        razao_social:
          type:
            - string
            - "null"
        situacao:
          type:
            - string
            - "null"
        status:
          type: integer
        status_label:
          $ref: "#/components/schemas/KybStatusLabel"
        display_status:
          type: string
          enum:
            - regular
            - bloqueada
            - com_restricao
            - pending
        database:
          type: string
        created_at:
          type:
            - string
            - "null"
          format: date-time
    KybHashDetailResponse:
      type: object
      required:
        - success
        - data
      properties:
        success:
          type: boolean
          const: true
        data:
          $ref: "#/components/schemas/KybHashDetail"
    KybHashDetail:
      type: object
      required:
        - hash
        - cnpj
        - status
        - status_label
        - display_status
        - database
        - created_at
        - company
        - contrato_social
        - validacao_socios
        - rejection
        - compliance
        - decision
        - reviews
      properties:
        hash:
          type: string
        cnpj:
          type:
            - string
            - "null"
        status:
          type: integer
        status_label:
          $ref: "#/components/schemas/KybStatusLabel"
        display_status:
          type: string
          enum:
            - regular
            - bloqueada
            - com_restricao
            - pending
        database:
          type: string
        created_at:
          type:
            - string
            - "null"
          format: date-time
        company:
          $ref: "#/components/schemas/KybCompany"
        contrato_social:
          $ref: "#/components/schemas/KybSocialContract"
        validacao_socios:
          $ref: "#/components/schemas/KybPartnersValidation"
        rejection:
          anyOf:
            - $ref: "#/components/schemas/KybRejection"
            - type: "null"
        compliance:
          type:
            - object
            - "null"
          additionalProperties: true
        decision:
          type:
            - object
            - "null"
          additionalProperties: true
        reviews:
          type: array
          items:
            $ref: "#/components/schemas/KybReview"
    KybCompany:
      type: object
      required:
        - razao_social
        - nome_fantasia
        - situacao
        - situacao_especial
        - simples_nacional
        - capital_social
        - abertura
        - natureza_juridica
        - cnae
        - endereco
        - validated
      properties:
        razao_social:
          type:
            - string
            - "null"
        nome_fantasia:
          type:
            - string
            - "null"
        situacao:
          type:
            - string
            - "null"
        situacao_especial:
          type:
            - string
            - "null"
        simples_nacional: {}
        capital_social: {}
        abertura: {}
        natureza_juridica: {}
        cnae: {}
        endereco: {}
        validated:
          type: boolean
    KybSocialContract:
      type: object
      required:
        - uploaded
        - pages
      properties:
        uploaded:
          type: boolean
        type:
          type:
            - string
            - "null"
        pages:
          type: array
          items: {}
        ocr:
          type: array
          items: {}
        owners:
          type: array
          items: {}
    KybPartnersValidation:
      type: object
      required:
        - result
        - details
        - socios
      properties:
        result:
          type: string
          enum:
            - pending
            - cnpj_mismatch
            - divergence
            - match_total
        details: {}
        socios:
          type: array
          items:
            $ref: "#/components/schemas/KybPartner"
    KybPartner:
      type: object
      required:
        - id
        - nome
        - qualificacao
        - documento
        - qsa_status
        - qsa_review
        - kyc_status
        - kyc_hash
      properties:
        id:
          type:
            - integer
            - "null"
        nome:
          type:
            - string
            - "null"
        qualificacao:
          type:
            - string
            - "null"
        documento:
          type:
            - string
            - "null"
        qsa_status:
          type: string
          enum:
            - pendente
            - identificado
            - divergente
            - nao_encontrado
        qsa_review:
          type:
            - string
            - "null"
        kyc_status:
          anyOf:
            - $ref: "#/components/schemas/KybStatusLabel"
            - type: "null"
        kyc_hash:
          type:
            - string
            - "null"
    KybRejection:
      type: object
      required:
        - reason
        - factor
        - cnpj
        - names
      properties:
        reason:
          type:
            - string
            - "null"
        factor:
          type:
            - string
            - "null"
        cnpj: {}
        names:
          anyOf:
            - type: object
              required:
                - extracted
                - expected
              properties:
                extracted:
                  type:
                    - string
                    - "null"
                expected:
                  type:
                    - string
                    - "null"
            - type: "null"
    KybReview:
      type: object
      required:
        - status
        - reasons
        - created_at
      properties:
        status: {}
        reasons:
          type: array
          items: {}
        created_at:
          type:
            - string
            - "null"
          format: date-time
    KybStatusLabel:
      type: string
      enum:
        - created
        - started
        - pending
        - approved
        - rejected
        - error
        - analysis
        - manually_approved
        - manually_rejected
        - manually_blocked
        - unknown
    PaginationMeta:
      type: object
      required:
        - current_page
        - last_page
        - per_page
        - total
        - from
        - to
      properties:
        current_page:
          type: integer
        last_page:
          type: integer
        per_page:
          type: integer
        total:
          type: integer
        from:
          type: integer
        to:
          type: integer
    getNewHashKYC:
      type: object
      properties:
        success:
          type: boolean
          description: Indica se a requisição foi bem sucedida.
          examples:
            - true
        hash:
          type: string
          examples:
            - dRkar0x5aUEvoKnZhhvxAp6oIBklMk0K
        hashChecker:
          type: string
          examples:
            - test123
        userId:
          type: string
          examples:
            - nQvYpZxTgLmRbHcFkAjD-eWqXsOtUiVnMzCrKjGhBy
        type:
          type: string
          examples:
            - kyc
        status:
          type: string
          examples:
            - created
        personType:
          type: string
          examples:
            - pf
            - pj
        steps:
          type: array
          items:
            type: string
          example:
            - email
            - document_front
            - document_back
            - facial
        currentStep:
          type: string
          examples:
            - email
        checkDocument:
          oneOf:
            - type: integer
            - type: string
          examples:
            - 6
            - "1"
            - "2"
            - "3"
            - "4"
            - "5"
            - "6"
        validateData:
          type: integer
          examples:
            - 1
        documentExpected:
          type: [string, "null"]
          examples:
            - "12345678900"
            - null
        returnUrl:
          type: string
          examples:
            - https://shielid.com
        url:
          type: string
          examples:
            - https://shielid.com/kyc/test123/dRkar0x5aUEvoKnZhhvxAp6oIBklMk0K
    getNewTransactionKYC:
      type: object
      properties:
        success:
          type: boolean
          description: Indica se a requisição foi bem sucedida.
          examples:
            - true
        userId:
          type: string
          examples:
            - 8STzaZ7Ii6cGlnLR
        url:
          type: string
          examples:
            - https://shielid.com/kyc/test123/hashDaTransacao123
    getHashs:
      type: object
      properties:
        success:
          type: boolean
          examples:
            - true
        hashList:
          type: array
          items:
            type: object
            properties:
              hash:
                type: string
                description: Hash de um procedimento do KYC.
              status:
                type: string
                description: Status da hash.
          example:
            - hash: dRkar0x5aUEvoKnZhhvxAp6oIBklMk0K
              status: created
            - hash: outroHashExemplo12345
              status: processed
        orderBy:
          type: string
          examples:
            - desc
        limit:
          type: integer
          examples:
            - 25
        page:
          type: integer
          examples:
            - 1
        lastPage:
          type: integer
          examples:
            - 5
    getHashData:
      type: object
      properties:
        success:
          type: boolean
          examples:
            - true
        data:
          type: object
          properties:
            currentStep:
              type: string
              examples:
                - document-front
            hash:
              type: string
              examples:
                - IWqoRB0gxKMmK6JoUOZZNnDOpbA9enES
            userId:
              type: string
              examples:
                - nQvYpZxTgLmRbHcFkAjD-eWqXsOtUiVnMzCrKjGhBy
            score:
              type: number
              examples:
                - 0
            status:
              type: string
              examples:
                - created
            url:
              type: string
              examples:
                - https://shielid.com/kyc/CwXwUh0QD9OpzACl/IWqoRB0gxKMmK6JoUOZZNnDOpbA9enES
            createdTimestamp:
              type: number
              examples:
                - 1752021617
            finishedTimestamp:
              type: number
              examples:
                - 1752021617
    getHashData400:
      type: object
      properties:
        success:
          type: boolean
          examples:
            - false
        message:
          type: string
          examples:
            - Parâmetro hash ausente ou inválido.
    getStats:
      type: object
      properties:
        onboardings:
          type: object
          description: Contagens agregadas de onboardings.
          properties:
            total:
              type: integer
              description: Soma de `approved` + `rejected`. Status intermediários não contam.
              examples:
                - 1099
            approved:
              type: integer
              description: Onboardings com status `approved`.
              examples:
                - 912
            rejected:
              type: integer
              description: Onboardings com status `rejected`.
              examples:
                - 187
        transactions:
          type: object
          description: Contagens agregadas de transações.
          properties:
            total:
              type: integer
              description: Soma de `approved` + `rejected`. Status intermediários não contam.
              examples:
                - 4422
            approved:
              type: integer
              description: Transações com status `approved`.
              examples:
                - 4320
            rejected:
              type: integer
              description: Transações com status `rejected`.
              examples:
                - 102
    getStats500:
      type: object
      properties:
        success:
          type: boolean
          examples:
            - false
        message:
          type: string
          examples:
            - Não foi possível carregar as estatísticas.
    getBlacklist:
      type: object
      properties:
        success:
          type: boolean
          examples:
            - true
        blacklist:
          type: array
          items:
            type: object
            properties:
              document:
                type: string
                description: CPF sem máscara (11 dígitos).
                example: "52998224725"
              until:
                type: [string, "null"]
                description: Data de expiração `"Y-m-d H:i:s"` ou `null` (bloqueio permanente/sem prazo).
                example: "2026-08-15 00:00:00"
              reason:
                type: [string, "null"]
                description: Motivo do bloqueio (texto livre) ou `null`.
                example: "fraude confirmada"
              blocked_by:
                type: [string, "null"]
                description: Quem fez o bloqueio, para auditoria (texto livre) ou `null`.
                example: "Fulano de Tal (fulano@empresa.com)"
          example:
            - document: "52998224725"
              until: "2026-08-15 00:00:00"
              reason: "fraude confirmada"
              blocked_by: "Fulano de Tal (fulano@empresa.com)"
            - document: "10000000001"
              until: null
              reason: null
              blocked_by: "API: Empresa LTDA (usr_abc123)"
        orderBy:
          type: string
          examples:
            - desc
        limit:
          type: integer
          examples:
            - 25
        page:
          type: integer
          examples:
            - 1
        lastPage:
          type: integer
          examples:
            - 1
    checkBlacklist:
      type: object
      properties:
        success:
          type: boolean
          examples:
            - true
        blocked:
          type: boolean
          description: "`true` se o CPF está bloqueado (e não expirado), `false` caso contrário."
          examples:
            - true
        document:
          type: string
          description: CPF sem máscara (11 dígitos), sempre presente.
          example: "52998224725"
        until:
          type: [string, "null"]
          description: Data de expiração `"Y-m-d H:i:s"` ou `null` (permanente, ou não bloqueado).
          example: "2026-08-15 00:00:00"
        reason:
          type: [string, "null"]
          description: Motivo do bloqueio, ou `null`.
          example: "fraude confirmada"
        blocked_by:
          type: [string, "null"]
          description: Quem bloqueou, para auditoria, ou `null`.
          example: "Fulano de Tal (fulano@empresa.com)"
    addBlacklist:
      type: object
      properties:
        success:
          type: boolean
          examples:
            - true
        message:
          type: string
          examples:
            - CPF adicionado à blacklist com sucesso.
    removeBlacklist:
      type: object
      properties:
        success:
          type: boolean
          examples:
            - true
        message:
          type: string
          examples:
            - CPF removido da blacklist com sucesso.
    blacklistError:
      type: object
      properties:
        success:
          type: boolean
          examples:
            - false
        message:
          type: string
          examples:
            - Este documento já está bloqueado.
            - O campo "cpf" é obrigatório
    setWebhook:
      type: object
      properties:
        success:
          type: boolean
          examples:
            - true
        message:
          type: string
          examples:
            - "O url do callback foi adicionado com sucesso."
    removeWebhook:
      type: object
      properties:
        success:
          type: boolean
          examples:
            - true
        message:
          type: string
          examples:
            - O url do callback foi removido com sucesso.
    addOptionalWebhook:
      type: object
      properties:
        success:
          type: boolean
          examples:
            - true
        message:
          type: string
          examples:
            - "O url opcional foi adicionado com sucesso."
    removeOptionalWebhook:
      type: object
      properties:
        success:
          type: boolean
          examples:
            - true
        message:
          type: string
          examples:
            - "O url opcional foi removido com sucesso."
    getWebhooks:
      type: object
      properties:
        success:
          type: boolean
          examples:
            - true
        data:
          type: object
          properties:
            callback_url:
              type: [string, "null"]
              examples:
                - "https://example.com/webhook"
            optional_urls:
              type: array
              items:
                type: string
              examples:
                - [
                    "https://backup1.example.com/webhook",
                    "https://backup2.example.com/webhook",
                  ]
    consultDocumentCNPJ:
      type: object
      properties:
        success:
          type: boolean
          examples:
            - true
        data (consultType 1):
          type: object
          properties:
            name:
              type: string
              examples:
                - Brasil Bitcoin Serviços Digitais Ltda
            document:
              type: string
              examples:
                - 29.519.837/0001-23
            documentType:
              type: string
              examples:
                - CNPJ
        data (consultType 2):
          type: object
          properties:
            success:
              type: boolean
              examples:
                - true
            type:
              type: string
              example: "Matriz"
            shortName:
              type: string
              example: "BRASIL BITCOIN"
            capital:
              type: number
              example: 500000
            startDate:
              type: string
              example: "24/01/2018"
            email:
              type: string
              example: "gisele@eficacy.com.br"
            responsible:
              type: string
              example: ""
            responsibleQualification:
              type: object
              properties:
                id:
                  type: integer
                  example: 49
                description:
                  type: string
                  example: "Sócio-Administrador"
            simplesNacional:
              type: object
              properties:
                included:
                  type: string
                  example: "Não"
                start:
                  type: [string, "null"]
                end:
                  type: [string, "null"]
            mainAddress:
              type: object
              properties:
                zipcode:
                  type: string
                  example: "04707-000"
                type:
                  type: string
                  example: "Avenida"
                phone:
                  type: string
                  example: "850"
                complement:
                  type: string
                  example: "Conj 172-173-174 Torre B"
                neighborhood:
                  type: string
                  example: "Jardim das Acacias"
                city:
                  type: string
                  example: "São Paulo"
                state:
                  type: string
                  example: "SP"
            ibge:
              type: object
              properties:
                country:
                  type: object
                  properties:
                    id:
                      type: string
                      example: "1058"
                    iso2:
                      type: string
                      example: "BR"
                    iso3:
                      type: string
                      example: "BRA"
                    name:
                      type: string
                      example: "Brasil"
                    comexId:
                      type: string
                      example: "105"
                state:
                  type: object
                  properties:
                    id:
                      type: integer
                      example: 26
                    name:
                      type: string
                      example: "São Paulo"
                    sigla:
                      type: string
                      example: "SP"
                    ibgeId:
                      type: integer
                      example: 35
                city:
                  type: object
                  properties:
                    id:
                      type: integer
                      example: 3832
                    name:
                      type: string
                      example: "São Paulo"
                    ibgeId:
                      type: integer
                      example: 3550308
                    siafiId:
                      type: string
                      example: "7107"
            phones:
              type: array
              items:
                type: object
                properties:
                  ddd:
                    type: string
                    example: "11"
                  phone:
                    type: string
                    example: "42246346"
            situation:
              type: object
              properties:
                id:
                  type: integer
                  example: 2
                name:
                  type: string
                  example: "Ativa"
                date:
                  type: string
                  example: "24/01/2018"
                reason:
                  type: array
                  items:
                    type: string
            companyType:
              type: object
              properties:
                code:
                  type: string
                  example: "2062"
                description:
                  type: string
                  example: "Sociedade Empresária Limitada"
            cnae:
              type: object
              properties:
                fiscal:
                  type: string
                  example: "6319400"
                division:
                  type: string
                  example: "63"
                class:
                  type: string
                  example: "63.19-4"
                description:
                  type: string
                  example: "Portais, provedores de conteúdo e outros serviços de informação na Internet"
                secondary:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                        example: "7490104"
                      division:
                        type: string
                        example: "74"
                      class:
                        type: string
                        example: "74.90-1"
                      description:
                        type: string
                        example: "Atividades de intermediação e agenciamento de serviços e negócios em geral, exceto imobiliários"
            size:
              type: object
              properties:
                id:
                  type: string
                  example: "05"
                description:
                  type: string
                  example: "Demais"
            taxRegimes:
              type: array
              items:
                type: object
                properties:
                  year:
                    type: integer
                    example: 2021
                  taxRegime:
                    type: string
                    example: "LUCRO PRESUMIDO"
                  taxationForm:
                    type: string
                    example: "LUCRO PRESUMIDO"
                  updatedAt:
                    type: string
                    example: "2023-01-26T03:00:00.000Z"
            partners:
              type: array
              items:
                type: object
                properties:
                  document:
                    type: string
                    example: "407.516.848-48"
                  name:
                    type: string
                    example: "Marco Vinicius Castellari"
                  type:
                    type: string
                    example: "Pessoa Física"
                  entryDate:
                    type: string
                    example: "2018-01-24"
                  age:
                    type: string
                    example: "31 a 40 anos"
                  updatedAt:
                    type: string
                    example: "2024-06-08T03:00:00.000Z"
                  countryId:
                    type: string
                    example: "1058"
                  partnerQualification:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 49
                      description:
                        type: string
                        example: "Sócio-Administrador"
                  country:
                    type: object
                    properties:
                      id:
                        type: string
                        example: "1058"
                      iso2:
                        type: string
                        example: "BR"
                      iso3:
                        type: string
                        example: "BRA"
                      name:
                        type: string
                        example: "Brasil"
                      comexId:
                        type: string
                        example: "105"
            document:
              type: string
              examples:
                - 29.519.837/0001-23
            documentType:
              type: string
              examples:
                - CNPJ
        data (consultType 3):
          type: object
          properties:
            name:
              type: string
              example: "Brasil Bitcoin Servicos Digitais Ltda"
            risky:
              type: object
              properties:
                riskyLevel:
                  type: integer
                  example: 2
                riskyText:
                  type: string
                  example: "Médio"
                score:
                  type: string
                  example: "251-600"
            document:
              type: string
              example: "29.519.837/0001-23"
            documentType:
              type: string
              example: "cnpj"
    consultDocumentCPF:
      type: object
      properties:
        success:
          type: boolean
          examples:
            - true
        data:
          type: object
          properties:
            cpf:
              type: string
              example: 123.456.789-09
            pepKyc:
              type: object
              properties:
                isCurrentlySanctioned:
                  type: boolean
                  example: false
                wasPreviouslySanctioned:
                  type: boolean
                  example: false
                sanctions30d:
                  type: number
                  example: 0
                sanctions90d:
                  type: number
                  example: 0
                sanctions180d:
                  type: number
                  example: 0
                sanctions365d:
                  type: number
                  example: 0
                isCurrentlyPep:
                  type: boolean
                  example: false
                pep1yCount:
                  type: number
                  example: 0
                pep3yCount:
                  type: number
                  example: 0
                pep5yCount:
                  type: number
                  example: 0
                pep5yPlusCount:
                  type: number
                  example: 0
                pepHistory:
                  type: array
                  items:
                    type: object
                    properties:
                      level:
                        type: string
                      jobTitle:
                        type: string
                      department:
                        type: string
                      motive:
                        type: string
                      source:
                        type: string
                      document:
                        type: string
                      pepDocument:
                        type: string
                      startDate:
                        type: string
                      endDate:
                        type: string
                      lastUpdateDate:
                        type: string
                  example:
                    - level: "1"
                      jobTitle: "VEREADOR"
                      department: "CAMARA MUNICIPAL DE X"
                      motive: "CITY EMPLOYEE"
                      source: "PEP_PORTAL"
                      document: "00000000000"
                      pepDocument: ""
                      startDate: "2021-01-01T00:00:00Z"
                      endDate: "2029-12-31T00:00:00Z"
                      lastUpdateDate: ""
                sanctions:
                  type: array
                  items:
                    type: object
                    properties:
                      source:
                        type: string
                      type:
                        type: string
                      standardizedType:
                        type: string
                      matchRate:
                        type: number
                      nameUniquenessScore:
                        type: number
                      startDate:
                        type: string
                      endDate:
                        type: string
                      isCurrentlyOnSource:
                        type: boolean
                      wasRecentlyOnSource:
                        type: boolean
                      lastUpdateDate:
                        type: string
                      details:
                        type: object
                        properties:
                          originalName:
                            type: string
                          sanctionName:
                            type: string
                          birthDate:
                            type: string
                          standardizedBirthDate:
                            type: string
                          sourceDobScore:
                            type: number
                          nationalities:
                            type: string
                          imageUrl:
                            type: string
                          languagesSpoken:
                            type: string
                          charges:
                            type: string
                  example:
                    - source: ""
                      type: ""
                      standardizedType: ""
                      matchRate: 0
                      nameUniquenessScore: 0
                      startDate: ""
                      endDate: ""
                      isCurrentlyOnSource: true
                      wasRecentlyOnSource: false
                      lastUpdateDate: ""
                      details:
                        originalName: ""
                        sanctionName: ""
                        birthDate: ""
                        standardizedBirthDate: ""
                        sourceDobScore: 0
                        nationalities: ""
                        imageUrl: ""
                        languagesSpoken: ""
                        charges: ""
                sanctionsNotFound:
                  type: array
                  items:
                    type: string
                  example:
                    - "CVM"
                    - "Banco Central"
                    - "OFAC"
                    - "COAF"
                    - "EU"
                    - "GOVUK"
                    - "FBI"
                    - "Interpol"
                    - "UNSC"
                    - "CEAF"
                    - "CNEP"
                    - "Conselho Nacional De Justiça"
                    - "CEIS"
                    - "CEPIM"
                    - "Inidôneos TCU"
                    - "Acordos de Leniência"
                    - "Processo administrativo disciplinar"
                    - "Impedidos de licitar e contratar banco"
                    - "Tribunal de Contas do Estado de São Paulo"
            queriedAt:
              type: string
              example: ""
            cpfStatus:
              type: object
              properties:
                cpf:
                  type: string
                  example: ""
                name:
                  type: string
                  example: ""
                firstName:
                  type: string
                  example: ""
                lastName:
                  type: string
                  example: ""
                status:
                  type: string
                  example: "REGULAR / SUSPENSA / TITULAR FALECIDO / PENDENTE DE REGULARIZAÇÃO / CANCELADA / NULA"
                countryOfOrigin:
                  type: string
                  example: ""
                age:
                  type: number
                  example: 0
                motherName:
                  type: string
                  example: ""
                gender:
                  type: string
                  example: "M = Masculino / F = Feminino / U = Indefinido"
                checkDigit:
                  type: string
                  example: ""
                birthDate:
                  type: string
                  example: ""
                registrationDate:
                  type: string
                  example: ""
                deathYear:
                  type: string
                  example: ""
            contactData:
              type: object
              properties:
                contact:
                  type: object
                  properties:
                    address:
                      type: array
                      items:
                        type: object
                        properties:
                          street:
                            type: string
                          number:
                            type: string
                          neighborhood:
                            type: string
                          complement:
                            type: string
                          zipcode:
                            type: string
                          city:
                            type: string
                          state:
                            type: string
                          fullAddress:
                            type: string
                          updatedYear:
                            type: number
                      example:
                        - street: "RUA EXEMPLO"
                          number: "1000"
                          neighborhood: "BAIRRO EXEMPLO"
                          complement: ""
                          zipcode: "12345678"
                          city: "CIDADE"
                          state: "SP"
                          fullAddress: "RUA EXEMPLO, 1000, BAIRRO EXEMPLO, CIDADE - SP, 12345678"
                          updatedYear: 2025
                    phones:
                      type: array
                      items:
                        type: object
                        properties:
                          number:
                            type: string
                      example:
                        - number: "12 123456789"
                    emails:
                      type: array
                      items:
                        type: object
                        properties:
                          email:
                            type: string
                      example:
                        - email: "EMAILEXEMPLO@EMAIL.COM"
            bettingBan:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    document:
                      type: string
                      example: "00000000000"
                    name:
                      type: string
                      example: "NOME SOBRENOME"
                    restrictions:
                      type: array
                      items:
                        type: object
                        properties:
                          linkLevel:
                            type: string
                            example: "0 para quando o próprio CPF é enquadrado, 1 para quando o CPF tem vínculo com um familiar de primeiro grau ou cônjuge, 2 para quando o CPF tem vínculo com um familiar de segundo grau"
                          restrictionType:
                            type: string
                            example: "agente-operador, agente-publico, agente-sistemas, funcionario, arbitragem, comissao-tecnica, agente-intemediario, agente-fiscalizador e atleta"
                          sport:
                            type: string
                            example: "Categoria esportiva associada ao CPF"
                          entity:
                            type: string
                            example: "Organização ou instituição relacionada ao CPF"
                          role:
                            type: string
                            example: "Posição ocupada pelo CPF"
                          relatedDocument:
                            type: string
                            example: "00000000"
                          relatedDocumentType:
                            type: string
                            example: "CPF"
                          relatedName:
                            type: string
                            example: "NOME SOBRENOME"
                          updatedAt:
                            type: string
                            example: "2024-02-09"
            socialBenefits:
              type: object
              properties:
                cpf:
                  type: string
                  example: "00000000000"
                beneficiaryName:
                  type: string
                  example: "NOME SOBRENOME"
                programs:
                  type: array
                  items:
                    type: object
                    properties:
                      programName:
                        type: string
                        example: "Novo Bolsa Familia"
                      history:
                        type: array
                        items:
                          type: object
                          properties:
                            amount:
                              type: string
                              example: "R$ XXX,XX"
                            monthYear:
                              type: string
                              example: "03-2026"
            consultCNH:
              type: [object, "null"]
              description: Dados da CNH. Presente apenas quando o módulo `consult_cnh` está habilitado e foi solicitado.
              properties:
                cnh:
                  type: object
                  properties:
                    category:
                      type: string
                      example: "AB"
                    expirationDate:
                      type: string
                      example: "2030-01-01"
                    renach:
                      type: string
                      example: "SP000000000"
                    firstCnh:
                      type: string
                      example: "2010-06-15"
                    issueDate:
                      type: string
                      example: "2025-01-10"
                    registrationNumber:
                      type: string
                      example: "00000000000"
                    observation:
                      type: string
                      example: ""
                    toxicological:
                      type: string
                      example: ""
                    situation:
                      type: string
                      example: "ATIVO"
                    dueDate:
                      type: string
                      example: "2030-01-01"
                blocks:
                  type: array
                  items:
                    type: object
                    properties:
                      description:
                        type: string
                  example: []
                exams:
                  type: array
                  items:
                    type: object
                    properties:
                      date:
                        type: string
                      location:
                        type: string
                  example: []
            financialData:
              type: [object, "null"]
              description: Dados financeiros do CPF. Presente apenas quando o módulo `dados_financeiros` está habilitado e foi solicitado.
              properties:
                totalAssets:
                  type: [number, "null"]
                  example: 250000.00
                taxReturns:
                  type: [array, "null"]
                  items:
                    type: object
                    properties:
                      bank:
                        type: string
                        example: ""
                      year:
                        type: string
                        example: "2020"
                      batch:
                        type: string
                        example: ""
                      branch:
                        type: string
                        example: "0000"
                      status:
                        type: string
                        example: "SUA DECLARACAO NAO CONSTA NA BASE DE DADOS DA RECEITA FEDERAL"
                      captureDate:
                        type: string
                        example: "01/01/2021"
                      isVipBranch:
                        type: boolean
                        example: false
                      creationDate:
                        type: string
                        example: "01/01/2021"
                      lastUpdateDate:
                        type: string
                        example: "15/04/2021"
                  example:
                    - bank: ""
                      year: "2020"
                      batch: ""
                      branch: "0000"
                      status: "SUA DECLARACAO NAO CONSTA NA BASE DE DADOS DA RECEITA FEDERAL"
                      captureDate: "01/01/2021"
                      isVipBranch: false
                      creationDate: "01/01/2021"
                      lastUpdateDate: "15/04/2021"
                incomeEstimates:
                  type: [object, "null"]
                  description: Estimativas de renda por fonte. Valor pode ser faixa salarial (ex.:"5 A 7 SM") ou "SEM INFORMACAO".
                  properties:
                    mte:
                      type: string
                      example: "5 A 7 SM"
                    ibge:
                      type: string
                      example: "5 A 7 SM"
                    bigdata:
                      type: string
                      example: "5 A 7 SM"
                    bigdataV2:
                      type: string
                      example: "5 A 7 SM"
                    companyOwnership:
                      type: string
                      example: "5 A 7 SM"
            document:
              type: string
              example: ""
            documentType:
              type: string
              example: ""
        idDocumentConsult:
          type: number
          example: 0
    checkFaceRequest:
      type: object
      required:
        - document
        - image
      properties:
        document:
          type: string
          description: Número do CPF (sem formatação) a ser consultado.
          example: "07068093868"
        image:
          type: string
          format: base64
          description: Imagem da face a ser validada, enviada em formato base64.
          example: "/9j/4AAQSkZJRgABAQAAAQABAAD/2wCEAAkGBxMSEhUTExMWFhUX..."
    checkFace:
      type: object
      properties:
        success:
          type: boolean
          examples:
            - true
        message:
          type: string
          examples:
            - Face confirmada.
        score:
          type: number
          examples:
            - 0.85
    sendPhoneToken:
      type: object
      properties:
        success:
          type: boolean
          examples:
            - true
        message:
          type: string
          examples:
            - Token enviado para +5511999999999.
        userId:
          type: string
          examples:
            - lTXniLwvQdncO8ZQ
    sendPhoneToken400:
      type: object
      properties:
        success:
          type: boolean
          examples:
            - false
        message:
          type: string
          examples:
            - Código do país não informado ou inválido.
    sendEmailToken:
      type: object
      properties:
        success:
          type: boolean
          examples:
            - true
        message:
          type: string
          examples:
            - Token enviado para exo********@gmail.com.br.
        userId:
          type: string
          examples:
            - lTXniLwvQdncO8ZQ
    sendEmailToken400:
      type: object
      properties:
        success:
          type: boolean
          examples:
            - false
        message:
          type: string
          examples:
            - E-mail não informado ou inválido.
    checkEmailToken:
      type: object
      properties:
        success:
          type: boolean
          examples:
            - true
        message:
          type: string
          examples:
            - E-mail confirmado.
    checkPhoneToken:
      type: object
      properties:
        success:
          type: boolean
          examples:
            - true
        message:
          type: string
          examples:
            - Número de telefone confirmado.
    checkToken400:
      type: object
      properties:
        success:
          type: boolean
          examples:
            - false
        message:
          type: string
          examples:
            - Token incorreto.
        ties:
          type: number
          examples:
            - 2
    unAuthorized:
      type: object
      properties:
        success:
          type: boolean
          examples:
            - false
        message:
          type: string
          examples:
            - Autenticação inválida.
    notFound:
      type: object
      properties:
        success:
          type: boolean
          examples:
            - false
        message:
          type: string
          examples:
            - 404 - Chamada não encontrada.
    consultTypeInvalid:
      type: object
      properties:
        success:
          type: boolean
          examples:
            - false
        message:
          type: string
          examples:
            - 'Parâmetro consultType inválido: módulo desconhecido "xpto".'
            - "Parâmetro consultType inválido: consulta de veículo deve ser feita via /consultVehicle."
        consultTypeInvalid:
          type: boolean
          examples:
            - true
    Error:
      type: object
      description: RFC 7807 (https://datatracker.ietf.org/doc/html/rfc7807)
      properties:
        type:
          type: string
          examples:
            - https://example.com/errors/generic-error
        title:
          type: string
          examples:
            - Something went wrong here.
        status:
          type: integer
          format: int64
          examples:
            - 403
        detail:
          type: string
          examples:
            - Unfortunately, we can’t provide further information.
