> ## 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.

# Criar voucher e-CPF

> Emite um voucher de certificado digital para pessoa física.



## OpenAPI

````yaml POST /api/v1/partners/{partnerId}/vouchers/cpf
openapi: 3.1.0
info:
  title: Certificados ZapSign Partner API
  version: 4.2.0
  description: >-
    API REST para parceiros (revendedores) emitirem vouchers de certificado
    digital e-CPF e e-CNPJ. Cada criação desconta 1 certificado do saldo da
    carteira do parceiro. Autenticação por Bearer token com prefixo `czk_live_`
    gerado em
    [https://certificados.zapsign.com.br/reseller/api-keys](https://certificados.zapsign.com.br/reseller/api-keys).
  contact:
    name: Suporte Certificados ZapSign
    url: https://wa.me/5511952135263
servers:
  - url: https://certificados.zapsign.com.br
    description: Produção
security:
  - bearerAuth: []
tags:
  - name: Vouchers
    description: Criação e consulta de vouchers de certificado digital.
  - name: Carteira
    description: Saldo disponível do parceiro.
paths:
  /api/v1/partners/{partnerId}/vouchers/cpf:
    post:
      tags:
        - Vouchers
      summary: Cria voucher e-CPF.
      description: Emite um voucher de certificado digital para pessoa física.
      operationId: createVoucherCpf
      parameters:
        - $ref: '#/components/parameters/PartnerIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VoucherRequestECPF'
            examples:
              ecpf_a1:
                summary: e-CPF A1 (arquivo .pfx)
                value:
                  certificate_type: ecpf_a1
                  name: Maria Aparecida da Silva
                  cpf: '39053344705'
                  email: maria.silva@example.com.br
                  phone: '+5511987654321'
                  birthdate: '1985-03-12'
                  reference_id: PEDIDO_12345
              ecpf_a3_nuvem:
                summary: e-CPF A3 em nuvem (assina pelo celular)
                value:
                  certificate_type: ecpf_a3_nuvem
                  name: Carlos Eduardo Pereira
                  cpf: '52998224725'
                  email: carlos.pereira@example.com.br
                  phone: '+5521988887777'
                  birthdate: '1990-09-25'
                  reference_id: PEDIDO_67890
      responses:
        '201':
          $ref: '#/components/responses/VoucherCreatedCpf'
        '400':
          description: >-
            Body inválido: cobre 6 códigos `error` distintos. Veja o `error` no
            body para o motivo exato.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoucherErrorEnvelope'
              examples:
                validation_error:
                  $ref: '#/components/examples/ValidationErrorExampleSlim'
                invalid_certificate_type:
                  $ref: '#/components/examples/InvalidCertificateTypeExampleSlim'
                wrong_endpoint:
                  $ref: '#/components/examples/WrongEndpointCpfExampleSlim'
                unknown_field:
                  $ref: '#/components/examples/UnknownFieldExampleSlim'
                underage_holder:
                  $ref: '#/components/examples/UnderageHolderExampleSlim'
                procuration_not_supported:
                  $ref: '#/components/examples/ProcurationNotSupportedExampleSlim'
        '401':
          $ref: '#/components/responses/UnauthorizedSlim'
        '402':
          $ref: '#/components/responses/InsufficientCreditsSlim'
        '403':
          $ref: '#/components/responses/ForbiddenSlim'
        '409':
          $ref: '#/components/responses/DuplicateReferenceIdSlim'
        '422':
          $ref: '#/components/responses/InvalidReferenceIdSlim'
        '429':
          $ref: '#/components/responses/RateLimitExceededSlim'
        '500':
          $ref: '#/components/responses/InternalErrorSlim'
      x-codeSamples:
        - lang: curl
          label: cURL
          source: >-
            curl -X POST
            'https://certificados.zapsign.com.br/api/v1/partners/PRT_ABC123/vouchers/cpf'
            \
              -H 'Authorization: Bearer czk_live_SUA_CHAVE' \
              -H 'Content-Type: application/json' \
              -d '{
                "certificate_type": "ecpf_a1",
                "name": "Maria Aparecida da Silva",
                "cpf": "39053344705",
                "email": "maria.silva@example.com.br",
                "phone": "+5511987654321",
                "birthdate": "1985-03-12",
                "reference_id": "PEDIDO_12345"
              }'
        - lang: javascript
          label: Node.js (fetch)
          source: |-
            const res = await fetch(
              'https://certificados.zapsign.com.br/api/v1/partners/PRT_ABC123/vouchers/cpf',
              {
                method: 'POST',
                headers: {
                  Authorization: 'Bearer czk_live_SUA_CHAVE',
                  'Content-Type': 'application/json',
                },
                body: JSON.stringify({
                  certificate_type: 'ecpf_a1',
                  name: 'Maria Aparecida da Silva',
                  cpf: '39053344705',
                  email: 'maria.silva@example.com.br',
                  phone: '+5511987654321',
                  birthdate: '1985-03-12',
                  reference_id: 'PEDIDO_12345',
                }),
              },
            );
            const voucher = await res.json();
        - lang: python
          label: Python (requests)
          source: |-
            import requests

            res = requests.post(
                'https://certificados.zapsign.com.br/api/v1/partners/PRT_ABC123/vouchers/cpf',
                headers={
                    'Authorization': 'Bearer czk_live_SUA_CHAVE',
                    'Content-Type': 'application/json',
                },
                json={
                    'certificate_type': 'ecpf_a1',
                    'name': 'Maria Aparecida da Silva',
                    'cpf': '39053344705',
                    'email': 'maria.silva@example.com.br',
                    'phone': '+5511987654321',
                    'birthdate': '1985-03-12',
                    'reference_id': 'PEDIDO_12345',
                },
            )
            voucher = res.json()
components:
  parameters:
    PartnerIdParam:
      name: partnerId
      in: path
      required: true
      description: Identificador público do parceiro (Partner ID), exibido no portal.
      schema:
        type: string
        minLength: 1
        maxLength: 64
  schemas:
    VoucherRequestECPF:
      type: object
      additionalProperties: false
      required:
        - certificate_type
        - name
        - cpf
        - email
        - phone
        - birthdate
      properties:
        certificate_type:
          type: string
          enum:
            - ecpf_a1
            - ecpf_a3_nuvem
          description: >-
            Tipo de e-CPF: `ecpf_a1` (arquivo `.pfx` no computador) ou
            `ecpf_a3_nuvem` (qualquer dispositivo; cada uso exige autorização no
            app de celular do titular).
          example: ecpf_a1
        name:
          type: string
          description: >-
            Nome completo do titular pessoa física, exatamente como no documento
            oficial.
          minLength: 1
          maxLength: 200
          example: Maria Aparecida da Silva
        cpf:
          type: string
          description: >-
            CPF do titular pessoa física. Apenas dígitos (`39053344705`); o
            servidor valida o DV.
          minLength: 11
          maxLength: 11
          example: '39053344705'
          examples:
            - '39053344705'
        email:
          type: string
          format: email
          description: Email do titular para envio do voucher e instruções de emissão.
          maxLength: 254
          example: maria.silva@example.com.br
        phone:
          type: string
          description: >-
            Celular do titular brasileiro em formato **E.164**: prefixo `+55` +
            DDD + número (ex.: `+5511987654321`). Não se aceita máscara, espaços
            nem separadores.
          minLength: 13
          maxLength: 14
          example: '+5511987654321'
          examples:
            - '+5511987654321'
        birthdate:
          type: string
          format: date
          description: >-
            Data de nascimento do titular no formato AAAA-MM-DD. Exige idade
            mínima de 18 anos.
          pattern: ^\d{4}-\d{2}-\d{2}$
          example: '1985-03-12'
        reference_id:
          $ref: '#/components/schemas/ReferenceId'
    VoucherErrorEnvelope:
      type: object
      description: >-
        Envelope de erro dos endpoints de voucher: `error`, `message` e
        `details` (opcional).
      required:
        - error
        - message
      properties:
        error:
          type: string
          description: >-
            Código curto e estável do catálogo fechado. Use para fazer branching
            no seu cliente.
          example: validation_error
        message:
          type: string
          description: Mensagem em pt-BR, segura para mostrar a operadores internos.
        details:
          description: Estrutura adicional dependente do código. Veja a tabela de erros.
    ReferenceId:
      type: string
      description: >-
        Chave de idempotência do parceiro: o mesmo `reference_id` retorna o
        voucher original com HTTP 200 e não desconta saldo novamente; omita ou
        envie `null` para criar outro voucher.
      pattern: ^[A-Za-z0-9_-]{1,64}$
      minLength: 1
      maxLength: 64
      example: PEDIDO_12345
    VoucherCreateResponse:
      type: object
      required:
        - voucher_id
        - whatsapp_number
        - whatsapp_link
      additionalProperties: false
      properties:
        voucher_id:
          type: string
          description: >-
            Identificador único do voucher recém-criado (ou do voucher já
            existente, no caso de replay idempotente). Use no link de resgate,
            em buscas e em `GET /vouchers/{voucher_id}`.
          example: ZS_ECPF_A1_01KRME1Q2EBE9XNHV3G8JP6RF3
        whatsapp_number:
          type:
            - string
            - 'null'
          description: >-
            Número de WhatsApp do suporte para o titular acionar a emissão.
            Encaminhe ao cliente final junto com o `voucher_id`. Use UX-only.
          example: '5511936203902'
        whatsapp_link:
          type:
            - string
            - 'null'
          format: uri
          description: >-
            Link `https://wa.me/...` pré-preenchido com o `voucher_id` na
            mensagem. Compartilhe com o cliente final como atalho pra abrir a
            conversa de emissão.
          example: >-
            https://wa.me/5511936203902?text=Ol%C3%A1%21%20Quero%20emitir%20meu%20certificado%20digital.%0A%0AMeu%20voucher%20%C3%A9%3A%20%2AZS_ECPF_A1_01KRME1Q2EBE9XNHV3G8JP6RF3%2A
  responses:
    VoucherCreatedCpf:
      description: Voucher e-CPF criado.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/VoucherCreateResponse'
          examples:
            ecpf:
              $ref: '#/components/examples/SuccessECPFCreate'
    UnauthorizedSlim:
      description: Não autenticado.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/VoucherErrorEnvelope'
          examples:
            missing_or_invalid_authorization:
              $ref: '#/components/examples/MissingOrInvalidAuthorizationExampleSlim'
            invalid_api_key:
              $ref: '#/components/examples/InvalidApiKeyExampleSlim'
            api_key_revoked:
              $ref: '#/components/examples/ApiKeyRevokedExampleSlim'
    InsufficientCreditsSlim:
      description: >-
        Saldo da carteira do parceiro insuficiente pra descontar 1 certificado.
        Recarregue antes de reenviar.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/VoucherErrorEnvelope'
          examples:
            insufficient_credits:
              $ref: '#/components/examples/InsufficientCreditsExampleSlim'
    ForbiddenSlim:
      description: Acesso negado.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/VoucherErrorEnvelope'
          examples:
            partner_not_approved:
              $ref: '#/components/examples/PartnerNotApprovedExampleSlim'
            tenant_mismatch:
              $ref: '#/components/examples/TenantMismatchExampleSlim'
    DuplicateReferenceIdSlim:
      description: >-
        Dois requests concorrentes com o mesmo `reference_id` colidiram. Reenvie
        o request; o segundo cai em replay idempotente 200.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/VoucherErrorEnvelope'
          examples:
            duplicate_reference_id:
              $ref: '#/components/examples/DuplicateReferenceIdExampleSlim'
    InvalidReferenceIdSlim:
      description: '`reference_id` no body do POST fora do padrão `^[A-Za-z0-9_-]{1,64}$`.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/VoucherErrorEnvelope'
          examples:
            invalid_reference_id:
              $ref: '#/components/examples/InvalidReferenceIdExampleSlim'
    RateLimitExceededSlim:
      description: >-
        Limite de requisições excedido para a chave. Aguarde a janela e respeite
        os headers `RateLimit-*`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/VoucherErrorEnvelope'
          examples:
            rate_limit_exceeded:
              $ref: '#/components/examples/RateLimitExceededExampleSlim'
      headers:
        RateLimit-Limit:
          description: Limite máximo na janela atual.
          schema:
            type: integer
        RateLimit-Remaining:
          description: Quantas requisições ainda cabem na janela.
          schema:
            type: integer
            example: 0
        RateLimit-Reset:
          description: Segundos até a janela reabrir.
          schema:
            type: integer
            example: 42
    InternalErrorSlim:
      description: >-
        Falha inesperada do servidor. Reenvie com backoff exponencial; o
        `reference_id` garante idempotência.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/VoucherErrorEnvelope'
          examples:
            internal_error:
              $ref: '#/components/examples/InternalErrorExampleSlim'
  examples:
    ValidationErrorExampleSlim:
      summary: Falha de Zod no body (campo aceito mas em formato errado)
      x-resolution: Veja `details.fieldErrors`, corrija o campo apontado e reenvie.
      value:
        error: validation_error
        message: Erro de validação no corpo da requisição.
        details:
          fieldErrors:
            cpf:
              - CPF deve ter 11 dígitos
    InvalidCertificateTypeExampleSlim:
      summary: Slug enviado não é um dos 4 aceitos
      x-resolution: Use exatamente um dos valores listados em `details.valid_values`.
      value:
        error: invalid_certificate_type
        message: certificate_type inválido ou ausente.
        details:
          valid_values:
            - ecpf_a1
            - ecpf_a3_nuvem
            - ecnpj_a1
            - ecnpj_a3_nuvem
    WrongEndpointCpfExampleSlim:
      summary: Slug `ecnpj_*` enviado para POST /vouchers/cpf
      x-resolution: Use POST /vouchers/cnpj para slugs `ecnpj_*`.
      value:
        error: wrong_endpoint
        message: certificate_type ecnpj_* deve ser enviado para POST /vouchers/cnpj.
        details:
          hint: Use POST /api/v1/partners/{partnerId}/vouchers/cnpj
    UnknownFieldExampleSlim:
      summary: Body contém campo não previsto pelo schema do endpoint
      x-resolution: >-
        Remova o campo extra apontado em `details.field` ou troque por um
        aceito.
      value:
        error: unknown_field
        message: 'Campo desconhecido: variant_id'
        details:
          field: variant_id
          valid_values:
            - ecpf_a1
            - ecpf_a3_nuvem
            - ecnpj_a1
            - ecnpj_a3_nuvem
    UnderageHolderExampleSlim:
      summary: Titular do e-CPF com menos de 18 anos na data do request
      x-resolution: Confirme a data de nascimento. ICP-Brasil exige idade mínima de 18 anos.
      value:
        error: underage_holder
        message: Titular ou responsável deve ter no mínimo 18 anos.
        details:
          field: birthdate
    ProcurationNotSupportedExampleSlim:
      summary: Body contém campos `legal_representative_*` (procuração)
      x-resolution: >-
        Em v1 o signatário deve ser o representante legal. Remova os campos
        `legal_representative_*`.
      value:
        error: procuration_not_supported
        message: v1 não suporta procuração; signatário deve ser o representante legal.
        details:
          hint: v1 não suporta procuração; signatário deve ser o representante legal
          field: legal_representative_cpf
    SuccessECPFCreate:
      summary: Voucher e-CPF criado
      value:
        voucher_id: ZS_ECPF_A1_01KRME1Q2EBE9XNHV3G8JP6RF3
        whatsapp_number: '5511936203902'
        whatsapp_link: >-
          https://wa.me/5511936203902?text=Ol%C3%A1%21%20Quero%20emitir%20meu%20certificado%20digital.%0A%0AMeu%20voucher%20%C3%A9%3A%20%2AZS_ECPF_A1_01KRME1Q2EBE9XNHV3G8JP6RF3%2A
    MissingOrInvalidAuthorizationExampleSlim:
      summary: Header `Authorization` ausente ou fora do formato `Bearer <token>`
      x-resolution: Envie o header `Authorization` no formato `Bearer czk_live_...`.
      value:
        error: missing_or_invalid_authorization
        message: Header Authorization ausente ou malformado.
    InvalidApiKeyExampleSlim:
      summary: Token Bearer não bate com nenhuma chave válida
      x-resolution: >-
        Gere uma nova chave em
        https://certificados.zapsign.com.br/reseller/api-keys e atualize seus
        secrets.
      value:
        error: invalid_api_key
        message: API key inválida.
    ApiKeyRevokedExampleSlim:
      summary: Chave existe mas foi revogada no portal
      x-resolution: >-
        Gere uma nova chave em
        https://certificados.zapsign.com.br/reseller/api-keys e atualize seus
        secrets.
      value:
        error: api_key_revoked
        message: API key revogada.
    InsufficientCreditsExampleSlim:
      summary: Saldo da carteira do parceiro insuficiente pra 1 certificado
      x-resolution: Compre certificados em `/reseller/buy-credits` antes de reenviar.
      value:
        error: insufficient_credits
        message: Saldo da carteira insuficiente para emitir 1 certificado.
    PartnerNotApprovedExampleSlim:
      summary: Parceiro existe mas o status não está em `approved`
      x-resolution: Aguarde a aprovação do cadastro. Você recebe email quando for liberado.
      value:
        error: partner_not_approved
        message: Parceiro não aprovado.
    TenantMismatchExampleSlim:
      summary: O `partnerId` da URL não bate com o dono da chave
      x-resolution: Use a chave do parceiro dono daquele `partnerId`.
      value:
        error: tenant_mismatch
        message: partnerId do path não corresponde ao dono da API key.
    DuplicateReferenceIdExampleSlim:
      summary: '`reference_id` duplicado por request concorrente'
      x-resolution: Reuse o `reference_id` (vai disparar replay 200) ou gere um novo alias.
      value:
        error: duplicate_reference_id
        message: reference_id já utilizado para este parceiro.
    InvalidReferenceIdExampleSlim:
      summary: '`reference_id` enviado mas não bate com `^[A-Za-z0-9_-]{1,64}$`'
      x-resolution: Use apenas `A-Z a-z 0-9 _ -` no `reference_id`, máximo 64 caracteres.
      value:
        error: invalid_reference_id
        message: reference_id inválido ou ausente.
        details:
          reference_id:
            - reference_id deve matchear ^[A-Za-z0-9_-]{1,64}$
    RateLimitExceededExampleSlim:
      summary: Limite de requisições excedido para a chave.
      x-resolution: >-
        Reduza a frequência das chamadas e use backoff exponencial antes de
        tentar novamente.
      value:
        error: rate_limit_exceeded
        message: Limite de requisições excedido.
    InternalErrorExampleSlim:
      summary: Falha não esperada do servidor
      x-resolution: >-
        Reenvie com backoff exponencial. O mesmo `reference_id` garante
        idempotência.
      value:
        error: internal_error
        message: Erro interno do servidor.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: czk_live_*
      description: >-
        Token Bearer com prefixo `czk_live_`. Gere a chave no portal em
        [https://certificados.zapsign.com.br/reseller/api-keys](https://certificados.zapsign.com.br/reseller/api-keys).

````