Resumo. Uma API de assinatura eletrônica funciona assim: o seu sistema cria envelopes, envia documentos, define signatários e recebe o resultado sem ninguém operar uma tela. Por isso, este guia explica a arquitetura típica (REST, autenticação por token, webhooks), os casos de uso que mais geram ganho, como desenhar o tratamento de eventos sem perder status, quais evidências a integração deve guardar e um checklist técnico para avaliar fornecedores.
Revisão jurídica interna. Fontes ao final.
Quando a API compensa
Em geral, a integração compensa quando a assinatura faz parte de um processo que já roda em sistema (ERP, CRM, core de crédito, sistema de RH) e o volume torna o upload manual um gargalo. Sinais típicos:
- alguém exporta PDFs do sistema para subir em outra tela;
- o status da assinatura é conferido à mão e copiado de volta;
- há erro de digitação de signatário ou de documento;
- o processo precisa de evidência ligada a um identificador interno (contrato, operação, matrícula).
Casos de uso
| Caso | O que o sistema faz pela API | Ganho |
|---|---|---|
| Contratos de adesão e renovação | Gera o documento por modelo e dispara para milhares de clientes | Escala sem operador |
| Crédito e cessão | Cria a operação, anexa contrato, termos e títulos, assina em lote | Prazo de formalização menor |
| RH | Admissão, aditivos, políticas internas | Sem papel nem courier |
| Fornecedores | Contratos e termos de confidencialidade a partir do cadastro | Rastreabilidade por fornecedor |
| Aprovações internas | Fluxo sequencial com aprovador antes da parte | Ordem garantida pelo sistema |
Arquitetura típica
- Autenticação: token de integração por conta, guardado como segredo no servidor e nunca no front-end.
- Criação: o sistema cria o envelope ou a operação, envia documentos (base64 ou URL assinada) e define signatários, papéis, ordem e tipo de assinatura.
- Envio: a plataforma notifica os signatários por e-mail ou WhatsApp.
- Eventos: a cada mudança (assinou, recusou, expirou, concluiu), a plataforma chama o webhook do seu sistema.
- Conclusão: o sistema baixa o documento final e o manifesto de evidências e grava os dois junto ao registro interno.
- Conciliação: uma consulta periódica confere se algum evento foi perdido.
Na Flixsign, a API é REST com JSON e documentação OpenAPI, tem webhooks por evento, autenticação por token de integração, isolamento por conta e ambiente de homologação. Além do JSON, aceita a entrada por web service SOAP (XML, com WSDL) e por arquivo CNAB 444, e permite a assinatura em lote com ou sem ICP-Brasil [S4].
Webhooks sem perder status
Em resumo, webhook é uma chamada HTTP que a plataforma faz para o seu sistema quando algo acontece. Por exemplo, um corpo ilustrativo:
{
"evento": "envelope.finalizado",
"operacao": "CONTRATO-0412",
"documentos": 3,
"signatarios": [
{"papel": "cliente", "status": "assinado"},
{"papel": "empresa", "status": "assinado"}
],
"concluidoEm": "2026-10-14T14:32:07Z"
}
Além disso, há boas práticas válidas para qualquer fornecedor:
| Prática | Por quê |
|---|---|
| Responder 2xx rápido e processar em fila | Evita timeout e reenvio desnecessário |
| Idempotência pelo id do evento | O mesmo evento pode chegar mais de uma vez |
| Não depender da ordem de chegada | Use o timestamp e o estado final, não a sequência |
| Validar a origem (por exemplo, assinatura HMAC do payload com segredo compartilhado e checagem do timestamp contra replay, conforme o fornecedor) | Impede eventos forjados |
| Conciliação diária por consulta | Recupera eventos perdidos por falha de rede |
| Log com o id do envelope e o id interno | Auditoria e suporte |
Trilha de evidências na integração
A validade jurídica de assinaturas eletrônicas fora da ICP-Brasil depende de demonstrar autoria e integridade, e da aceitação pelas partes (MP 2.200-2/2001, artigo 10, § 2º). De fato, com certificado ICP-Brasil, há presunção de veracidade (artigo 10, § 1º) [S1]. A integração deve, portanto, preservar a evidência, e não só o PDF:
- documento final e o seu hash;
- manifesto com signatários, autenticação, data e hora, IP e dispositivo;
- vínculo entre o envelope e o id interno (contrato, operação);
- log de eventos recebidos pelo webhook;
- retenção e acesso compatíveis com a LGPD [S3].
Além disso, a classificação simples, avançada e qualificada da Lei 14.063/2020 (artigo 4º), aplicável às interações com entes públicos (artigo 2º), ajuda a definir, por tipo de documento, qual assinatura a API deve solicitar [S2].
Segurança
- Token em cofre de segredos e com rotação; nunca no código-fonte.
- HTTPS em todas as chamadas e no endpoint do webhook.
- Princípio do menor privilégio: um token por sistema ou ambiente.
- Ambiente de homologação separado de produção, com dados fictícios.
- Minimização de dados pessoais no payload (LGPD) [S3].
Checklist técnico para avaliar uma API de assinatura
- [ ] Documentação pública ou OpenAPI e ambiente de homologação
- [ ] Autenticação por token com escopo por conta
- [ ] Webhooks por evento, com reenvio e mecanismo de validação de origem
- [ ] Assinatura em lote por signatário
- [ ] Tipos de assinatura por documento, incluindo ICP-Brasil quando necessário
- [ ] Download do documento final e do manifesto de evidências
- [ ] Consulta de status para conciliação
- [ ] Formatos de entrada compatíveis com o seu sistema (JSON, XML ou arquivo)
- [ ] Limites de requisição documentados
- [ ] Suporte técnico na integração
Plano de integração em 4 etapas
| Etapa | Entregável | Critério de pronto |
|---|---|---|
| 1. Desenho | Mapa de documentos, signatários, tipos de assinatura e eventos | Aprovado por jurídico e operação |
| 2. Homologação | Criação, envio, webhook e download funcionando com dados fictícios | Cenários de recusa, expiração e reenvio testados |
| 3. Piloto | Uma linha de produto em produção | Taxa de conclusão e erros medidos |
| 4. Escala | Demais fluxos, com conciliação diária e alertas | Nenhum status divergente na conciliação |
Sequência de chamadas, do início ao fim
Exemplo ilustrativo e genérico. Não é a documentação da Flixsign. No entanto, os nomes de endpoints e campos reais estão na documentação OpenAPI do fornecedor [S4].
| # | Chamada (ilustrativa) | Quem chama | Resultado esperado |
|---|---|---|---|
| 1 | Autenticar com o token de integração | Seu servidor | Sessão válida |
| 2 | Criar envelope/operação com o id interno | Seu servidor | Id do envelope |
| 3 | Anexar documentos | Seu servidor | Documentos com hash |
| 4 | Incluir signatários, papéis, ordem e tipo de assinatura | Seu servidor | Fluxo montado |
| 5 | Enviar | Seu servidor | Notificações disparadas |
| 6 | Eventos de assinatura | Plataforma → webhook | Status atualizado |
| 7 | Envelope concluído | Plataforma → webhook | Gatilho para download |
| 8 | Baixar documento final e manifesto | Seu servidor | Arquivos gravados com o id interno |
| 9 | Conciliar pendentes | Rotina diária | Nenhum status divergente |
Estados de um envelope
| Estado | Próximos estados possíveis | Ação do seu sistema |
|---|---|---|
| Criado | Enviado, cancelado | Nenhuma |
| Enviado | Parcialmente assinado, recusado, expirado | Exibir “aguardando assinatura” |
| Parcialmente assinado | Concluído, recusado, expirado | Atualizar quem falta |
| Concluído | — (final) | Baixar e arquivar evidências |
| Recusado | — (final) | Abrir tratamento manual |
| Expirado | Reenviado | Decidir reenvio ou cancelamento |
| Cancelado | — (final) | Registrar motivo |
Modelar estados finais evita o erro mais comum: tratar um evento atrasado como se reabrisse um envelope já concluído.
Erros, novas tentativas e limites
- Erros 4xx (dados inválidos, falta de permissão): não repita a chamada sem corrigir. Registre e alerte.
- Erros 5xx e timeouts: repita com espera crescente (por exemplo, 1 s, 2 s, 4 s, 8 s) e limite de tentativas.
- Limite de requisições: respeite o limite documentado pelo fornecedor. Em envios em massa, use fila.
- Chave de idempotência na criação: evita envelope duplicado quando uma chamada é repetida após timeout.
Testes de homologação
| Cenário | Resultado esperado |
|---|---|
| Envelope com 1 signatário e 1 documento | Concluído, evidências baixadas |
| Lote com 3 documentos para 1 signatário | Uma única assinatura cobre o lote |
| Fluxo sequencial com aprovador | O cliente só recebe após a aprovação |
| Recusa do signatário | Estado “recusado” e tratamento aberto |
| Expiração | Estado “expirado” e decisão de reenvio |
| Webhook fora do ar por 1 hora | Conciliação recupera os eventos |
| Evento duplicado | Processado uma única vez |
| Documento com ICP-Brasil | Assinatura qualificada registrada [S1][S2] |
Monitoramento em produção
| Indicador | Alerta sugerido |
|---|---|
| Webhooks com erro | Mais de 1% em 1 hora |
| Envelopes sem evento há mais de X dias | Lista diária para a operação |
| Divergências na conciliação | Qualquer divergência |
| Tempo de resposta da API | Acima do padrão histórico |
Página de produto
Para conhecer os recursos de integração da Flixsign (REST/JSON, webhooks, SOAP/WSDL, CNAB 444 e ambiente de homologação), veja a página de integração da API da Flixsign [S4].
Quanto custa não integrar
Por fim, uma conta simples ajuda a decidir. Por exemplo, suponha 1.500 documentos por mês, com 4 minutos de trabalho manual cada (exportar o PDF, subir, conferir o signatário, acompanhar o status e copiar o resultado de volta):
| Item | Cálculo | Resultado |
|---|---|---|
| Horas manuais por mês | 1.500 × 4 min ÷ 60 | 100 horas |
| Custo por hora da equipe (exemplo) | — | R$ 45,00 |
| Custo mensal do processo manual | 100 × 45 | R$ 4.500,00 |
| Erros de digitação (exemplo: 2%) | 1.500 × 2% | 30 reenvios por mês |
Em seguida, compare esse custo com o esforço de integração e com o preço do plano. Porém, os números são ilustrativos: use os tempos medidos na sua operação.
Quem precisa estar no projeto
| Papel | Responsabilidade |
|---|---|
| Jurídico | Matriz documento × tipo de assinatura e política de evidências |
| Produto/operação | Fluxos, signatários, prazos e lembretes |
| Engenharia | Chamadas, webhooks, fila, conciliação e monitoramento |
| Segurança e privacidade | Guarda do token, minimização de dados e retenção (LGPD) [S3] |
| Suporte | Tratamento de recusas, expirações e dúvidas de signatários |
Perguntas frequentes
O que é uma API de assinatura eletrônica? É uma interface que permite ao seu sistema criar, enviar e acompanhar assinaturas eletrônicas por chamadas programáticas, sem operação manual.
Para que servem os webhooks? Para a plataforma avisar o seu sistema, em tempo real, quando um signatário assina, recusa ou quando o envelope é concluído.
A assinatura feita pela API tem a mesma validade? Sim, desde que o tipo de assinatura e as evidências sejam adequados ao documento. Assim, a validade depende do tipo de assinatura e das evidências, e não do canal de criação. A base é a MP 2.200-2/2001, artigo 10 [S1].
Posso integrar sem API REST? Na Flixsign, além do JSON pela API REST, há entrada por web service SOAP e por arquivo CNAB 444 [S4].
O que é idempotência em webhooks? É garantir que o mesmo evento, recebido mais de uma vez, produza o efeito uma única vez. Por isso, use o id do evento como chave.
Como testar uma integração sem afetar clientes reais? Use o ambiente de homologação com dados fictícios e rode todos os cenários de recusa, expiração e reenvio antes de ir para produção.
REST ou SOAP: qual escolher? Em geral, REST/JSON é o padrão em sistemas novos. No entanto, SOAP/XML ou arquivo são úteis quando o sistema de origem já trabalha nesses formatos. Na Flixsign, os três estão disponíveis [S4].
O que guardar depois da assinatura? O documento final, o hash, o manifesto de evidências, o log de eventos e o vínculo com o id interno.
Fontes
- [S1] Medida Provisória nº 2.200-2/2001, artigo 10
- [S2] Lei nº 14.063/2020, artigo 4º
- [S3] Lei nº 13.709/2018 (LGPD)
- [S4] Flixsign, Integração via API (recursos técnicos) (acesso em 29/10/2026)



