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

# Cancela Voucher

> Cancela um voucher do parceiro. Em caso de sucesso, devolve 1 certificado ao saldo da carteira.



## OpenAPI

````yaml POST /api/v1/partners/{partnerId}/vouchers/{voucher_id}/cancel
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/{voucher_id}/cancel:
    post:
      tags:
        - Vouchers
      summary: Cancela voucher.
      description: >-
        Cancela um voucher do parceiro. Em caso de sucesso, devolve 1
        certificado ao saldo da carteira.
      operationId: cancelVoucher
      parameters:
        - $ref: '#/components/parameters/PartnerIdParam'
        - $ref: '#/components/parameters/VoucherIdParam'
      responses:
        '200':
          $ref: '#/components/responses/VoucherCancelled'
        '400':
          $ref: '#/components/responses/InvalidVoucherId'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/VoucherNotFound'
        '409':
          $ref: '#/components/responses/VoucherNotCancellable'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalError'
      x-codeSamples:
        - lang: curl
          label: cURL
          source: >-
            curl -X POST
            'https://certificados.zapsign.com.br/api/v1/partners/PRT_ABC123/vouchers/ZS_ECPF_A1_01HXYZABCDEFGHJKMNPQRSTV/cancel'
            \
              -H 'Authorization: Bearer czk_live_SUA_CHAVE'
        - lang: javascript
          label: Node.js (fetch)
          source: |-
            const res = await fetch(
              'https://certificados.zapsign.com.br/api/v1/partners/PRT_ABC123/vouchers/ZS_ECPF_A1_01HXYZABCDEFGHJKMNPQRSTV/cancel',
              {
                method: 'POST',
                headers: { Authorization: 'Bearer czk_live_SUA_CHAVE' },
              },
            );
            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/ZS_ECPF_A1_01HXYZABCDEFGHJKMNPQRSTV/cancel',
                headers={'Authorization': 'Bearer czk_live_SUA_CHAVE'},
            )
            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
    VoucherIdParam:
      name: voucher_id
      in: path
      required: true
      description: >-
        Identificador do voucher retornado em POST /vouchers/cpf ou
        /vouchers/cnpj.
      schema:
        type: string
        pattern: ^[A-Z0-9_-]{8,80}$
        example: ZS_ECPF_A3_01HXYZABCDEFGHJKMNPQRSTV
  responses:
    VoucherCancelled:
      description: >-
        Voucher cancelado. 1 certificado volta ao saldo da carteira. O detalhe
        completo está em `GET /vouchers/{voucher_id}`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/VoucherCancelResponse'
          examples:
            cancelled:
              $ref: '#/components/examples/SuccessCancelled'
    InvalidVoucherId:
      description: '`voucher_id` na URL fora do padrão `^[A-Z0-9_-]{8,80}$`.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/VoucherErrorEnvelope'
          examples:
            invalid_voucher_id:
              $ref: '#/components/examples/InvalidVoucherIdExample'
    Unauthorized:
      description: Não autenticado.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/VoucherErrorEnvelope'
          examples:
            missing_or_invalid_authorization:
              $ref: '#/components/examples/MissingOrInvalidAuthorizationExample'
            invalid_api_key:
              $ref: '#/components/examples/InvalidApiKeyExample'
            api_key_revoked:
              $ref: '#/components/examples/ApiKeyRevokedExample'
    Forbidden:
      description: Acesso negado.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/VoucherErrorEnvelope'
          examples:
            partner_not_approved:
              $ref: '#/components/examples/PartnerNotApprovedExample'
            tenant_mismatch:
              $ref: '#/components/examples/TenantMismatchExample'
    VoucherNotFound:
      description: Não existe voucher para este parceiro com o identificador informado.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/VoucherErrorEnvelope'
          examples:
            voucher_not_found:
              $ref: '#/components/examples/VoucherNotFoundExample'
    VoucherNotCancellable:
      description: >-
        O voucher existe mas está num estado que não permite cancelamento (já
        cancelado, expirado, ou outro estado terminal). Verifique o `status`
        antes de tentar cancelar.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/VoucherErrorEnvelope'
          examples:
            voucher_not_cancellable:
              $ref: '#/components/examples/VoucherNotCancellableExample'
    RateLimitExceeded:
      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/RateLimitExceededExample'
      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
    InternalError:
      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/InternalErrorExample'
  schemas:
    VoucherCancelResponse:
      type: object
      additionalProperties: false
      description: Shape retornado por `POST /vouchers/{voucher_id}/cancel` (200).
      required:
        - voucher_id
        - certificate_type
        - status
        - reference_id
      properties:
        voucher_id:
          type: string
          description: Identificador único do voucher cancelado.
          example: ZS_ECPF_A1_01HXYZABCDEFGHJKMNPQRSTV
        certificate_type:
          oneOf:
            - $ref: '#/components/schemas/CertificateType'
            - type: 'null'
          description: Tipo do certificado. `null` apenas em vouchers legados.
        status:
          $ref: '#/components/schemas/VoucherStatus'
        reference_id:
          type:
            - string
            - 'null'
          description: >-
            Alias enviado pelo parceiro na criação. Sempre presente: `null`
            quando o voucher foi criado sem alias.
          example: PEDIDO_12345
    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.
    CertificateType:
      type: string
      description: >-
        Slug do certificado digital a emitir. Combina o titular (`ecpf_*` pessoa
        física, `ecnpj_*` pessoa jurídica) com a mídia do certificado (`*_a1`
        arquivo `.pfx` no computador, `*_a3_nuvem` usa em qualquer dispositivo,
        autorizado por app de celular).
      enum:
        - ecpf_a1
        - ecpf_a3_nuvem
        - ecnpj_a1
        - ecnpj_a3_nuvem
      x-enumDescriptions:
        ecpf_a1: Pessoa física, arquivo .pfx no computador.
        ecpf_a3_nuvem: >-
          Pessoa física, qualquer dispositivo; cada uso autorizado no app de
          celular do titular.
        ecnpj_a1: Pessoa jurídica, arquivo .pfx no computador.
        ecnpj_a3_nuvem: >-
          Pessoa jurídica, qualquer dispositivo; cada uso autorizado no app de
          celular do responsável legal.
      example: ecpf_a1
    VoucherStatus:
      type: string
      description: Estado atual do voucher no ciclo de vida.
      enum:
        - issued
        - redeemed
        - expired
        - declined
      x-enumDescriptions:
        issued: Voucher pronto pra ser usado pra emitir um certificado digital.
        redeemed: >-
          Titular já usou o voucher e recebeu o protocolo pra fazer a prova de
          vida e emitir o certificado.
        expired: Voucher venceu sem ser resgatado.
        declined: >-
          A emissão foi recusada, ou o próprio revendedor cancelou o voucher via
          `POST /vouchers/{voucher_id}/cancel`. Veja `decline_reason` pra o
          motivo (no self-cancel vale `reseller_self_cancel`).
  examples:
    SuccessCancelled:
      summary: Voucher após cancelamento via POST /vouchers/{voucher_id}/cancel
      value:
        voucher_id: ZS_ECPF_A1_01HXYZABCDEFGHJKMNPQRSTV
        certificate_type: ecpf_a1
        status: declined
        reference_id: PEDIDO_12345
    InvalidVoucherIdExample:
      summary: '`voucher_id` na URL fora do padrão `^[A-Z0-9_-]{8,80}$`'
      x-resolution: Use o `voucher_id` retornado na criação (formato `ZS_...`).
      value:
        error: invalid_voucher_id
        message: voucher_id em formato inválido.
    MissingOrInvalidAuthorizationExample:
      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.
    InvalidApiKeyExample:
      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.
    ApiKeyRevokedExample:
      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.
    PartnerNotApprovedExample:
      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.
    TenantMismatchExample:
      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.
    VoucherNotFoundExample:
      summary: '`voucher_id` desconhecido para este parceiro'
      x-resolution: Confira o `voucher_id`.
      value:
        error: voucher_not_found
        message: Voucher não encontrado.
    VoucherNotCancellableExample:
      summary: Voucher num estado que não permite cancelamento
      x-resolution: >-
        Cancelamento só vale para vouchers em estados elegíveis. Verifique o
        `status` atual do voucher antes de tentar cancelar.
      value:
        error: voucher_not_cancellable
        message: Voucher não pode ser cancelado no estado atual.
    RateLimitExceededExample:
      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.
    InternalErrorExample:
      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).

````