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

> Cancela um protocolo e devolve o certificado ao saldo.

> [!NOTE]
>
> Só protocolos em `protocol_generated` ou `appointment_scheduled` podem ser cancelados. Defina um timeout de pelo menos 35 segundos no cliente HTTP: a chamada espera até 30 segundos pelo resultado.

> [!NOTE]
>
> Veja também:
>
> * [Erros](https://docs.certificados.zapsign.com.br/erros.md)
> * [Idempotência](https://docs.certificados.zapsign.com.br/idempotencia.md)
> * [Ciclo de vida do protocolo](https://docs.certificados.zapsign.com.br/ciclo-de-vida-do-protocolo.md)


## OpenAPI

````yaml /api-reference/openapi.json post /api/v2/partners/protocols/{protocol_id}/cancel
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/protocols/{protocol_id}/cancel:
    post:
      tags:
        - Protocolos
      summary: Cancela protocolo
      description: Cancela um protocolo e devolve o certificado ao saldo.
      operationId: cancelProtocol
      parameters:
        - $ref: '#/components/parameters/ProtocolId'
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '200':
          description: >-
            Protocolo com o resultado do cancelamento. Se o `status` não for
            `cancelled`, `error.code` traz `invalid_state` ou
            `provider_unavailable`; sem `error`, consulte o protocolo de novo.
          headers:
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Protocol'
              examples:
                Cancelamento confirmado:
                  summary: Cancelamento confirmado
                  value:
                    status: cancelled
                    protocol_id: CPR_01K7Q3ZB8M4N6P2R5T9V1W3X5Y
                    external_id: PEDIDO_12345
                    protocol_number: '7800'
                    appointment:
                      date: '2026-10-22'
                      time: '11:30'
                      timezone: America/Sao_Paulo
                    certificate:
                      name: e-CPF A1 (1 ano)
                      type: e_cpf
                      model: a1
                      validity_months: 12
                    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
                    created_at: '2026-10-21T13:00:00.000Z'
                    updated_at: '2026-10-21T13:00:30.000Z'
        '404':
          $ref: '#/components/responses/NotFoundCancel'
      x-codeSamples:
        - lang: curl
          label: cURL
          source: >-
            # Gere uma chave para cada ação. Ao reenviar a mesma chamada, use a
            mesma chave.

            # Timeout de 35 s: a chamada espera até 30 s pelo resultado.

            # Na resposta 200, confira se status é cancelled e verifique error.
            Se ainda não estiver cancelado, consulte o protocolo de novo.

            curl -X POST
            'https://certificados.zapsign.com.br/api/v2/partners/protocols/CPR_01K7Q3ZB8M4N6P2R5T9V1W3X5Y/cancel'
            \
              -H 'Authorization: Bearer czk_live_SUA_CHAVE' \
              -H 'Idempotency-Key: 3f2b8a1e-7c4d-4e0a-9b51-6d2f8c9e1a47' \
              --max-time 35
        - lang: javascript
          label: Node.js (fetch)
          source: >-
            // Timeout de 35 s: a chamada espera até 30 s pelo resultado.

            // Gere a chave uma vez por ação e reutilize-a ao reenviar a mesma
            chamada.

            const idempotencyKey = crypto.randomUUID();

            const res = await fetch(
              'https://certificados.zapsign.com.br/api/v2/partners/protocols/CPR_01K7Q3ZB8M4N6P2R5T9V1W3X5Y/cancel',
              {
                method: 'POST',
                headers: {
                  Authorization: 'Bearer czk_live_SUA_CHAVE',
                  'Idempotency-Key': idempotencyKey,
                },
                signal: AbortSignal.timeout(35_000),
              },
            );

            const protocolo = await res.json();

            // Na resposta 200, confira se `protocolo.status` é `cancelled` e
            verifique `error`. Se o cancelamento ainda não estiver confirmado,
            consulte o protocolo de novo.
        - lang: python
          label: Python (requests)
          source: >-
            import requests

            import uuid


            # Timeout de 35 s: a chamada espera até 30 s pelo resultado.

            # Gere a chave uma vez por ação e reutilize-a ao reenviar a mesma
            chamada.

            idempotency_key = str(uuid.uuid4())

            res = requests.post(
                'https://certificados.zapsign.com.br/api/v2/partners/protocols/CPR_01K7Q3ZB8M4N6P2R5T9V1W3X5Y/cancel',
                headers={
                    'Authorization': 'Bearer czk_live_SUA_CHAVE',
                    'Idempotency-Key': idempotency_key,
                },
                timeout=35,
            )

            protocolo = res.json()

            # Na resposta 200, confira se protocolo['status'] é cancelled e
            verifique error. Se o cancelamento ainda não estiver confirmado,
            consulte o protocolo de novo.
components:
  parameters:
    ProtocolId:
      name: protocol_id
      in: path
      required: true
      description: >-
        Identificador do protocolo, devolvido ao criar. Formato `CPR_` seguido
        de 26 caracteres.
      schema:
        type: string
        pattern: ^CPR_[0-9A-HJKMNP-TV-Z]{26}$
      example: CPR_01K7Q3ZB8M4N6P2R5T9V1W3X5Y
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      description: >-
        Identificador da ação, para reenviar a chamada sem repeti-la. Use a
        mesma chave ao reenviar e outra para cada nova ação. Letras, números e
        `. _ : -`, sem dados pessoais. Não expira. Máx. 128 caracteres.
      schema:
        type: string
        pattern: ^[A-Za-z0-9._:-]{1,128}$
        minLength: 1
        maxLength: 128
      example: 3f2b8a1e-7c4d-4e0a-9b51-6d2f8c9e1a47
  headers:
    IdempotentReplayed:
      description: Indica que a API reconheceu um reenvio da mesma chamada.
      schema:
        type: string
        enum:
          - 'true'
    XRequestId:
      description: Identificador da chamada. Informe-o ao suporte se precisar de ajuda.
      schema:
        type: string
        example: 01K7Q4A1B2C3D4E5F6G7H8J9KM
  schemas:
    Protocol:
      type: object
      required:
        - protocol_id
        - status
        - certificate
        - customer
        - created_at
        - updated_at
      properties:
        status:
          $ref: '#/components/schemas/ProtocolStatus'
        error:
          $ref: '#/components/schemas/ProtocolError'
        protocol_id:
          type: string
          description: >-
            Identificador do protocolo. Use nas chamadas de consulta,
            agendamento e cancelamento.
          pattern: ^CPR_[0-9A-HJKMNP-TV-Z]{26}$
          example: CPR_01K7Q3ZB8M4N6P2R5T9V1W3X5Y
        external_id:
          type: string
          description: Seu identificador do pedido, se você enviou um ao criar.
          example: PEDIDO_12345
        protocol_number:
          type: string
          description: >-
            Número do protocolo. Compartilhe com o titular para emitir o
            certificado. Disponível depois que o protocolo é gerado.
          example: '7800'
        protocol_url:
          type: string
          description: >-
            Link da fila da videoconferência. Compartilhe com o titular. Aparece
            só em `protocol_generated`, quando o link está disponível.
          format: uri
          example: https://sistemas.gestaocd.com.br/fila/Xk3pQ9vT2a/52998224725/7800
        appointment:
          $ref: '#/components/schemas/Appointment'
          description: >-
            Videoconferência agendada. Aparece depois que o horário é
            confirmado. Ao reagendar, mantém o horário anterior até a
            confirmação do novo.
        valid_until:
          type:
            - string
            - 'null'
          description: >-
            Fim da validade do certificado, em UTC. Aparece quando o certificado
            é emitido.
          format: date-time
          example: '2027-10-20T14:10:00.000Z'
        certificate:
          $ref: '#/components/schemas/Certificate'
        customer:
          $ref: '#/components/schemas/Customer'
        created_at:
          type: string
          description: Data e hora de criação do protocolo, em UTC.
          format: date-time
          example: '2026-10-21T13:00:00.000Z'
        updated_at:
          type: string
          description: Data e hora da última atualização do protocolo, em UTC.
          format: date-time
          example: '2026-10-21T13:00:30.000Z'
    ProtocolStatus:
      type: string
      description: >-
        Status do protocolo.


        | Valor | Significado |

        | --- | --- |

        | `creating` | O protocolo está sendo criado. |

        | `protocol_generated` | O protocolo foi gerado e já tem número. |

        | `appointment_scheduled` | A videoconferência está agendada para o
        horário de `appointment`. |

        | `certificate_issued` | O certificado foi emitido. |

        | `cancelled` | O protocolo foi cancelado e o certificado voltou ao
        saldo. |

        | `creation_failed` | Não foi possível criar o protocolo. Nada foi
        descontado do saldo. |
      enum:
        - creating
        - protocol_generated
        - appointment_scheduled
        - certificate_issued
        - cancelled
        - creation_failed
    ProtocolError:
      type: object
      description: >-
        Falha da última ação (criar, agendar ou cancelar). Só aparece quando a
        ação falhou.
      required:
        - code
        - message
      properties:
        code:
          $ref: '#/components/schemas/ProtocolErrorCode'
        reason:
          $ref: '#/components/schemas/ProtocolErrorReason'
        message:
          type: string
          description: Mensagem em português sobre a falha.
          example: O horário escolhido não está mais disponível. Escolha outro horário.
    Appointment:
      type: object
      description: Videoconferência agendada.
      required:
        - date
        - time
        - timezone
      properties:
        date:
          type: string
          description: Dia da videoconferência. Formato `AAAA-MM-DD`.
          format: date
          example: '2026-10-22'
        time:
          type: string
          description: Horário da videoconferência, de Brasília. Formato `HH:MM`.
          example: '11:30'
        timezone:
          type: string
          description: Fuso horário de `date` e `time`, hoje `America/Sao_Paulo`.
          example: America/Sao_Paulo
    Certificate:
      type: object
      description: Certificado do protocolo.
      required:
        - type
        - model
        - validity_months
        - name
      properties:
        name:
          type: string
          description: Nome do certificado, para exibir ao titular.
          example: e-CPF A1 (1 ano)
        type:
          $ref: '#/components/schemas/CertificateType'
        model:
          $ref: '#/components/schemas/CertificateModel'
        validity_months:
          $ref: '#/components/schemas/ValidityMonths'
    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
    ProtocolErrorCode:
      type: string
      description: >-
        Código da falha. Veja o que fazer em [Ciclo de vida do
        protocolo](/ciclo-de-vida-do-protocolo).


        | Valor | Significado |

        | --- | --- |

        | `slot_unavailable` | O horário escolhido não está mais disponível. |

        | `appointment_rejected` | O agendamento não foi confirmado. |

        | `reschedule_rejected` | O novo horário não foi confirmado. |

        | `provider_unavailable` | O serviço está indisponível no momento. |

        | `order_not_created` | A criação do protocolo não foi concluída e nada
        foi descontado do saldo. Crie outro protocolo com uma nova
        `Idempotency-Key` e outro `external_id`. |

        | `protocol_not_created` | O protocolo não foi gerado e nada foi
        descontado do saldo. Crie outro protocolo com uma nova `Idempotency-Key`
        e outro `external_id`. |

        | `invalid_state` | O protocolo não pode ser cancelado. |
      enum:
        - slot_unavailable
        - appointment_rejected
        - reschedule_rejected
        - provider_unavailable
        - order_not_created
        - protocol_not_created
        - invalid_state
    ProtocolErrorReason:
      type: string
      description: >-
        Detalhe da falha. Só aparece com `protocol_not_created`.


        | Valor | Significado |

        | --- | --- |

        | `holder_email_in_use` | O e-mail já estava vinculado a outro CPF e a
        Autoridade Certificadora recusou o protocolo. Nada foi descontado do
        saldo. Crie outro protocolo com outro e-mail, uma nova `Idempotency-Key`
        e outro `external_id`. |
      enum:
        - holder_email_in_use
    CertificateType:
      type: string
      description: >-
        Tipo do certificado. `e_cpf` é para titular `pf` e `e_cnpj` para titular
        `pj`.


        | Valor | Significado |

        | --- | --- |

        | `e_cpf` | Certificado e-CPF, para titular pessoa física. |

        | `e_cnpj` | Certificado e-CNPJ, para titular pessoa jurídica. |
      enum:
        - e_cpf
        - e_cnpj
    CertificateModel:
      type: string
      description: >-
        Modelo do certificado.


        | Valor | Significado |

        | --- | --- |

        | `a1` | Certificado em arquivo, instalado no computador do titular. |

        | `a3_em_nuvem` | Certificado guardado na nuvem, usado de qualquer
        dispositivo. |
      enum:
        - a1
        - a3_em_nuvem
    ValidityMonths:
      type: integer
      enum:
        - 12
      description: Validade do certificado, em meses. Hoje só `12` (1 ano).
    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
  responses:
    NotFoundCancel:
      description: Protocolo não encontrado. Veja o que fazer em [Erros](/erros).
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
      content:
        application/problem+json:
          schema:
            type: object
            required:
              - type
              - status
              - code
              - message
              - retryable
              - request_id
            properties:
              code:
                type: string
                description: |-
                  Código do erro. Veja como corrigir em [Erros](/erros).

                  | Valor | Significado |
                  | --- | --- |
                  | `not_found` | O protocolo não foi encontrado. |
                enum:
                  - not_found
              message:
                type: string
                description: Mensagem em português sobre o erro.
                example: Erro de validação no corpo da requisição.
              retryable:
                type: boolean
                description: '`true` quando vale reenviar a mesma chamada.'
                example: false
              status:
                type: integer
                description: Status HTTP da resposta.
                example: 400
              type:
                type: string
                description: URL da página do erro.
                format: uri
                example: >-
                  https://docs.certificados.zapsign.com.br/erros/validation_error
              request_id:
                type: string
                description: Identificador da chamada, igual ao header `X-Request-Id`.
                example: 01K7Q4A1B2C3D4E5F6G7H8J9KM
          examples:
            Protocolo não encontrado:
              summary: Protocolo não encontrado
              value:
                code: not_found
                message: Recurso não encontrado.
                retryable: false
                status: 404
                type: https://docs.certificados.zapsign.com.br/erros/not_found
                request_id: 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.