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

# Início rápido

> Do saldo ao cancelamento: consulte, verifique, crie, agende e cancele um protocolo.

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.

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

**1. Consulte o saldo e os certificados**

Cada protocolo desconta 1 certificado do saldo.

```bash theme={"system"}
curl https://certificados.zapsign.com.br/api/v2/partners/credits \
  -H "Authorization: Bearer czk_live_SUA_CHAVE"
```

```json theme={"system"}
{ "credits_available": 4 }
```

Liste os certificados que você pode criar.

```bash theme={"system"}
curl https://certificados.zapsign.com.br/api/v2/partners/protocol-products \
  -H "Authorization: Bearer czk_live_SUA_CHAVE"
```

Resposta (resumida):

```json theme={"system"}
{
  "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`.

**2. Verifique o titular**

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

```bash theme={"system"}
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):

```json theme={"system"}
{
  "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`.

**3. 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 `+`.

```bash theme={"system"}
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`](https://docs.certificados.zapsign.com.br/erros/holder_email_in_use); se tiver o sinal `+`, é `400` [`validation_error`](https://docs.certificados.zapsign.com.br/erros/validation_error). Nos dois casos nada é criado: troque o e-mail e reenvie com a mesma chave.

Resposta (resumida):

```json theme={"system"}
{
  "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](https://docs.certificados.zapsign.com.br/api-reference/protocolos/cria-protocolo.md).

**4. 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.

```bash theme={"system"}
curl https://certificados.zapsign.com.br/api/v2/partners/protocols/CPR_01K7Q3ZB8M4N6P2R5T9V1W3X5Y \
  -H "Authorization: Bearer czk_live_SUA_CHAVE"
```

Resposta (resumida):

```json theme={"system"}
{
  "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](https://docs.certificados.zapsign.com.br/ciclo-de-vida-do-protocolo.md).

**5. 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.

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

```json theme={"system"}
{
  "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.

```bash theme={"system"}
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):

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

> [!NOTE]
>
> 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](https://docs.certificados.zapsign.com.br/ciclo-de-vida-do-protocolo.md).

**6. 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.

```bash theme={"system"}
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):

```json theme={"system"}
{
  "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](https://docs.certificados.zapsign.com.br/ciclo-de-vida-do-protocolo.md#cancelar).

## 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](https://docs.certificados.zapsign.com.br/idempotencia.md).

## Outras ações

* [Crie já agendado](https://docs.certificados.zapsign.com.br/ciclo-de-vida-do-protocolo.md#criar-já-agendado) com `appointment` em `POST /protocols`.
* [Reagende a videoconferência](https://docs.certificados.zapsign.com.br/api-reference/agendamento/agenda-videoconferencia.md) com o mesmo endpoint de agendamento.
* [Liste os protocolos](https://docs.certificados.zapsign.com.br/paginacao.md) com `GET /protocols`.

## Próximos passos

> [card] [Ciclo de vida do protocolo](https://docs.certificados.zapsign.com.br/ciclo-de-vida-do-protocolo.md)
>
> Os status do protocolo e o que fazer em cada um.

> [card] [Idempotência](https://docs.certificados.zapsign.com.br/idempotencia.md)
>
> Reenvie com segurança, sem duplicar protocolos.

> [card] [Erros](https://docs.certificados.zapsign.com.br/erros.md)
>
> Formato dos erros e quando tentar de novo.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.