Cria protocolo

POST

api

partners

protocols

cURL

# Gere uma chave para cada ação. Ao reenviar a mesma chamada, use a mesma chave.
# A resposta é 202. Consulte o protocolo até o status ser protocol_generated ou creation_failed.
curl -X POST 'https://certificados.zapsign.com.br/api/v2/partners/protocols' \
  -H 'Authorization: Bearer czk_live_SUA_CHAVE' \
  -H 'Idempotency-Key: 3f2b8a1e-7c4d-4e0a-9b51-6d2f8c9e1a47' \
  -H 'Content-Type: application/json' \
  -d '{
    "certificate": {
      "type": "e_cpf",
      "model": "a1",
      "validity_months": 12
    },
    "customer": {
      "type": "pf",
      "cpf": "52998224725",
      "birth_date": "1990-01-02",
      "email": "ana@exemplo.com.br",
      "phone": "+5511987654321",
      "address": {
        "cep": "01310100",
        "street": "Rua das Flores",
        "number": "123",
        "neighborhood": "Centro",
        "city": "São Paulo",
        "state": "SP"
      }
    },
    "external_id": "PEDIDO_12345"
  }'

// 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',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer czk_live_SUA_CHAVE',
      'Idempotency-Key': idempotencyKey,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      certificate: {
        type: 'e_cpf',
        model: 'a1',
        validity_months: 12,
      },
      customer: {
        type: 'pf',
        cpf: '52998224725',
        birth_date: '1990-01-02',
        email: 'ana@exemplo.com.br',
        phone: '+5511987654321',
        address: {
          cep: '01310100',
          street: 'Rua das Flores',
          number: '123',
          neighborhood: 'Centro',
          city: 'São Paulo',
          state: 'SP',
        },
      },
      external_id: 'PEDIDO_12345',
    }),
  },
);
const protocolo = await res.json();
// A resposta é 202. Consulte o protocolo até `protocolo.status` ser `protocol_generated` ou `creation_failed`.

import requests
import uuid

# 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',
    headers={
        'Authorization': 'Bearer czk_live_SUA_CHAVE',
        'Idempotency-Key': idempotency_key,
    },
    json={
        'certificate': {
            'type': 'e_cpf',
            'model': 'a1',
            'validity_months': 12,
        },
        'customer': {
            'type': 'pf',
            'cpf': '52998224725',
            'birth_date': '1990-01-02',
            'email': 'ana@exemplo.com.br',
            'phone': '+5511987654321',
            'address': {
                'cep': '01310100',
                'street': 'Rua das Flores',
                'number': '123',
                'neighborhood': 'Centro',
                'city': 'São Paulo',
                'state': 'SP',
            },
        },
        'external_id': 'PEDIDO_12345',
    },
)
protocolo = res.json()
# A resposta é 202. Consulte o protocolo até protocolo['status'] ser protocol_generated ou creation_failed.

{
  "status": "creating",
  "protocol_id": "CPR_01K7Q3ZB8M4N6P2R5T9V1W3X5Y",
  "external_id": "PEDIDO_12345",
  "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:00.000Z"
}

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}$

Corpo

application/json

Dados do novo protocolo.

certificate

object

obrigatório

Certificado a emitir. Use uma combinação de GET /protocol-products. O credits_required dela é descontado do saldo.

Show child attributes

customer

Pessoa física · object

obrigatório

Titular pessoa física, para e-CPF.

Pessoa física
Pessoa jurídica

Show child attributes

appointment

object

Horário da videoconferência. Escolha um horário livre em Lista horários: os exemplos têm datas fixas. Sem este campo, o titular pode entrar na fila de atendimento.

Show child attributes

external_id

string

Identificador do pedido no seu sistema. Vem de volta no protocolo. Não pode repetir entre os seus protocolos, nem em um cancelado ou que falhou. Máx. 100 caracteres.

Required string length: 1 - 100

Exemplo:

"PEDIDO_12345"

Resposta

Protocolo aceito, com status creating. Consulte o protocolo em Location até o status ser protocol_generated ou creation_failed. Com appointment, a resposta é a mesma: o horário aparece ao consultar o protocolo.

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.
# A resposta é 202. Consulte o protocolo até o status ser protocol_generated ou creation_failed.
curl -X POST 'https://certificados.zapsign.com.br/api/v2/partners/protocols' \
  -H 'Authorization: Bearer czk_live_SUA_CHAVE' \
  -H 'Idempotency-Key: 3f2b8a1e-7c4d-4e0a-9b51-6d2f8c9e1a47' \
  -H 'Content-Type: application/json' \
  -d '{
    "certificate": {
      "type": "e_cpf",
      "model": "a1",
      "validity_months": 12
    },
    "customer": {
      "type": "pf",
      "cpf": "52998224725",
      "birth_date": "1990-01-02",
      "email": "ana@exemplo.com.br",
      "phone": "+5511987654321",
      "address": {
        "cep": "01310100",
        "street": "Rua das Flores",
        "number": "123",
        "neighborhood": "Centro",
        "city": "São Paulo",
        "state": "SP"
      }
    },
    "external_id": "PEDIDO_12345"
  }'

// 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',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer czk_live_SUA_CHAVE',
      'Idempotency-Key': idempotencyKey,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      certificate: {
        type: 'e_cpf',
        model: 'a1',
        validity_months: 12,
      },
      customer: {
        type: 'pf',
        cpf: '52998224725',
        birth_date: '1990-01-02',
        email: 'ana@exemplo.com.br',
        phone: '+5511987654321',
        address: {
          cep: '01310100',
          street: 'Rua das Flores',
          number: '123',
          neighborhood: 'Centro',
          city: 'São Paulo',
          state: 'SP',
        },
      },
      external_id: 'PEDIDO_12345',
    }),
  },
);
const protocolo = await res.json();
// A resposta é 202. Consulte o protocolo até `protocolo.status` ser `protocol_generated` ou `creation_failed`.

import requests
import uuid

# 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',
    headers={
        'Authorization': 'Bearer czk_live_SUA_CHAVE',
        'Idempotency-Key': idempotency_key,
    },
    json={
        'certificate': {
            'type': 'e_cpf',
            'model': 'a1',
            'validity_months': 12,
        },
        'customer': {
            'type': 'pf',
            'cpf': '52998224725',
            'birth_date': '1990-01-02',
            'email': 'ana@exemplo.com.br',
            'phone': '+5511987654321',
            'address': {
                'cep': '01310100',
                'street': 'Rua das Flores',
                'number': '123',
                'neighborhood': 'Centro',
                'city': 'São Paulo',
                'state': 'SP',
            },
        },
        'external_id': 'PEDIDO_12345',
    },
)
protocolo = res.json()
# A resposta é 202. Consulte o protocolo até protocolo['status'] ser protocol_generated ou creation_failed.

{
  "status": "creating",
  "protocol_id": "CPR_01K7Q3ZB8M4N6P2R5T9V1W3X5Y",
  "external_id": "PEDIDO_12345",
  "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:00.000Z"
}

Referência da API

Protocolos

Verificação

Agendamento

Saldo e catálogo

Autorizações

Cabeçalhos

Corpo

Resposta