Início rápido

Neste passo a passo, você consulta o saldo e os certificados, verifica o titular, cria um protocolo, agenda a videoconferência e cancela o protocolo. Os exemplos usam a chave czk_live_SUA_CHAVE. Troque pela sua.

Não há ambiente de testes. O passo 3 desconta 1 certificado do saldo real, e o passo 6 devolve esse certificado.

Consulte o saldo e os certificados

Cada protocolo desconta 1 certificado do saldo.

curl https://certificados.zapsign.com.br/api/v2/partners/credits \
  -H "Authorization: Bearer czk_live_SUA_CHAVE"

{ "credits_available": 4 }

Liste os certificados que você pode criar.

curl https://certificados.zapsign.com.br/api/v2/partners/protocol-products \
  -H "Authorization: Bearer czk_live_SUA_CHAVE"

Resposta (resumida):

{
  "data": [
    { "name": "e-CPF A1 (1 ano)", "type": "e_cpf", "model": "a1", "validity_months": 12, "credits_required": 1 },
    ...
  ],
  "has_more": false,
  "object": "list"
}

Escolha um item de data. No passo 3, copie type, model e validity_months desse item para certificate.

Verifique o titular

Confira os dados antes de criar o protocolo. A verificação não desconta saldo.

curl -X POST https://certificados.zapsign.com.br/api/v2/partners/customer-verifications \
  -H "Authorization: Bearer czk_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "type": "pf", "cpf": "52998224725", "birth_date": "1990-01-02" }'

Resposta (resumida):

{
  "verification_result": "approved",
  "customer": { "type": "pf", "name": "Ana Souza", "cpf": "52998224725", "birth_date": "1990-01-02", ... }
}

Confira verification_result, mesmo quando a resposta for 200. Se o valor não for approved, interrompa a criação e siga a orientação de message.

Crie o protocolo

Gere uma chave de idempotência para esta criação. Ao reenviar a mesma chamada, mantenha a chave e os dados. Não envie name nem company_name: a API preenche os dois. Em certificate, use type, model e validity_months do item escolhido no passo 1.Use o e-mail do próprio cliente. Cada e-mail só pode ser usado com um CPF, por exigência da Autoridade Certificadora que emite o certificado. Um mesmo CPF pode usar mais de um e-mail. O e-mail não pode ter o sinal +.

curl -X POST https://certificados.zapsign.com.br/api/v2/partners/protocols \
  -H "Authorization: Bearer czk_live_SUA_CHAVE" \
  -H "Idempotency-Key: pedido-12345-criar-1" \
  -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"
  }'

A API responde 202 com o protocolo em creating. Se o e-mail já estiver vinculado a outro CPF, a resposta é 422 holder_email_in_use; se tiver o sinal +, é 400 validation_error. Nos dois casos nada é criado: troque o e-mail e reenvie com a mesma chave.Resposta (resumida):

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

Para e-CNPJ, use e_cnpj em certificate.type. Informe a empresa em customer e o representante legal em representative. Veja o exemplo completo em Cria protocolo.

Acompanhe o protocolo

O cabeçalho Location traz o caminho para consultar o protocolo. Consulte a cada 5 segundos enquanto status for creating. Esse intervalo vem no cabeçalho Retry-After da criação.

curl https://certificados.zapsign.com.br/api/v2/partners/protocols/CPR_01K7Q3ZB8M4N6P2R5T9V1W3X5Y \
  -H "Authorization: Bearer czk_live_SUA_CHAVE"

Resposta (resumida):

{
  "status": "protocol_generated",
  "protocol_id": "CPR_01K7Q3ZB8M4N6P2R5T9V1W3X5Y",
  "external_id": "PEDIDO_12345",
  "protocol_number": "7800",
  "protocol_url": "https://sistemas.gestaocd.com.br/fila/Xk3pQ9vT2a/52998224725/7800",
  ...
}

Compartilhe protocol_number com o titular para emitir o certificado digital. Quando a resposta trouxer protocol_url, compartilhe também esse link para entrar na fila da videoconferência.Guarde protocol_id nos seus registros para consultar o protocolo pela API. Se a criação falhar, siga as instruções do Ciclo de vida.

Agende a videoconferência

Consulte os horários livres e escolha um. Listar os horários não reserva nenhum. Os exemplos usam datas fixas: use um date e um time que GET /appointment-slots devolver.

curl "https://certificados.zapsign.com.br/api/v2/partners/appointment-slots?from=2026-10-22&days=5" \
  -H "Authorization: Bearer czk_live_SUA_CHAVE"

{
  "data": [
    { "date": "2026-10-22", "times": ["10:00", "11:30"] },
    { "date": "2026-10-23", "times": [] },
    { "date": "2026-10-24", "times": [] },
    { "date": "2026-10-25", "times": [] },
    { "date": "2026-10-26", "times": ["08:00"] }
  ],
  "has_more": true,
  "bookable_until": "2026-11-19",
  "timezone": "America/Sao_Paulo",
  "object": "list"
}

Dias sem horário livre vêm com times vazio. Se has_more for true, use em from o dia seguinte ao último recebido. Os horários usam America/Sao_Paulo (horário de Brasília).Agende o horário escolhido. Defina um tempo limite de pelo menos 35 segundos: a chamada espera até 30 segundos pelo resultado.

curl -X POST https://certificados.zapsign.com.br/api/v2/partners/protocols/CPR_01K7Q3ZB8M4N6P2R5T9V1W3X5Y/appointment \
  -H "Authorization: Bearer czk_live_SUA_CHAVE" \
  -H "Idempotency-Key: pedido-12345-agendar-1" \
  -H "Content-Type: application/json" \
  -d '{ "date": "2026-10-22", "time": "10:00" }'

Resposta (resumida):

{
  "status": "appointment_scheduled",
  "protocol_id": "CPR_01K7Q3ZB8M4N6P2R5T9V1W3X5Y",
  "external_id": "PEDIDO_12345",
  "appointment": { "date": "2026-10-22", "time": "10:00", "timezone": "America/Sao_Paulo" },
  ...
}

Confira status, appointment e error, mesmo com uma resposta 200.

Confirme appointment_scheduled e o dia e horário escolhidos em appointment.
Se o resultado ainda não aparecer e não houver error, consulte o protocolo de novo. Não repita a ação com uma nova chave.
Se error.code for slot_unavailable, escolha outro horário e use uma nova chave, como pedido-12345-agendar-2.
Para outros erros, siga o Ciclo de vida.

Cancele o protocolo

Cancele antes da emissão do certificado. O cancelamento devolve 1 certificado ao saldo. A chamada não tem corpo e exige uma chave nova, porque é uma nova ação.

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: pedido-12345-cancelar-1"

Resposta (resumida):

{
  "status": "cancelled",
  "protocol_id": "CPR_01K7Q3ZB8M4N6P2R5T9V1W3X5Y",
  "external_id": "PEDIDO_12345",
  ...
}

Como no agendamento, defina um tempo limite de pelo menos 35 segundos e confira status e error, mesmo com 200. Confirme cancelled. Se error.code for invalid_state, o protocolo continua ativo e não pode ser cancelado. Veja as regras de cancelamento.

Chaves de idempotência

Os exemplos usam uma chave por ação: pedido-12345-criar-1, pedido-12345-agendar-1 e pedido-12345-cancelar-1. O sufixo -1 marca a primeira tentativa. Para uma nova ação, como outro horário, troque a chave, por exemplo para pedido-12345-agendar-2. Veja Idempotência.

Outras ações

Crie já agendado com appointment em POST /protocols.
Reagende a videoconferência com o mesmo endpoint de agendamento.
Liste os protocolos com GET /protocols.

Próximos passos

Ciclo de vida do protocolo

Os status do protocolo e o que fazer em cada um.

Idempotência

Reenvie com segurança, sem duplicar protocolos.

Erros

Formato dos erros e quando tentar de novo.

Começar

Conceitos

Chaves de idempotência

Outras ações

Próximos passos

Ciclo de vida do protocolo

Idempotência

Erros

​Chaves de idempotência

​Outras ações

​Próximos passos

Ciclo de vida do protocolo

Idempotência

Erros

Chaves de idempotência

Outras ações

Próximos passos