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

# Ciclo de vida do protocolo

> As etapas do protocolo e o que fazer em cada uma.

O campo `status` diz em que etapa o protocolo está. Consulte-o com `GET /protocols/{protocol_id}`.

```mermaid theme={"system"}
stateDiagram-v2
    [*] --> creating
    creating --> protocol_generated
    creating --> creation_failed
    protocol_generated --> appointment_scheduled: agendar
    protocol_generated --> certificate_issued
    protocol_generated --> cancelled: cancelar
    appointment_scheduled --> certificate_issued
    appointment_scheduled --> cancelled: cancelar
```

Reagendar mantém o status `appointment_scheduled`. Os status finais são `certificate_issued`, `cancelled` e `creation_failed`.

| Status | O que significa e o que fazer |
| - | - |
| `creating` | O protocolo está sendo criado. Siga a regra de consulta abaixo. |
| `protocol_generated` | O protocolo foi criado. Compartilhe `protocol_number` com o titular para emitir o certificado digital. Compartilhe também `protocol_url`, quando existir, para entrar na fila da videoconferência. Você também pode agendar um horário ou cancelar. |
| `appointment_scheduled` | A videoconferência está marcada para o horário de `appointment`. Aguarde, reagende ou cancele se precisar. |
| `certificate_issued` | O certificado foi emitido, e `valid_until` traz a validade. |
| `cancelled` | O protocolo foi cancelado e 1 certificado voltou ao saldo. |
| `creation_failed` | O protocolo não foi criado e nada foi descontado do saldo. `error` traz o motivo. Crie de novo com uma nova `Idempotency-Key` e outro `external_id`: o anterior continua em uso. |

A API não envia webhooks. Consulte o protocolo para saber quando o `status` muda.

## Quando consultar de novo

Consulte a cada 5 segundos enquanto `status` for `creating`. Esse intervalo vem no cabeçalho `Retry-After` da criação.

Depois de agendar, reagendar ou cancelar, confira o resultado esperado:

| Ação | Como confirmar |
| - | - |
| Agendar ou reagendar | O `status` é `appointment_scheduled` e `appointment` traz o dia e horário escolhidos. |
| Cancelar | O `status` é `cancelled`. |

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 de idempotência. Se nada mudar, fale com o suporte.

Ao reagendar, `appointment` mantém o horário anterior até a confirmação do novo horário.

## Resultado da ação

Ao agendar, reagendar ou cancelar:

* Defina um tempo limite de pelo menos 35 segundos. A chamada espera até 30 segundos pelo resultado.
* Confira `status`, `appointment` e `error`, mesmo quando a resposta for `200`.
* Se a ação falhar, `error.code` e `error.message` explicam o motivo. Siga a tabela abaixo.

Se uma nova ação responder `409 operation_in_progress`, aguarde alguns segundos e consulte o protocolo. Para tentar novamente, mantenha a mesma chave e siga a orientação de [Erros](https://docs.certificados.zapsign.com.br/erros/operation_in_progress).

## Criar já agendado

Sem `appointment` no `POST /protocols`, o titular pode entrar na fila da videoconferência. Com `appointment`, a API também solicita o agendamento. O campo `appointment` só aparece na resposta depois que o horário é confirmado.

Quando a criação e o agendamento dão certo, o protocolo passa por estas etapas:

1. `creating`.
2. `protocol_generated`.
3. `appointment_scheduled`, com o dia e horário confirmados em `appointment`.

Continue consultando até confirmar o agendamento ou receber `error`.

Se o horário não estiver livre, o protocolo fica em `protocol_generated` com `error.code` igual a `slot_unavailable`. Escolha outro horário com `POST /protocols/{protocol_id}/appointment`.

## Cancelar

`POST /protocols/{protocol_id}/cancel` cancela o protocolo antes da emissão e devolve 1 certificado ao saldo. A devolução só vale quando o `status` for `cancelled`.

Só `protocol_generated` e `appointment_scheduled` aceitam cancelamento. O resultado depende de onde a API barra a ação:

| Resposta | Quando acontece | O que fazer |
| - | - | - |
| `200`, `status` igual a `cancelled` | O cancelamento foi confirmado. | Nada. O saldo recebeu 1 certificado. |
| `409 action_not_allowed` | O `status` não é `protocol_generated` nem `appointment_scheduled`, ou o protocolo não cumpre as regras de cancelamento. A API recusou a chamada antes de aceitá-la. | Consulte o protocolo. Não repita a chamada. |
| `200` com `error.code` igual a `invalid_state` | A API aceitou a chamada e, ao verificar o protocolo, concluiu que ele não pode ser cancelado. `status` e saldo não mudam. | Não tente cancelar de novo. |
| `200` com `error.code` igual a `provider_unavailable` | A API não conseguiu verificar o protocolo. Nada mudou. | Tente de novo com uma nova `Idempotency-Key`. |

## Códigos de `error`

O campo `error` descreve só a última ação: criar, agendar, reagendar ou cancelar. Ele aparece quando essa ação falhou. Enquanto uma nova ação roda, ou depois que ela dá certo, `error` não aparece. Em `certificate_issued` e `cancelled`, `error` nunca aparece.

Estes códigos vêm no campo `error` do protocolo. Eles são diferentes dos erros HTTP da página [Erros](https://docs.certificados.zapsign.com.br/erros.md).

| `error.code` | Quando aparece | O que fazer |
| - | - | - |
| `slot_unavailable` | Ao criar já agendado, agendar ou reagendar. | Escolha outro horário com `POST /protocols/{protocol_id}/appointment`. |
| `appointment_rejected` | Ao criar já agendado ou agendar pela primeira vez. | Escolha outro horário. O protocolo continua em `protocol_generated`. |
| `reschedule_rejected` | Ao reagendar. | Escolha outro horário. O agendamento anterior continua valendo. |
| `provider_unavailable` | Ao criar, agendar, reagendar ou cancelar. | Nada foi alterado. Reenvie com uma nova `Idempotency-Key`. |
| `order_not_created`, `protocol_not_created` | Ao criar. O `status` é `creation_failed`. | Nada foi descontado do saldo. Crie outro protocolo com uma nova `Idempotency-Key` e outro `external_id`: o anterior continua em uso. |
| `protocol_not_created` com `error.reason` igual a `holder_email_in_use` | Ao criar. O `status` é `creation_failed`. O e-mail já estava vinculado a outro CPF e a Autoridade Certificadora recusou o protocolo. | Nada foi descontado do saldo. Peça ao cliente um e-mail próprio e crie outro protocolo com esse e-mail, uma nova `Idempotency-Key` e outro `external_id`. |
| `invalid_state` | Ao cancelar. | O protocolo não pode ser cancelado. Veja [Cancelar](#cancelar). |

`error.reason` é opcional e detalha o `error.code`. Hoje só aparece com `protocol_not_created`, e o único valor é `holder_email_in_use`. Decida primeiro por `error.code`; sem `reason`, siga a linha do código.

```json theme={"system"}
"status": "creation_failed",
"error": {
  "code": "protocol_not_created",
  "reason": "holder_email_in_use",
  "message": "Este e-mail já está vinculado a outro CPF. Cada CPF precisa de um e-mail próprio. Use outro e-mail."
}
```


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