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

# Verifica titular

> Confere se o titular pode emitir o certificado digital por videoconferência.

> [!NOTE]
>
> A verificação é opcional e não desconta saldo. Criar o protocolo já inclui essa verificação.
>
> Veja também:
>
> * [Erros](https://docs.certificados.zapsign.com.br/erros.md)
> * [Limites de uso](https://docs.certificados.zapsign.com.br/api-reference/limites.md)


## OpenAPI

````yaml /api-reference/openapi.json post /api/v2/partners/customer-verifications
openapi: 3.1.0
info:
  title: Certificados ZapSign Partner API v2
  version: 2.0.0
  description: >-
    API REST para parceiros criarem e acompanharem protocolos de certificado
    digital e-CPF e e-CNPJ (A1 e A3 em nuvem), emitidos por videoconferência.
  contact:
    name: Suporte Certificados ZapSign
    url: https://wa.me/5511952135263
servers:
  - url: https://certificados.zapsign.com.br
    description: Produção
security:
  - bearerAuth: []
tags:
  - name: Protocolos
    description: Criação, consulta, listagem e cancelamento de protocolos.
  - name: Verificação
    description: Verificação opcional do titular antes de criar o protocolo.
  - name: Agendamento
    description: Horários livres e agendamento da videoconferência.
  - name: Saldo e catálogo
    description: Saldo atual e certificados disponíveis para o parceiro.
paths:
  /api/v2/partners/customer-verifications:
    post:
      tags:
        - Verificação
      summary: Verifica titular
      description: >-
        Confere se o titular pode emitir o certificado digital por
        videoconferência.
      operationId: verifyCustomer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerificationRequest'
            examples:
              Pessoa física:
                summary: Pessoa física
                value:
                  type: pf
                  cpf: '52998224725'
                  birth_date: '1990-01-02'
              Pessoa jurídica:
                summary: Pessoa jurídica
                value:
                  type: pj
                  cnpj: '11222333000181'
                  representative:
                    cpf: '52998224725'
                    birth_date: '1990-01-02'
      responses:
        '200':
          description: Verificação concluída, inclusive quando o titular não é aprovado.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationResponse'
              examples:
                Pode emitir por videoconferência (e-CPF):
                  summary: Pode emitir por videoconferência (e-CPF)
                  value:
                    verification_result: approved
                    customer:
                      type: pf
                      name: Ana Souza
                      cpf: '52998224725'
                      birth_date: '1990-01-02'
                      email: ana@exemplo.com.br
                      phone: '+5511987654321'
                      address:
                        cep: '01310100'
                        street: Rua das Flores
                        number: '123'
                        complement: null
                        neighborhood: Centro
                        city: São Paulo
                        state: SP
                Pode emitir por videoconferência (e-CNPJ):
                  summary: Pode emitir por videoconferência (e-CNPJ)
                  value:
                    verification_result: approved
                    customer:
                      type: pj
                      company_name: Padaria do Bairro LTDA
                      cnpj: '11222333000181'
                      representative:
                        name: Ana Souza
                        cpf: '52998224725'
                        birth_date: '1990-01-02'
                        email: ana@exemplo.com.br
                        phone: '+5511987654321'
                        address:
                          cep: '01310100'
                          street: Rua das Flores
                          number: '123'
                          complement: null
                          neighborhood: Centro
                          city: São Paulo
                          state: SP
                'Não pode emitir por videoconferência: CPF e data de nascimento não conferem (e-CPF)':
                  summary: >-
                    Não pode emitir por videoconferência: CPF e data de
                    nascimento não conferem (e-CPF)
                  value:
                    verification_result: identity_not_confirmed
                    message: >-
                      CPF e data de nascimento não conferem. Confira os dados
                      informados.
                'Não pode emitir por videoconferência: não é representante legal da empresa (e-CNPJ)':
                  summary: >-
                    Não pode emitir por videoconferência: não é representante
                    legal da empresa (e-CNPJ)
                  value:
                    verification_result: legal_representation_not_confirmed
                    message: >-
                      A pessoa informada não consta como representante legal da
                      empresa. Confira o CNPJ e os dados do representante legal.
                'Não pode emitir por videoconferência: sem biometria cadastrada nem CNH (e-CPF)':
                  summary: >-
                    Não pode emitir por videoconferência: sem biometria
                    cadastrada nem CNH (e-CPF)
                  value:
                    verification_result: video_requirements_not_met
                    message: >-
                      O titular precisa ter biometria cadastrada ou CNH para
                      emitir por videoconferência.
                    customer:
                      type: pf
                      name: Ana Souza
                      cpf: '52998224725'
                      birth_date: '1990-01-02'
                      email: ana@exemplo.com.br
                      phone: '+5511987654321'
                      address:
                        cep: '01310100'
                        street: Rua das Flores
                        number: '123'
                        complement: null
                        neighborhood: Centro
                        city: São Paulo
                        state: SP
      x-codeSamples:
        - lang: curl
          label: cURL
          source: >-
            curl -X POST
            'https://certificados.zapsign.com.br/api/v2/partners/customer-verifications'
            \
              -H 'Authorization: Bearer czk_live_SUA_CHAVE' \
              -H 'Content-Type: application/json' \
              -d '{
                "type": "pf",
                "cpf": "52998224725",
                "birth_date": "1990-01-02"
              }'
        - lang: javascript
          label: Node.js (fetch)
          source: >-
            const res = await fetch(
              'https://certificados.zapsign.com.br/api/v2/partners/customer-verifications',
              {
                method: 'POST',
                headers: {
                  Authorization: 'Bearer czk_live_SUA_CHAVE',
                  'Content-Type': 'application/json',
                },
                body: JSON.stringify({
                  type: 'pf',
                  cpf: '52998224725',
                  birth_date: '1990-01-02',
                }),
              },
            );

            const verificacao = await res.json();

            // Só `verificacao.verification_result` igual a `approved` permite
            criar o protocolo.
        - lang: python
          label: Python (requests)
          source: >-
            import requests


            res = requests.post(
                'https://certificados.zapsign.com.br/api/v2/partners/customer-verifications',
                headers={
                    'Authorization': 'Bearer czk_live_SUA_CHAVE',
                },
                json={
                    'type': 'pf',
                    'cpf': '52998224725',
                    'birth_date': '1990-01-02',
                },
            )

            verificacao = res.json()

            # Só verificacao['verification_result'] igual a approved permite
            criar o protocolo.
components:
  schemas:
    VerificationRequest:
      description: 'Titular a verificar: `pf` para e-CPF, `pj` para e-CNPJ.'
      oneOf:
        - $ref: '#/components/schemas/VerificationRequestPf'
        - $ref: '#/components/schemas/VerificationRequestPj'
      discriminator:
        propertyName: type
        mapping:
          pf: '#/components/schemas/VerificationRequestPf'
          pj: '#/components/schemas/VerificationRequestPj'
      type: object
    VerificationResponse:
      type: object
      required:
        - verification_result
      properties:
        verification_result:
          $ref: '#/components/schemas/VerificationResult'
        message:
          type: string
          description: >-
            Motivo da negativa, em português, para mostrar ao titular. Só vem
            quando o resultado não é `approved`.
          example: CPF e data de nascimento não conferem. Confira os dados informados.
        customer:
          $ref: '#/components/schemas/Customer'
          description: >-
            Dados do titular encontrados na verificação. Só vem com `approved` e
            `video_requirements_not_met`.
    VerificationRequestPf:
      type: object
      additionalProperties: false
      required:
        - type
        - cpf
        - birth_date
      description: 'Titular pessoa física: CPF e data de nascimento.'
      properties:
        type:
          type: string
          const: pf
          description: Use `pf` para e-CPF e `pj` para e-CNPJ.
        cpf:
          type: string
          description: CPF do titular, só números.
          example: '52998224725'
        birth_date:
          type: string
          description: Data de nascimento. Formato `AAAA-MM-DD`. Não pode ser futura.
          format: date
          example: '1990-01-02'
      title: Pessoa física
    VerificationRequestPj:
      type: object
      additionalProperties: false
      required:
        - type
        - cnpj
        - representative
      description: >-
        Titular pessoa jurídica: CNPJ e CPF e data de nascimento do
        representante legal.
      properties:
        type:
          type: string
          const: pj
          description: Use `pf` para e-CPF e `pj` para e-CNPJ.
        cnpj:
          type: string
          description: >-
            CNPJ da empresa, 14 caracteres sem pontuação. Aceita números e
            letras.
          example: '11222333000181'
        representative:
          type: object
          additionalProperties: false
          required:
            - cpf
            - birth_date
          description: Representante legal da empresa, quem faz a videoconferência.
          properties:
            cpf:
              type: string
              description: CPF do representante legal, só números.
              example: '52998224725'
            birth_date:
              type: string
              description: Data de nascimento. Formato `AAAA-MM-DD`. Não pode ser futura.
              format: date
              example: '1990-01-02'
      title: Pessoa jurídica
    VerificationResult:
      type: string
      description: >-
        Resultado da verificação do titular. Só `approved` permite criar o
        protocolo.


        | Valor | Significado |

        | --- | --- |

        | `approved` | Os dados conferem e o titular pode emitir o certificado
        por videoconferência. |

        | `identity_not_confirmed` | O CPF e a data de nascimento não conferem.
        No e-CNPJ, são os do representante legal. |

        | `legal_representation_not_confirmed` | A pessoa informada não consta
        como representante legal da empresa. |

        | `video_requirements_not_met` | Os dados conferem, mas falta biometria
        cadastrada ou CNH para a videoconferência. No e-CNPJ, vale para o
        representante legal. |
      enum:
        - approved
        - identity_not_confirmed
        - legal_representation_not_confirmed
        - video_requirements_not_met
    Customer:
      description: >-
        Titular do certificado. A API preenche o nome (`name` ou
        `company_name`).
      oneOf:
        - $ref: '#/components/schemas/CustomerPf'
        - $ref: '#/components/schemas/CustomerPj'
      discriminator:
        propertyName: type
        mapping:
          pf: '#/components/schemas/CustomerPf'
          pj: '#/components/schemas/CustomerPj'
      type: object
    CustomerPf:
      type: object
      description: Titular pessoa física.
      required:
        - type
        - cpf
        - birth_date
        - name
        - email
        - phone
        - address
      properties:
        type:
          type: string
          const: pf
          description: Tipo do titular, `pf` para e-CPF.
        name:
          type:
            - string
            - 'null'
          description: Nome completo do titular.
          example: Ana Souza
        cpf:
          type: string
          description: CPF do titular, só números.
          example: '52998224725'
        birth_date:
          type:
            - string
            - 'null'
          description: Data de nascimento. Formato `AAAA-MM-DD`.
          example: '1990-01-02'
        email:
          type:
            - string
            - 'null'
          description: E-mail do titular.
          example: ana@exemplo.com.br
        phone:
          type:
            - string
            - 'null'
          description: Celular com DDD e código do país, como `+5511987654321`.
          example: '+5511987654321'
        address:
          $ref: '#/components/schemas/Address'
      title: Pessoa física
    CustomerPj:
      type: object
      description: >-
        Titular pessoa jurídica. Os dados de quem faz a videoconferência ficam
        em `representative`.
      required:
        - type
        - cnpj
        - company_name
        - representative
      properties:
        type:
          type: string
          const: pj
          description: Tipo do titular, `pj` para e-CNPJ.
        company_name:
          type:
            - string
            - 'null'
          description: Razão social da empresa.
          example: Padaria do Bairro LTDA
        cnpj:
          type: string
          description: CNPJ da empresa, 14 caracteres sem pontuação.
          example: '11222333000181'
        representative:
          type: object
          description: >-
            Representante legal da empresa, quem faz a videoconferência do
            e-CNPJ.
          required:
            - cpf
            - birth_date
            - name
            - email
            - phone
            - address
          properties:
            name:
              type:
                - string
                - 'null'
              description: Nome completo do representante legal.
              example: Ana Souza
            cpf:
              type:
                - string
                - 'null'
              description: CPF do representante legal, só números.
              example: '52998224725'
            birth_date:
              type:
                - string
                - 'null'
              description: Data de nascimento. Formato `AAAA-MM-DD`.
              example: '1990-01-02'
            email:
              type:
                - string
                - 'null'
              description: E-mail do representante legal.
              example: ana@exemplo.com.br
            phone:
              type:
                - string
                - 'null'
              description: Celular com DDD e código do país, como `+5511987654321`.
              example: '+5511987654321'
            address:
              $ref: '#/components/schemas/Address'
      title: Pessoa jurídica
    Address:
      type: object
      description: Endereço do titular. As 7 chaves sempre vêm; sem dados, todas `null`.
      required:
        - cep
        - street
        - number
        - complement
        - neighborhood
        - city
        - state
      properties:
        cep:
          type:
            - string
            - 'null'
          description: CEP, 8 dígitos, só números.
          example: '01310100'
        street:
          type:
            - string
            - 'null'
          description: Nome da rua ou avenida.
          example: Rua das Flores
        number:
          type:
            - string
            - 'null'
          description: Número do endereço.
          example: '123'
        complement:
          type:
            - string
            - 'null'
          description: Complemento do endereço.
        neighborhood:
          type:
            - string
            - 'null'
          description: Bairro.
          example: Centro
        city:
          type:
            - string
            - 'null'
          description: Cidade.
          example: São Paulo
        state:
          type:
            - string
            - 'null'
          description: Sigla da UF, como `SP`.
          example: SP
  headers:
    XRequestId:
      description: Identificador da chamada. Informe-o ao suporte se precisar de ajuda.
      schema:
        type: string
        example: 01K7Q4A1B2C3D4E5F6G7H8J9KM
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: czk_live_*
      description: >-
        API key criada no [portal do
        parceiro](https://certificados.zapsign.com.br/reseller/api-keys).

````

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