Como integrar assinatura digital ao ERP com API e webhook

O ERP continua conduzindo a operação

O cliente comercial não precisa trocar de sistema. O ERP gera o PDF, registra a operação e chama a CLP. O destinatário abre a página de assinatura com a marca da empresa, confirma o acesso por e-mail, lê e manifesta seu aceite. A CLP protege o conjunto final e comunica a conclusão.

A proteção institucional do PDF não é a assinatura pessoal ICP-Brasil de cada destinatário. Os aceites individuais compõem a evidência. A integração deve apresentar essa diferença com clareza ao usuário.

1. Prepare a empresa e o documento

Configure marca, remetente verificado, chave e webhook. Verifique a proteção disponível. Separe as credenciais por empresa e mantenha-as no servidor. Antes de enviar, grave o ID interno da operação, a chave idempotente, o hash SHA-256 do original e a lista autorizada de destinatários.

Uma análise opcional por IA pode apontar diferenças entre dados do ERP e o PDF. Ela não envia convites sozinha. O remetente revisa o resultado e autoriza o envio; não trate uma resposta da IA como aprovação jurídica.

2. Envie e entregue o acesso

Crie o envelope conforme os exemplos nas três linguagens. Guarde o ID CLP junto ao pedido. external_id ajuda na correlação, mas não substitui esse ID e não é filtro de busca implementado.

GET /v1/envelopes/{id}/signing-links fornece links privados para destinatários pendentes. Entregue cada link somente à pessoa correspondente; não registre o token em analytics, logs ou URL de redirecionamento. A recuperação desses links não desativa os convites automáticos nem remove a confirmação por e-mail.

Há até cinco destinatários em paralelo. Ordem sequencial, biometria e WhatsApp não fazem parte dessa versão.

3. Sincronize sem confundir aceite e conclusão

• sent: aguardando aceites.
• accepted: aceites concluídos, finalização ainda pendente.
• completed: conjunto final disponível.
• sealing_failed: falha de finalização; investigar antes de retomar.
• declined, canceled, expired ou purged: tratar o estado correspondente sem considerar o contrato concluído.

Use webhook autenticado para a conclusão e consultas espaçadas para conciliação. O limite técnico é 60 requisições por minuto por chave; distribua consultas em fila e evite atualizar todas as operações a cada segundo.

4. Exporte original, final e evidências

Depois de consultar um envelope completed, baixe GET /v1/envelopes/{id}/files/original, /files/final e /files/evidence. Calcule SHA-256 dos bytes de cada arquivo e compare com original_sha256, final_sha256 e evidence_sha256. Não normalize nem regrave o JSON de evidências antes de calcular seu hash.

Persista os arquivos no armazenamento privado do ERP e só então envie POST /v1/envelopes/{id}/delivery-receipts com esses três hashes. O recibo registra arquivamento; não exclui imediatamente os arquivos nem amplia a guarda. Não o envie apenas porque começou o download.

Os endpoints /files/{kind}/link podem retornar link temporário R2. Se direct=false, use o download autenticado. Nunca envie a chave CLP ao endereço R2. Links temporários não devem ser armazenados como endereço permanente do documento.

5. Trate guarda e falhas

Use retain_until como prazo efetivo. Os planos têm até um ano, dois anos ou vigência ativa, sujeitos à janela de exportação e ao limite já registrado no documento. O convite de sete dias é diferente do prazo de armazenamento. HTTP 410 indica indisponibilidade definitiva do recurso naquele fluxo.

Na falha de finalização, consulte error_code. POST /v1/envelopes/{id}/retry só se aplica ao estado sealing_failed; não crie outro envelope para tentar concluir o mesmo aceite. Mantenha uma fila de exceções visível à equipe e registre IDs e códigos, sem expor PDFs, senhas ou links privados.