Como Migrar da API Clicksign para a SignDocs Brasil: Guia Prático
Trocar de API de assinatura parece cirurgia de coração aberto — o fluxo de contratos é crítico demais para "ver no que dá". A boa notícia: uma migração bem planejada é um projeto de dias, não meses, porque os conceitos centrais das duas plataformas se correspondem. Este guia entrega o mapa de conceitos, o plano em 6 etapas com rodagem paralela (zero downtime no seu fluxo) e uma estimativa honesta de esforço — incluindo os pontos em que os modelos divergem e você precisa decidir, não só traduzir.
Uma nota de honestidade antes de começar: a Clicksign é uma plataforma madura, e se a sua integração atual funciona bem e o custo faz sentido, migrar pode não ser prioridade. Este guia é para quem já decidiu — por preço, por ergonomia de API, por ICP-Brasil nativo ou por recursos — e quer o caminho mais curto e seguro. A comparação de plataformas está em API Clicksign vs SignDocs Brasil; aqui o assunto é execução.
O mapa de conceitos: o que vira o quê
Toda API de assinatura resolve os mesmos problemas: um documento, pessoas que assinam, um fluxo entre elas e eventos para o seu sistema reagir. A tabela traduz os conceitos gerais do modelo de envelopes para a superfície da SignDocs (para os nomes exatos do lado Clicksign, confira a documentação da sua versão de API — os conceitos se mantêm):
| Conceito na sua integração atual | Na SignDocs | Nota de migração |
|---|---|---|
| Documento/envelope criado por upload | POST /v1/signing-sessions (1 signatário) ou POST /v1/envelopes (vários) |
Documento vai em base64 (até 10 MB) na própria criação, ou por presigned URL |
| Signatário com método de autenticação | signer + policy.profile (CLICK_ONLY, CLICK_PLUS_OTP, BIOMETRIC, DIGITAL_CERTIFICATE) |
Um perfil por signatário — cada participante pode ter um nível diferente |
| Ordem de assinatura | signingMode (SEQUENTIAL/PARALLEL) + signerIndex por sessão |
A fila é imposta pela API no modo sequencial |
| Link/URL de assinatura | url + clientSecret → link final url?cs=... |
O segredo faz parte do link — trate-o como credencial |
| Notificação por e-mail | Automática quando o envio tem owner definido |
Ou distribua o link pelo seu canal (WhatsApp, portal) |
| Webhook de eventos | SIGNING_SESSION.COMPLETED, ENVELOPE.ALL_SIGNED, TRANSACTION.EXPIRED... |
Assinados com HMAC-SHA256; idempotência pelo id do evento |
| Download do assinado | GET /v1/transactions/{id}/download → URL temporária |
Evidências em /evidence (.p7m) — baixe e arquive os dois |
| Autenticação da API | OAuth2 client-credentials (POST /oauth2/token, token de 15 min) |
SDKs renovam o token sozinhos |
combined-stamp; (2) posicionamento visual por coordenadas não existe — a plataforma aplica a assinatura e registra o signatário na trilha de evidências; (3) templates de documento são seu lado da fronteira — seu sistema monta o PDF (com a biblioteca que preferir) e a API o assina. Se sua integração atual depende de algum desses três, planeje o redesenho dessas partes antes de estimar o prazo.
O plano em 6 etapas (com rodagem paralela)
Etapa 1 — Inventário da integração atual (meio dia)
Liste o que a sua integração realmente usa: endpoints chamados, eventos de webhook tratados, tipos de documento e de signatário, e — importante — os recursos específicos da plataforma de origem. O mapa acima diz o que tem tradução direta; o que não tiver entra numa lista de decisões, não de tarefas.
Etapa 2 — Sandbox de ponta a ponta (1 dia)
Gere credenciais de homologação e reproduza o seu fluxo principal contra api-hml.signdocs.com.br — sem custo, sem cartão, entidades com TTL de 7 dias. O guia de 5 minutos cobre da credencial à primeira assinatura; os nove passos completos cobrem o resto.
Etapa 3 — Adaptar o código (1–2 dias)
Com SDK oficial (Node, Python, PHP, Java, Go, C#), a autenticação e a tipagem vêm prontas. O padrão que funciona: uma interface SignatureProvider no seu código com as duas implementações atrás dela — a troca vira uma flag de configuração, e a rodagem paralela sai de graça.
Etapa 4 — Webhooks e reconciliação (1 dia)
Novo endpoint (ou o mesmo, com roteamento pela assinatura), verificação HMAC-SHA256 sobre {timestamp}.{corpo}, resposta 200 rápida e processamento assíncrono. Mapeie os eventos para os estados do seu domínio e mantenha um polling de reconciliação (GET /v1/transactions) como rede de segurança das primeiras semanas. Detalhes em webhooks e eventos.
Etapa 5 — Rodagem paralela em produção (1–2 semanas de calendário, pouco esforço)
Contrate produção (a API é um plano sob medida — o time comercial dimensiona pelo seu volume), aponte um segmento pequeno do tráfego para a SignDocs — um tipo de documento, um cliente piloto — e compare taxas de conclusão, tempos e eventos. Documentos novos nascem na plataforma nova; os em andamento terminam onde começaram. Nada é interrompido.
Etapa 6 — Corte e arquivamento (meio dia)
Flag virada para 100%, monitoração por um ciclo completo e, antes de encerrar o contrato antigo: exporte todos os PDFs assinados e os relatórios de evidência da plataforma anterior para o seu repositório. Documentos assinados lá continuam válidos — mas a guarda passa a ser sua.
O que você ganha (e o que deve conferir) do outro lado
- ICP-Brasil nativo: A1 no fluxo da API em todos os planos, A3 pelo assinador desktop — sem módulos adicionais.
- Assinatura Expressa: o caso "um documento, um signatário" em uma única chamada, sem orquestração de envelope.
- Evidence pack (.p7m): trilha de auditoria, hash e autenticações em container verificável de forma independente — confira no verificador público.
- Confira no seu caso: limites e cotas do seu contrato (dimensionados na proposta), os perfis de autenticação de que você precisa e — se usava recursos sem equivalente — as decisões da etapa 1.
Perguntas Frequentes
Quanto esforço leva migrar uma integração de assinatura eletrônica?
Para uma integração típica — criar documento, definir signatários, receber webhook de conclusão, baixar o assinado — a experiência mostra algo entre 2 e 5 dias de um desenvolvedor: um dia para reproduzir o fluxo no sandbox da SignDocs, um ou dois para adaptar o código (os SDKs oficiais em 6 linguagens eliminam boa parte), um para o receptor de webhooks e a verificação HMAC, e o restante para testes e a rodagem paralela. Integrações com posicionamento de campos, templates ou lógica própria em cima de recursos específicos da plataforma de origem exigem redesenho dessas partes e podem levar mais.
Preciso desligar a integração antiga para começar?
Não — e não deveria. O plano recomendado é a rodagem paralela: a integração nova nasce no sandbox da SignDocs (api-hml.signdocs.com.br, gratuito, sem cartão), sobe para produção atendendo uma fração do tráfego (um tipo de documento, um cliente piloto) e só assume tudo quando os números de conclusão e os webhooks se mostram estáveis. Documentos já assinados na plataforma anterior permanecem válidos lá — exporte os PDFs assinados e os relatórios de evidência antes de encerrar o contrato antigo.
Os documentos assinados na Clicksign continuam válidos depois da migração?
Sim. A validade jurídica de um documento assinado não depende da continuidade do seu contrato com a plataforma onde ele foi assinado — as evidências foram geradas no ato. O cuidado prático é de guarda: antes de encerrar a conta antiga, exporte todos os PDFs assinados e os respectivos relatórios/trilhas de evidência e arquive-os no seu repositório. Migração muda onde os novos documentos serão assinados; não reescreve o passado.
O que muda na autenticação da API?
A SignDocs usa OAuth2 client-credentials: sua aplicação troca client_id e client_secret por um bearer token de curta duração (15 minutos) em POST /oauth2/token, com corpo application/x-www-form-urlencoded. Se a sua integração atual usa um token estático de API, a mudança é adicionar a rotina de obtenção e renovação do token — ou deixar isso com o SDK oficial, que renova automaticamente. Tokens curtos reduzem o dano de um vazamento e são um dos requisitos comuns em auditorias de segurança.
Como migro os webhooks?
Registre seu endpoint na SignDocs e mapeie os eventos para a sua lógica atual: a conclusão de uma assinatura chega como SIGNING_SESSION.COMPLETED, a de todos os signatários de um envelope como ENVELOPE.ALL_SIGNED, expiração como TRANSACTION.EXPIRED, entre outros. Cada entrega é assinada com HMAC-SHA256 sobre timestamp e corpo — verifique a assinatura antes de processar e use o id do evento para idempotência. Durante a rodagem paralela, seu receptor atende os dois formatos lado a lado; ao final, remove-se o antigo.
E se eu usar recursos que não têm equivalente direto?
Mapeie antes de codar — é a etapa 1 do plano. A maioria dos fluxos (documento + signatários + ordem + webhook + download) tem equivalente direto. Diferenças de modelo aparecem em pontos específicos: na SignDocs, cada envelope carrega um documento (o consolidado sai via combined-stamp), o posicionamento visual do carimbo não é configurável por coordenadas, e a montagem do PDF a partir de template é feita no seu sistema antes do envio. Para cada recurso sem equivalente, a pergunta certa é se ele era essencial ou um contorno — e o time comercial ajuda a desenhar a alternativa antes de você escrever código.
Comece a migração pelo sandbox — hoje, sem custo
Gere credenciais de homologação, reproduza seu fluxo em api-hml.signdocs.com.br e valide webhooks e evidências antes de qualquer contrato. Quando estiver pronto, o time comercial dimensiona a produção pelo seu volume.
Criar credenciais de homologação Falar com o time comercial