Estados do envelope

O campo status informa em que ponto do ciclo de assinatura o envelope está. Trate o valor como uma máquina de estados: uma operação aceita em DRAFT pode ser rejeitada depois que o envelope for enviado.

Fluxo principal

DRAFT → PREPARING → SENT → SEALING → COMPLETED
                    ├────────────→ VOIDED
                    ├────────────→ DECLINED
                    ├────────────→ EXPIRED
                    └────────────→ RETURNED → CORRECTING → SENT

PREPARING e SEALING são estados transitórios. A conclusão jurídica e operacional só deve ser considerada quando o status chegar a COMPLETED.

Significado dos estados

Status	Significado	Conduta da integração
`DRAFT`	Rascunho criado e ainda configurável	Adicione documento, participantes, campos e configurações antes de enviar
`PREPARING`	O envio foi reivindicado e está sendo preparado	Não dispare outro envio; consulte novamente com a mesma operação idempotente
`PROCESSING`	Estado de compatibilidade usado por fluxos legados de processamento	Não é esperado no fluxo explícito normal da v4; aguarde ou acione o suporte se persistir
`CORRECTING`	O envelope voltou ao remetente para ajustes	Corrija os dados permitidos e envie novamente
`SENT`	Convites enviados; existem ações pendentes dos participantes	Aguarde assinaturas, use webhook e evite polling agressivo
`SEALING`	Todas as ações terminaram e os documentos finais estão sendo selados	Aguarde; ainda não trate o envelope como concluído
`COMPLETED`	Fluxo concluído e documentos finais disponíveis	Confirme por consulta autenticada e faça o download
`EXPIRED`	O prazo terminou antes da conclusão	Trate como encerrado sem conclusão
`VOIDED`	O envelope foi anulado	Interrompa automações relacionadas ao envio
`DECLINED`	Um participante recusou a ação	Registre a recusa e encaminhe para o fluxo de negócio adequado
`RETURNED`	Um participante devolveu o envelope para ajuste	Aguarde a aprovação do retorno pelo remetente antes de editar ou reenviar

Estados terminais

COMPLETED, EXPIRED, VOIDED e DECLINED encerram o fluxo atual. Não presuma que um envelope pode ser reaberto ou alterado depois disso.

RETURNED não é terminal: ele exige uma decisão do remetente. CORRECTING também não é terminal e pode retornar a SENT após o reenvio.

Consulta recomendada

Use o webhook ENVELOPE_COMPLETED como aviso de mudança e confirme o estado pela API antes de executar uma ação irreversível.

Boas práticas

Persista o envelopeId retornado na criação.

Aceite estados novos sem quebrar o consumidor; registre o valor desconhecido e consulte a documentação.

Não use intervalos curtos de polling.

Não considere SENT como prova de entrega nem SEALING como conclusão.

Faça download apenas pela rota autenticada; a URL temporária retornada deve ser tratada como segredo de curta duração.

Fluxo principal#

Significado dos estados#

Estados terminais#

Consulta recomendada#

Boas práticas#

Fluxo principal

Significado dos estados

Estados terminais

Consulta recomendada

Boas práticas