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

# Enviar verificação do titular

> ⚠️ **Esta chamada é real**: ela envia a verificação de identidade do workspace e **envia códigos de verificação reais** para `contactEmail` (sempre) e para `contactWhatsapp` (sempre que a Pilot Status está enviando códigos pelo WhatsApp — `contact.requiredChannels` diz quais). Use apenas dados reais do titular da conta.

Inicia a verificação e entrega o documento, numa só chamada. Conferimos o número (dígitos verificadores; um CNPJ também precisa ser encontrado e estar **ativo** na Receita), congelamos os canais de contato exigidos, enviamos os códigos, guardamos o arquivo de forma privada e lemos o número impresso nele. Responde **201** com o estado em `PENDING_CONTACT`; depois, confirme cada código com `POST /v1/phone-lines/verification/contact/{channel}/confirm`. A requisição volta depois que o documento foi lido — em geral em segundos, no máximo cerca de um minuto.

O corpo é **JSON** (`Content-Type: application/json`), não multipart: o arquivo vai em `document` como data URI em base64. Qualquer outro campo é recusado com 400 `UNKNOWN_FIELDS`. O arquivo é conferido **antes de qualquer coisa começar**: tipo ou tamanho errado não envia código nem cria nada.

**Enviar de novo.** Enquanto a verificação ainda está em `PENDING_CONTACT`, um novo envio a **substitui** (para corrigir um erro de digitação): os códigos já enviados deixam de valer e novos são enviados. Depois que ela avançou, um envio responde 409 `VERIFICATION_WRONG_STATE` (`IN_REVIEW` ou `APPROVED` — você já pode comprar — ou `NEEDS_DOCUMENT` — envie o documento em `POST /v1/phone-lines/verification/document`) ou 403 `VERIFICATION_REJECTED`.

**Idempotência** (`Idempotency-Key` é OBRIGATÓRIO), durante 24 horas: mesma chave + mesma requisição, a primeira já terminou → **200** (não 201) com o estado atual do workspace e `Idempotent-Replayed: true`, nada é enviado de novo; mesma chave enquanto a primeira ainda está rodando → 409 `IDEMPOTENCY_KEY_IN_USE`; mesma chave, requisição diferente (qualquer campo, inclusive o arquivo) → 409 `IDEMPOTENCY_KEY_REUSED`; uma requisição recusada como um todo libera a chave. **Limite:** 10 envios por hora por workspace, somando este endpoint e `…/verification/document` → 429 `RATE_LIMITED`. Exige uma chave **com escopo de tenant**, como todo endpoint `/v1/phone-lines` (uma chave com escopo de número recebe `403 NUMBER_SCOPE_NOT_ALLOWED`). Permissão `phone_lines:purchase`, a mesma da compra: com um token OAuth/MCP, só o **OWNER** do workspace pode chamar (`403 PERMISSION_DENIED` caso contrário). É a mesma verificação do painel (**Linhas** → **Comprar linhas**): o que você fizer por um caminho aparece no outro. A resposta é o objeto de estado da verificação, enviado com `Cache-Control: no-store`; o número do documento e os contatos voltam mascarados.

> [!WARNING]
>
> **Isto envia a verificação de identidade real do seu workspace.** Envie só os dados e o documento verdadeiros do titular.


## OpenAPI

````yaml openapi.pt.json POST /v1/phone-lines/verification
openapi: 3.1.0
info:
  title: API Pilot Status
  version: 1.0.0
  license:
    name: Pilot Status Terms of Service
    url: https://pilotstatus.com.br/terms
  description: >-
    API REST pública do Pilot Status. Autentique com o header `x-api-key:
    ps_...` (ou `x-api-key-id`). Base URL: https://pilotstatus.com.br
servers:
  - url: https://pilotstatus.com.br
security:
  - apiKey: []
  - apiKeyId: []
paths:
  /v1/phone-lines/verification:
    post:
      tags:
        - Phone Lines
      summary: Enviar a verificação do titular
      description: >-
        ⚠️ **Esta chamada é real**: ela envia a verificação de identidade do
        workspace e **envia códigos de verificação reais** para `contactEmail`
        (sempre) e para `contactWhatsapp` (sempre que a Pilot Status está
        enviando códigos pelo WhatsApp — `contact.requiredChannels` diz quais).
        Use apenas dados reais do titular da conta.


        Inicia a verificação e entrega o documento, numa só chamada. Conferimos
        o número (dígitos verificadores; um CNPJ também precisa ser encontrado e
        estar **ativo** na Receita), congelamos os canais de contato exigidos,
        enviamos os códigos, guardamos o arquivo de forma privada e lemos o
        número impresso nele. Responde **201** com o estado em
        `PENDING_CONTACT`; depois, confirme cada código com `POST
        /v1/phone-lines/verification/contact/{channel}/confirm`. A requisição
        volta depois que o documento foi lido — em geral em segundos, no máximo
        cerca de um minuto.


        O corpo é **JSON** (`Content-Type: application/json`), não multipart: o
        arquivo vai em `document` como data URI em base64. Qualquer outro campo
        é recusado com 400 `UNKNOWN_FIELDS`. O arquivo é conferido **antes de
        qualquer coisa começar**: tipo ou tamanho errado não envia código nem
        cria nada.


        **Enviar de novo.** Enquanto a verificação ainda está em
        `PENDING_CONTACT`, um novo envio a **substitui** (para corrigir um erro
        de digitação): os códigos já enviados deixam de valer e novos são
        enviados. Depois que ela avançou, um envio responde 409
        `VERIFICATION_WRONG_STATE` (`IN_REVIEW` ou `APPROVED` — você já pode
        comprar — ou `NEEDS_DOCUMENT` — envie o documento em `POST
        /v1/phone-lines/verification/document`) ou 403 `VERIFICATION_REJECTED`.


        **Idempotência** (`Idempotency-Key` é OBRIGATÓRIO), durante 24 horas:
        mesma chave + mesma requisição, a primeira já terminou → **200** (não
        201) com o estado atual do workspace e `Idempotent-Replayed: true`, nada
        é enviado de novo; mesma chave enquanto a primeira ainda está rodando →
        409 `IDEMPOTENCY_KEY_IN_USE`; mesma chave, requisição diferente
        (qualquer campo, inclusive o arquivo) → 409 `IDEMPOTENCY_KEY_REUSED`;
        uma requisição recusada como um todo libera a chave. **Limite:** 10
        envios por hora por workspace, somando este endpoint e
        `…/verification/document` → 429 `RATE_LIMITED`. Exige uma chave **com
        escopo de tenant**, como todo endpoint `/v1/phone-lines` (uma chave com
        escopo de número recebe `403 NUMBER_SCOPE_NOT_ALLOWED`). Permissão
        `phone_lines:purchase`, a mesma da compra: com um token OAuth/MCP, só o
        **OWNER** do workspace pode chamar (`403 PERMISSION_DENIED` caso
        contrário). É a mesma verificação do painel (**Linhas** → **Comprar
        linhas**): o que você fizer por um caminho aparece no outro. A resposta
        é o objeto de estado da verificação, enviado com `Cache-Control:
        no-store`; o número do documento e os contatos voltam mascarados.
      operationId: post_phone_lines_verification
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          description: >-
            **Obrigatório.** Qualquer string de até **255 caracteres**, sem
            caracteres de controle — um UUID por envio. Ausente ou em branco →
            400 `IDEMPOTENCY_KEY_REQUIRED`; mais longa, ou com um caractere de
            controle → 400 `IDEMPOTENCY_KEY_INVALID`. Lembrada por 24 horas por
            workspace: a mesma chave enviada por dois workspaces nunca colide.
          schema:
            type: string
            maxLength: 255
          example: 5f0c6d2e-9a41-4d1b-8f7e-2b3c4d5e6f70
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - documentType
                - documentNumber
                - contactEmail
                - contactWhatsapp
                - document
              additionalProperties: false
              properties:
                documentType:
                  type: string
                  enum:
                    - CNPJ
                    - CPF
                  description: '`"CNPJ"` ou `"CPF"`.'
                  example: CNPJ
                documentNumber:
                  type: string
                  description: >-
                    O CNPJ ou CPF, com ou sem pontuação (`11.222.333/0001-81` ou
                    `11222333000181`). CNPJs alfanuméricos são aceitos.
                  example: 11.222.333/0001-81
                contactEmail:
                  type: string
                  format: email
                  maxLength: 254
                  description: >-
                    O e-mail de contato do titular, com até 254 caracteres. Ele
                    sempre recebe um código.
                  example: ana@example.com
                contactWhatsapp:
                  type: string
                  description: >-
                    O número de WhatsApp do titular no formato internacional —
                    código do país, DDD e número, por exemplo `+55 11
                    90000-0000`; a pontuação é ignorada. Ele recebe um código
                    quando `WHATSAPP` é exigido.
                  example: +55 11 90000-0000
                document:
                  type: string
                  description: >-
                    O arquivo do documento como **data URI em base64**:
                    `data:<tipo>;base64,<conteúdo>`, codificado sem quebras de
                    linha. Tipos: `application/pdf`, `image/jpeg`, `image/png`,
                    `image/webp`; no máximo **10 MB** de arquivo (cerca de 14 MB
                    depois de codificado). Para CNPJ: cartão CNPJ, contrato
                    social ou comprovante de inscrição. Para CPF: RG, CNH ou
                    comprovante de inscrição no CPF, com o número legível.
                  example: data:application/pdf;base64,JVBERi0xLjQKJcOkw7zDtsOfCg==
            example:
              documentType: CNPJ
              documentNumber: 11.222.333/0001-81
              contactEmail: ana@example.com
              contactWhatsapp: +55 11 90000-0000
              document: data:application/pdf;base64,JVBERi0xLjQKJcOkw7zDtsOfCg==
      responses:
        '200':
          description: >-
            Replay idempotente: a mesma `Idempotency-Key` com a mesma requisição
            já terminou. O estado **atual** do workspace; nada foi iniciado nem
            enviado de novo.
          headers:
            Cache-Control:
              description: Sempre `no-store`.
              schema:
                type: string
                enum:
                  - no-store
            Idempotent-Replayed:
              description: '`true` num replay.'
              schema:
                type: string
                enum:
                  - 'true'
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - NONE
                      - PENDING_CONTACT
                      - IN_REVIEW
                      - APPROVED
                      - NEEDS_DOCUMENT
                      - REJECTED
                    description: >-
                      `NONE` (nunca iniciada), `PENDING_CONTACT` (esperando os
                      códigos de contato e, se `document.status` indicar, um
                      documento melhor), `IN_REVIEW` (concluída, esperando uma
                      pessoa conferir — compra permitida), `APPROVED`
                      (verificada — compra permitida), `NEEDS_DOCUMENT` (o
                      revisor pediu outro documento) ou `REJECTED` (definitivo —
                      fale com o suporte). O webhook
                      `phone_line.verification_updated` usa os mesmos valores
                      para os quatro últimos.
                  canPurchase:
                    type: boolean
                    description: >-
                      Se `POST /v1/phone-lines` é permitido agora: `true` para
                      `APPROVED` e `IN_REVIEW`.
                  verification:
                    type: object
                    nullable: true
                    description: '`null` para `NONE`.'
                    properties:
                      id:
                        type: string
                        description: >-
                          Identifica a verificação — é o `verificationId` do
                          evento de webhook, e o que o suporte vai pedir.
                      documentType:
                        type: string
                        enum:
                          - CNPJ
                          - CPF
                      documentNumber:
                        type: string
                        description: >-
                          **Mascarado**: `**.***.333/0001-**` (CNPJ) ou
                          `***.456.789-**` (CPF). O número completo nunca é
                          retornado.
                      legalName:
                        type: string
                        nullable: true
                        description: >-
                          A razão social na Receita (CNPJ). `null` para CPF, e
                          quando a Receita não pôde ser consultada.
                      contact:
                        type: object
                        properties:
                          email:
                            type: string
                            description: >-
                              O e-mail de contato, mascarado
                              (`a***@example.com`).
                          whatsapp:
                            type: string
                            nullable: true
                            description: >-
                              O WhatsApp de contato, mascarado
                              (`+5511****0000`).
                          requiredChannels:
                            type: array
                            items:
                              type: string
                              enum:
                                - WHATSAPP
                                - EMAIL
                            description: >-
                              `WHATSAPP` e/ou `EMAIL`: os códigos de que esta
                              verificação precisa. Fica congelada quando a
                              verificação começa. Pela API, `EMAIL` é sempre
                              exigido.
                          confirmedChannels:
                            type: array
                            items:
                              type: string
                              enum:
                                - WHATSAPP
                                - EMAIL
                            description: Os canais exigidos já confirmados.
                          pendingChannels:
                            type: array
                            items:
                              type: string
                              enum:
                                - WHATSAPP
                                - EMAIL
                            description: Os canais exigidos que ainda esperam o código.
                      document:
                        type: object
                        properties:
                          status:
                            type: string
                            enum:
                              - RECEIVED
                              - UNREADABLE
                              - UNCLEAR
                              - REQUESTED
                              - MISSING
                            description: >-
                              `RECEIVED` (o documento foi recebido),
                              `UNREADABLE` (não encontramos nenhum número no
                              arquivo), `UNCLEAR` (encontramos números, mas
                              nenhum em que pudéssemos confiar), `REQUESTED` (o
                              revisor pediu outro documento) ou `MISSING` (ainda
                              sem documento). Nos quatro últimos, envie um novo
                              documento com `POST
                              /v1/phone-lines/verification/document`.
                      reviewReason:
                        type: string
                        nullable: true
                        enum:
                          - REGISTRY_UNAVAILABLE
                          - DOCUMENT_CHECK
                          - null
                        description: >-
                          Só em `IN_REVIEW`: `REGISTRY_UNAVAILABLE` (não foi
                          possível consultar a Receita) ou `DOCUMENT_CHECK` (o
                          documento precisa ser conferido). `null` nos outros
                          casos.
                      reviewNote:
                        type: string
                        nullable: true
                        description: >-
                          A mensagem do revisor, só em `REJECTED` e
                          `NEEDS_DOCUMENT`. `null` nos outros casos — e pode ser
                          `null` nesses também.
                      createdAt:
                        type: string
                        format: date-time
                        description: ISO 8601 — quando esta verificação foi enviada.
                      updatedAt:
                        type: string
                        format: date-time
                        description: ISO 8601 — a última mudança dela.
              example:
                status: PENDING_CONTACT
                canPurchase: false
                verification:
                  id: cmg5k0v3r0000vf8example7k
                  documentType: CNPJ
                  documentNumber: '**.***.333/0001-**'
                  legalName: ACME LTDA
                  contact:
                    email: a***@example.com
                    whatsapp: +5511****0000
                    requiredChannels:
                      - WHATSAPP
                      - EMAIL
                    confirmedChannels:
                      - WHATSAPP
                    pendingChannels:
                      - EMAIL
                  document:
                    status: RECEIVED
                  reviewReason: null
                  reviewNote: null
                  createdAt: '2026-10-01T13:55:02.000Z'
                  updatedAt: '2026-10-01T13:56:40.000Z'
        '201':
          description: >-
            Verificação iniciada: os códigos estão a caminho
            (`PENDING_CONTACT`).
          headers:
            Cache-Control:
              description: Sempre `no-store`.
              schema:
                type: string
                enum:
                  - no-store
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - NONE
                      - PENDING_CONTACT
                      - IN_REVIEW
                      - APPROVED
                      - NEEDS_DOCUMENT
                      - REJECTED
                    description: >-
                      `NONE` (nunca iniciada), `PENDING_CONTACT` (esperando os
                      códigos de contato e, se `document.status` indicar, um
                      documento melhor), `IN_REVIEW` (concluída, esperando uma
                      pessoa conferir — compra permitida), `APPROVED`
                      (verificada — compra permitida), `NEEDS_DOCUMENT` (o
                      revisor pediu outro documento) ou `REJECTED` (definitivo —
                      fale com o suporte). O webhook
                      `phone_line.verification_updated` usa os mesmos valores
                      para os quatro últimos.
                  canPurchase:
                    type: boolean
                    description: >-
                      Se `POST /v1/phone-lines` é permitido agora: `true` para
                      `APPROVED` e `IN_REVIEW`.
                  verification:
                    type: object
                    nullable: true
                    description: '`null` para `NONE`.'
                    properties:
                      id:
                        type: string
                        description: >-
                          Identifica a verificação — é o `verificationId` do
                          evento de webhook, e o que o suporte vai pedir.
                      documentType:
                        type: string
                        enum:
                          - CNPJ
                          - CPF
                      documentNumber:
                        type: string
                        description: >-
                          **Mascarado**: `**.***.333/0001-**` (CNPJ) ou
                          `***.456.789-**` (CPF). O número completo nunca é
                          retornado.
                      legalName:
                        type: string
                        nullable: true
                        description: >-
                          A razão social na Receita (CNPJ). `null` para CPF, e
                          quando a Receita não pôde ser consultada.
                      contact:
                        type: object
                        properties:
                          email:
                            type: string
                            description: >-
                              O e-mail de contato, mascarado
                              (`a***@example.com`).
                          whatsapp:
                            type: string
                            nullable: true
                            description: >-
                              O WhatsApp de contato, mascarado
                              (`+5511****0000`).
                          requiredChannels:
                            type: array
                            items:
                              type: string
                              enum:
                                - WHATSAPP
                                - EMAIL
                            description: >-
                              `WHATSAPP` e/ou `EMAIL`: os códigos de que esta
                              verificação precisa. Fica congelada quando a
                              verificação começa. Pela API, `EMAIL` é sempre
                              exigido.
                          confirmedChannels:
                            type: array
                            items:
                              type: string
                              enum:
                                - WHATSAPP
                                - EMAIL
                            description: Os canais exigidos já confirmados.
                          pendingChannels:
                            type: array
                            items:
                              type: string
                              enum:
                                - WHATSAPP
                                - EMAIL
                            description: Os canais exigidos que ainda esperam o código.
                      document:
                        type: object
                        properties:
                          status:
                            type: string
                            enum:
                              - RECEIVED
                              - UNREADABLE
                              - UNCLEAR
                              - REQUESTED
                              - MISSING
                            description: >-
                              `RECEIVED` (o documento foi recebido),
                              `UNREADABLE` (não encontramos nenhum número no
                              arquivo), `UNCLEAR` (encontramos números, mas
                              nenhum em que pudéssemos confiar), `REQUESTED` (o
                              revisor pediu outro documento) ou `MISSING` (ainda
                              sem documento). Nos quatro últimos, envie um novo
                              documento com `POST
                              /v1/phone-lines/verification/document`.
                      reviewReason:
                        type: string
                        nullable: true
                        enum:
                          - REGISTRY_UNAVAILABLE
                          - DOCUMENT_CHECK
                          - null
                        description: >-
                          Só em `IN_REVIEW`: `REGISTRY_UNAVAILABLE` (não foi
                          possível consultar a Receita) ou `DOCUMENT_CHECK` (o
                          documento precisa ser conferido). `null` nos outros
                          casos.
                      reviewNote:
                        type: string
                        nullable: true
                        description: >-
                          A mensagem do revisor, só em `REJECTED` e
                          `NEEDS_DOCUMENT`. `null` nos outros casos — e pode ser
                          `null` nesses também.
                      createdAt:
                        type: string
                        format: date-time
                        description: ISO 8601 — quando esta verificação foi enviada.
                      updatedAt:
                        type: string
                        format: date-time
                        description: ISO 8601 — a última mudança dela.
              example:
                status: PENDING_CONTACT
                canPurchase: false
                verification:
                  id: cmg5k0v3r0000vf8example7k
                  documentType: CNPJ
                  documentNumber: '**.***.333/0001-**'
                  legalName: ACME LTDA
                  contact:
                    email: a***@example.com
                    whatsapp: +5511****0000
                    requiredChannels:
                      - WHATSAPP
                      - EMAIL
                    confirmedChannels: []
                    pendingChannels:
                      - WHATSAPP
                      - EMAIL
                  document:
                    status: RECEIVED
                  reviewReason: null
                  reviewNote: null
                  createdAt: '2026-10-01T13:55:02.000Z'
                  updatedAt: '2026-10-01T13:55:09.000Z'
        '400':
          description: >-
            Validação: `Idempotency-Key` ausente/inválida, corpo que não é
            objeto JSON (`INVALID_BODY`), campo desconhecido (`UNKNOWN_FIELDS`,
            `details.unknownFields`), `INVALID_DOCUMENT_TYPE`,
            `INVALID_DOCUMENT_NUMBER` (ausente, ou dígitos verificadores
            errados), `INVALID_CONTACT_EMAIL`, `INVALID_CONTACT_WHATSAPP`,
            `INVALID_DOCUMENT` (não é data URI em base64),
            `DOCUMENT_TYPE_UNSUPPORTED` (não é PDF/JPEG/PNG/WEBP),
            `REGISTRY_NOT_FOUND` (CNPJ não encontrado na Receita) ou
            `REGISTRY_INACTIVE` (CNPJ não ativo: não é possível vender linhas
            para ele).
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Frase em inglês e frase em português separadas por ` | `.
                  code:
                    type: string
                    description: Código de erro estável — decida por ele, nunca pelo texto.
                  details:
                    type: object
                    description: >-
                      Só em erros de validação: `unknownFields` (array) ou
                      `maxLength` (número).
                    additionalProperties: true
              examples:
                idempotencyKeyRequired:
                  summary: Sem Idempotency-Key
                  value:
                    error: >-
                      Send an Idempotency-Key header (for example a UUID) so a
                      retry cannot start the verification twice. | Envie o
                      header Idempotency-Key (por exemplo um UUID) para que uma
                      nova tentativa não inicie a verificação duas vezes.
                    code: IDEMPOTENCY_KEY_REQUIRED
                idempotencyKeyInvalid:
                  summary: Chave longa demais ou com caractere de controle
                  value:
                    error: >-
                      Idempotency-Key must have at most 255 characters and no
                      control characters. | Idempotency-Key deve ter no máximo
                      255 caracteres e nenhum caractere de controle.
                    code: IDEMPOTENCY_KEY_INVALID
                    details:
                      maxLength: 255
                unknownFields:
                  summary: Campo que este endpoint não aceita
                  value:
                    error: >-
                      Unknown field(s): whatsapp. Accepted: documentType,
                      documentNumber, contactEmail, contactWhatsapp, document. |
                      Campo(s) desconhecido(s): whatsapp. Aceitos: documentType,
                      documentNumber, contactEmail, contactWhatsapp, document.
                    code: UNKNOWN_FIELDS
                    details:
                      unknownFields:
                        - whatsapp
                invalidDocumentType:
                  summary: documentType não é CNPJ/CPF
                  value:
                    error: >-
                      documentType must be "CPF" or "CNPJ". | documentType deve
                      ser "CPF" ou "CNPJ".
                    code: INVALID_DOCUMENT_TYPE
                invalidDocumentNumber:
                  summary: Dígitos verificadores errados
                  value:
                    error: >-
                      The document number is not valid. | O número do documento
                      não é válido.
                    code: INVALID_DOCUMENT_NUMBER
                invalidContactEmail:
                  summary: E-mail inválido
                  value:
                    error: >-
                      contactEmail must be a valid e-mail address: the
                      verification code is sent to it. | contactEmail deve ser
                      um e-mail válido: o código de verificação é enviado para
                      ele.
                    code: INVALID_CONTACT_EMAIL
                invalidContactWhatsapp:
                  summary: Número de WhatsApp inválido
                  value:
                    error: >-
                      contactWhatsapp must be a WhatsApp number with country and
                      area code, e.g. +55 11 99999-8888. | contactWhatsapp deve
                      ser um número de WhatsApp com país e DDD, ex.: +55 11
                      99999-8888.
                    code: INVALID_CONTACT_WHATSAPP
                invalidDocument:
                  summary: document não é data URI
                  value:
                    error: >-
                      document must be the file as a base64 data URI, e.g.
                      data:application/pdf;base64,JVBERi0x… | document deve ser
                      o arquivo como data URI em base64, ex.:
                      data:application/pdf;base64,JVBERi0x…
                    code: INVALID_DOCUMENT
                documentTypeUnsupported:
                  summary: Tipo de arquivo não aceito
                  value:
                    error: >-
                      Send a PDF, JPG, PNG or WEBP file. | Envie um arquivo PDF,
                      JPG, PNG ou WEBP.
                    code: DOCUMENT_TYPE_UNSUPPORTED
                registryNotFound:
                  summary: CNPJ não encontrado na Receita
                  value:
                    error: >-
                      This CNPJ was not found in the public registry. | Este
                      CNPJ não foi encontrado na Receita.
                    code: REGISTRY_NOT_FOUND
                registryInactive:
                  summary: CNPJ não ativo
                  value:
                    error: >-
                      This CNPJ is not active in the public registry, so lines
                      cannot be sold to it. | Este CNPJ não está ativo na
                      Receita, então não é possível vender linhas para ele.
                    code: REGISTRY_INACTIVE
        '401':
          description: >-
            Header `x-api-key` / `x-api-key-id` (ou token OAuth Bearer) ausente
            ou inválido. Este corpo não traz `code`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
              example:
                error: Invalid API key
        '403':
          description: >-
            `VERIFICATION_REJECTED`: a verificação foi recusada — definitivo,
            fale com o suporte. Também: chave com escopo de número ou grant
            OAuth por número (`NUMBER_SCOPE_NOT_ALLOWED` — use a chave com
            escopo de tenant); token OAuth/MCP de um usuário que não é o OWNER
            do workspace (`PERMISSION_DENIED`) ou que não é mais membro ativo
            (`WORKSPACE_MEMBERSHIP_REQUIRED`); workspace arquivado
            (`WORKSPACE_ARCHIVED`). Os erros de escopo e de papel trazem um
            `error` só em inglês.. `TENANT_REQUIRED`: credencial sem workspace
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
              examples:
                rejected:
                  summary: Verificação recusada
                  value:
                    error: >-
                      The account holder verification was rejected. | A
                      verificação do titular foi recusada.
                    code: VERIFICATION_REJECTED
                numberScope:
                  summary: Chave com escopo de número
                  value:
                    error: This endpoint requires a tenant-scoped API key
                    code: NUMBER_SCOPE_NOT_ALLOWED
                permission:
                  summary: Usuário OAuth/MCP não é o OWNER
                  value:
                    error: >-
                      Your workspace role does not allow this action
                      (phone_lines:purchase).
                    code: PERMISSION_DENIED
                membership:
                  summary: Usuário OAuth/MCP não é mais membro ativo
                  value:
                    error: >-
                      The user behind this token is not an active member of this
                      workspace.
                    code: WORKSPACE_MEMBERSHIP_REQUIRED
                archived:
                  summary: Workspace arquivado
                  value:
                    error: >-
                      This workspace has been archived and its API is closed. |
                      Este workspace foi arquivado e sua API está encerrada.
                    code: WORKSPACE_ARCHIVED
                tenantRequired:
                  summary: Credencial sem workspace
                  value:
                    error: This credential is not bound to a workspace.
                    code: TENANT_REQUIRED
        '409':
          description: >-
            `VERIFICATION_WRONG_STATE`: a verificação atual está em `IN_REVIEW`,
            `APPROVED` (você já pode comprar) ou `NEEDS_DOCUMENT` (envie o
            documento em `…/verification/document`). `IDEMPOTENCY_KEY_IN_USE`:
            uma requisição com esta chave ainda está rodando — aguarde e envie
            de novo para receber o resultado. `IDEMPOTENCY_KEY_REUSED`: esta
            chave foi usada em outra requisição — use uma chave nova.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
              examples:
                wrongState:
                  summary: Verificação já passou da etapa de dados
                  value:
                    error: >-
                      The verification is not in a state that allows this. | A
                      verificação não está em um estado que permita isso.
                    code: VERIFICATION_WRONG_STATE
                inUse:
                  summary: Chave ainda em uso
                  value:
                    error: >-
                      A request with this Idempotency-Key is still running. Wait
                      for it, then send it again to get its result. | Um pedido
                      com esta Idempotency-Key ainda está em andamento. Aguarde
                      e envie de novo para receber o resultado.
                    code: IDEMPOTENCY_KEY_IN_USE
                reused:
                  summary: Chave reutilizada em outra requisição
                  value:
                    error: >-
                      This Idempotency-Key was already used for a different
                      request. Use a new key for new data. | Esta
                      Idempotency-Key já foi usada em outro pedido. Use uma nova
                      chave para dados novos.
                    code: IDEMPOTENCY_KEY_REUSED
        '413':
          description: O arquivo tem mais de 10 MB.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
              example:
                error: The file is larger than 10 MB. | O arquivo tem mais de 10 MB.
                code: DOCUMENT_TOO_LARGE
        '429':
          description: >-
            `RATE_LIMITED`: mais de 10 envios na hora para este workspace
            (somando este endpoint e `…/verification/document`). Aguarde
            `Retry-After` segundos.
          headers:
            Retry-After:
              description: Segundos a esperar antes do próximo envio.
              schema:
                type: integer
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
                  retryAfterSeconds:
                    type: integer
                    description: Segundos até um novo envio ser aceito.
              example:
                error: >-
                  Too many verification submissions: at most 10 per hour per
                  workspace. Try again later. | Envios de verificação demais: no
                  máximo 10 por hora por workspace. Tente de novo mais tarde.
                code: RATE_LIMITED
                retryAfterSeconds: 1820
        '500':
          description: Falha inesperada. Tente de novo.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
              example:
                error: Unexpected error. | Erro inesperado.
                code: INTERNAL_ERROR
        '503':
          description: >-
            `SUPPLIER_UNAVAILABLE`: não foi possível colocar um código de
            contato na fila de envio. A chave é liberada — tente de novo em
            alguns minutos.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
              example:
                error: >-
                  Phone lines are temporarily unavailable. Try again in a few
                  minutes. | As linhas estão temporariamente indisponíveis.
                  Tente de novo em alguns minutos.
                code: SUPPLIER_UNAVAILABLE
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: Sua chave de API ps_
    apiKeyId:
      type: apiKey
      in: header
      name: x-api-key-id
      description: Id da chave de API (alternativa ao x-api-key)

````

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