Como funciona uma API de assinatura eletrônica: webhooks e trilha de evidências

Compartilhar:

Neste artigo

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

CasoO que o sistema faz pela APIGanho
Contratos de adesão e renovaçãoGera o documento por modelo e dispara para milhares de clientesEscala sem operador
Crédito e cessãoCria a operação, anexa contrato, termos e títulos, assina em lotePrazo de formalização menor
RHAdmissão, aditivos, políticas internasSem papel nem courier
FornecedoresContratos e termos de confidencialidade a partir do cadastroRastreabilidade por fornecedor
Aprovações internasFluxo sequencial com aprovador antes da parteOrdem garantida pelo sistema

Arquitetura típica

  1. Autenticação: token de integração por conta, guardado como segredo no servidor e nunca no front-end.
  2. 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.
  3. Envio: a plataforma notifica os signatários por e-mail ou WhatsApp.
  4. Eventos: a cada mudança (assinou, recusou, expirou, concluiu), a plataforma chama o webhook do seu sistema.
  5. Conclusão: o sistema baixa o documento final e o manifesto de evidências e grava os dois junto ao registro interno.
  6. 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áticaPor quê
Responder 2xx rápido e processar em filaEvita timeout e reenvio desnecessário
Idempotência pelo id do eventoO mesmo evento pode chegar mais de uma vez
Não depender da ordem de chegadaUse 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 consultaRecupera eventos perdidos por falha de rede
Log com o id do envelope e o id internoAuditoria 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

EtapaEntregávelCritério de pronto
1. DesenhoMapa de documentos, signatários, tipos de assinatura e eventosAprovado por jurídico e operação
2. HomologaçãoCriação, envio, webhook e download funcionando com dados fictíciosCenários de recusa, expiração e reenvio testados
3. PilotoUma linha de produto em produçãoTaxa de conclusão e erros medidos
4. EscalaDemais fluxos, com conciliação diária e alertasNenhum 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 chamaResultado esperado
1Autenticar com o token de integraçãoSeu servidorSessão válida
2Criar envelope/operação com o id internoSeu servidorId do envelope
3Anexar documentosSeu servidorDocumentos com hash
4Incluir signatários, papéis, ordem e tipo de assinaturaSeu servidorFluxo montado
5EnviarSeu servidorNotificações disparadas
6Eventos de assinaturaPlataforma → webhookStatus atualizado
7Envelope concluídoPlataforma → webhookGatilho para download
8Baixar documento final e manifestoSeu servidorArquivos gravados com o id interno
9Conciliar pendentesRotina diáriaNenhum status divergente

Estados de um envelope

EstadoPróximos estados possíveisAção do seu sistema
CriadoEnviado, canceladoNenhuma
EnviadoParcialmente assinado, recusado, expiradoExibir “aguardando assinatura”
Parcialmente assinadoConcluído, recusado, expiradoAtualizar quem falta
Concluído— (final)Baixar e arquivar evidências
Recusado— (final)Abrir tratamento manual
ExpiradoReenviadoDecidir 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árioResultado esperado
Envelope com 1 signatário e 1 documentoConcluído, evidências baixadas
Lote com 3 documentos para 1 signatárioUma única assinatura cobre o lote
Fluxo sequencial com aprovadorO cliente só recebe após a aprovação
Recusa do signatárioEstado “recusado” e tratamento aberto
ExpiraçãoEstado “expirado” e decisão de reenvio
Webhook fora do ar por 1 horaConciliação recupera os eventos
Evento duplicadoProcessado uma única vez
Documento com ICP-BrasilAssinatura qualificada registrada [S1][S2]

Monitoramento em produção

IndicadorAlerta sugerido
Webhooks com erroMais de 1% em 1 hora
Envelopes sem evento há mais de X diasLista diária para a operação
Divergências na conciliaçãoQualquer divergência
Tempo de resposta da APIAcima 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):

ItemCálculoResultado
Horas manuais por mês1.500 × 4 min ÷ 60100 horas
Custo por hora da equipe (exemplo)—R$ 45,00
Custo mensal do processo manual100 × 45R$ 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

PapelResponsabilidade
JurídicoMatriz documento × tipo de assinatura e política de evidências
Produto/operaçãoFluxos, signatários, prazos e lembretes
EngenhariaChamadas, webhooks, fila, conciliação e monitoramento
Segurança e privacidadeGuarda do token, minimização de dados e retenção (LGPD) [S3]
SuporteTratamento 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

Demonstração

Veja a Flixsign aplicada à sua operação

Mostramos o fluxo com o volume, os documentos e os signatários que você já usa, com respostas sobre ICP-Brasil, lastro e integração.

  • Padrão ICP-Brasil
  • Com ou sem certificado digital
  • API e webhooks
Agendar demonstração Ver soluções por segmento

Leva dois minutos. Retornamos pelo canal que você preferir.

Escrito por

Rodrigo Matioli · CRO da Flixsign

Rodrigo Matioli é CRO da Flixsign, plataforma de formalização e assinatura de operações de crédito para FIDCs, securitizadoras e factorings. Tem 4 anos de mercado em tecnologia para crédito e assinatura digital. Antes da Flixsign, liderou vendas e desenvolvimento de negócios e foi CRO em empresas do setor.

Mulher de óculos sorrindo enquanto usa um notebook

Agende uma reunião pelo WhatsApp.

Fale com um de nossos especialistas.