Pular para o conteúdo principal
O campo status diz em que etapa o protocolo está. Consulte-o com GET /protocols/{protocol_id}. Reagendar mantém o status appointment_scheduled. Os status finais são certificate_issued, cancelled e creation_failed. 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: 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.

​
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:

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