Cancela protocolo

POST

api

partners

protocols

{protocol_id}

cancel

cURL

# 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

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

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.

{
  "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"
}

{
  "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"
}

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.

Veja também:

Autorizações

Authorization

string

header

obrigatório

API key criada no portal do parceiro.

Cabeçalhos

Idempotency-Key

string

obrigatório

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.

Required string length: 1 - 128

Pattern: ^[A-Za-z0-9._:-]{1,128}$

Parâmetros de caminho

protocol_id

string

obrigatório

Identificador do protocolo, devolvido ao criar. Formato CPR_ seguido de 26 caracteres.

Pattern: ^CPR_[0-9A-HJKMNP-TV-Z]{26}$

Resposta

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.

status

enum<string>

obrigatório

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.

Opções disponíveis:

creating,

protocol_generated,

appointment_scheduled,

certificate_issued,

cancelled,

creation_failed

protocol_id

string

obrigatório

Identificador do protocolo. Use nas chamadas de consulta, agendamento e cancelamento.

Pattern: ^CPR_[0-9A-HJKMNP-TV-Z]{26}$

Exemplo:

"CPR_01K7Q3ZB8M4N6P2R5T9V1W3X5Y"

certificate

object

obrigatório

Certificado do protocolo.

Show child attributes

customer

Pessoa física · object

obrigatório

Titular pessoa física.

Pessoa física
Pessoa jurídica

Show child attributes

created_at

string<date-time>

obrigatório

Data e hora de criação do protocolo, em UTC.

Exemplo:

"2026-10-21T13:00:00.000Z"

updated_at

string<date-time>

obrigatório

Data e hora da última atualização do protocolo, em UTC.

Exemplo:

"2026-10-21T13:00:30.000Z"

error

object

Falha da última ação (criar, agendar ou cancelar). Só aparece quando a ação falhou.

Show child attributes

external_id

string

Seu identificador do pedido, se você enviou um ao criar.

Exemplo:

"PEDIDO_12345"

protocol_number

string

Número do protocolo. Compartilhe com o titular para emitir o certificado. Disponível depois que o protocolo é gerado.

Exemplo:

"7800"

protocol_url

string<uri>

Link da fila da videoconferência. Compartilhe com o titular. Aparece só em protocol_generated, quando o link está disponível.

Exemplo:

"https://sistemas.gestaocd.com.br/fila/Xk3pQ9vT2a/52998224725/7800"

appointment

object

Videoconferência agendada. Aparece depois que o horário é confirmado. Ao reagendar, mantém o horário anterior até a confirmação do novo.

Show child attributes

valid_until

string<date-time> | null

Fim da validade do certificado, em UTC. Aparece quando o certificado é emitido.

Exemplo:

"2027-10-20T14:10:00.000Z"

cURL

# 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

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

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.

{
  "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"
}

{
  "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"
}

Referência da API

Protocolos

Verificação

Agendamento

Saldo e catálogo

Autorizações

Cabeçalhos

Parâmetros de caminho

Resposta