Webhooks Certyneo: automatizar o balanço contábil em ERP

Quando um documento é assinado eletronicamente via Certyneo, o que acontece depois em sua cadeia contábil? Para a maioria das empresas, a resposta ainda é frequentemente: nada automatizado. Um colaborador baixa manualmente o PDF assinado, envia por e-mail ao contador, que o redigita em seu software de gestão. Este processo fragmentado gera erros, atrasos e perda de rastreabilidade incompatível com as exigências de um balanço contábil confiável. Os webhooks Certyneo respondem precisamente a esta problematização: permitem disparar automaticamente ações em seus sistemas terceirizados — ERP, software contábil, GED — assim que um evento de assinatura ocorre. Este artigo explica em detalhes como configurar e explorar esses webhooks para fluidificar seu ciclo contábil de ponta a ponta.

O que é um webhook e por que é essencial para a contabilidade

O princípio do webhook explicado simplesmente

Um webhook é um mecanismo de notificação HTTP em tempo real: em vez de perguntar regularmente a uma API "algo mudou?" (abordagem chamada polling), é a aplicação emissora — aqui Certyneo — que envia uma requisição HTTP POST para uma URL de sua escolha assim que um evento específico ocorre. Em contabilidade, isso significa que no momento exato em que uma ordem de compra, um contrato de fornecedor ou uma nota de despesa é assinada eletronicamente, seu ERP pode ser instantaneamente notificado, sem intervenção humana.

Ao contrário de uma simples exportação CSV ou de um relatório mensal, o webhook garante uma sincronização quase em tempo real dos dados. Para um contador gerenciando encerramentos mensais ou trimestrais, essa granularidade é determinante: os documentos justificativos estão disponíveis no sistema assim que são assinados, e não no final do mês durante uma recuperação trabalhosa.

Os eventos Certyneo que disparam um balanço contábil

Certyneo expõe vários tipos de eventos via webhooks, diretamente exploráveis em um contexto contábil:

• `envelope.completed`: todas as partes assinaram o documento — este é o disparador principal para injetar um documento justificativo em seu ERP.
• `envelope.declined`: um signatário recusou — útil para alertar o departamento contábil de uma fatura contestada.
• `envelope.expired`: o prazo de assinatura foi excedido — permite reiniciar um procedimento e evitar uma lacuna na contabilidade.
• `signer.signed`: assinatura parcial de uma parte — pertinente para contratos com múltiplos signatários (ex.: contrato de aluguel que requer assinatura do proprietário e do inquilino).

Cada payload JSON enviado por Certyneo contém os metadados essenciais: identificador do documento, carimbo de data/hora qualificado, nomes dos signatários, URL segura para baixar o PDF assinado e a trilha de auditoria. Esses dados estruturados são diretamente exploráveis por um ERP ou software contábil.

Configuração passo a passo dos webhooks Certyneo para um ERP

Criar e registrar um endpoint webhook

A configuração de um webhook Certyneo é feita no painel, seção Configurações > Integrações > Webhooks. Aqui estão os passos-chave:

1. Definir a URL de destino: é o endpoint exposto por seu ERP ou sua ferramenta de integração middleware (ex.: um endpoint dedicado em SAP, Sage, Cegid ou uma ferramenta iPaaS como n8n, Make ou Zapier).
2. Selecionar os eventos a escutar: para um balanço contábil, priorize no mínimo `envelope.completed` e `envelope.declined`.
3. Configurar o segredo de assinatura HMAC: Certyneo assina cada payload com uma chave secreta que você define. Seu endpoint deve verificar essa assinatura para garantir a autenticidade das notificações — passo de segurança não negociável.
4. Testar com o modo simulação: Certyneo permite enviar um payload de teste sem criar um documento real. Verifique se seu endpoint responde bem com HTTP 200.

Mapear os dados do payload para seu plano contábil

Uma vez que o endpoint esteja operacional, é necessário mapear os campos do payload Certyneo para os campos esperados por seu ERP. Aqui está um exemplo de lógica de mapeamento para um contrato de fornecedor:

```json { "event": "envelope.completed", "envelope_id": "env_01HX...", "completed_at": "2026-05-26T14:32:00Z", "document_url": "https://app.certyneo.com/documents/signed/...", "metadata": { "type": "contrat_fournisseur", "montant_ht": 12500, "compte_comptable": "607", "fournisseur_id": "F-2891" } } ```

O campo `metadata` é livremente configurável ao criar o envelope via API Certyneo. Esta é a chave para enriquecer cada assinatura com os dados de negócio necessários para a contabilização automática: número de conta, centro de custo, exercício contábil, etc. Para aprofundar as possibilidades de integração técnica, consulte o centro de ajuda Certyneo que lista toda a documentação da API.

Gerenciar rejeições e relançamentos automáticos

Um webhook pode falhar se seu endpoint estiver temporariamente indisponível. Certyneo implementa uma política de retry exponencial: em caso de ausência de resposta HTTP 2xx, o sistema retenta o envio em intervalos crescentes (5 min, 30 min, 2 h, 24 h) durante uma janela de 72 horas. Além disso, o webhook é marcado como falho e um alerta é elevado no painel.

Para a contabilidade, essa resiliência é crucial: um documento justificativo não recebido no ERP pode gerar uma discrepância de balanço. Portanto, é recomendado complementar o mecanismo webhook com um job de reconciliação diário que interrogue a API Certyneo para listar os envelopes concluídos nas últimas 24 horas e verificar sua presença no sistema contábil.

Integração com os principais ERPs e softwares contábeis

Conexão nativa com Cegid, Sage e Pennylane

Vários editores de softwares contábeis populares na França oferecem conectores ou APIs REST compatíveis com webhooks Certyneo. Aqui estão os padrões de integração mais comuns:

Cegid XRP Flex: expõe uma API REST permitindo criar pièces contábeis e anexar arquivos. O webhook `envelope.completed` dispara uma chamada POST para a API Cegid para criar a escritura e anexar o PDF assinado como justificativo numérico.

Sage 100cloud / Sage 50: a abordagem recomendada passa por um middleware leve (script Python ou Node.js hospedado em serverless) que recebe o webhook Certyneo, baixa o documento via URL segura e o deposita na pasta de importação automática do Sage.

Pennylane: solução cloud nativa cuja API aceita diretamente documentos em PJ com seus metadados contábeis. A integração webhook-Pennylane é particularmente adequada para escritórios de contadores que centralizam pièces de vários clientes — um caso de uso que detalhamos na seção de cenários.

Para as equipes que avaliam diferentes soluções antes de migrar para Certyneo, o comparativo das soluções de assinatura eletrônica oferece uma visão detalhada das capacidades de integração por plataforma.

Usar um iPaaS como Make ou n8n para não-desenvolvedores

Se sua organização não possui uma equipe técnica dedicada, as plataformas de automação sem código/baixo código (Make, n8n, Zapier) constituem uma alternativa eficaz. O princípio é simples:

1. Crie um cenário com um trigger webhook em Make ou n8n — a URL gerada serve como endpoint Certyneo.
2. Configure as ações seguintes: download do documento assinado, análise dos metadados, envio para Google Drive / SharePoint, criação de uma linha em uma planilha de acompanhamento, notificação Slack ao responsável contábil.
3. Opcionalmente, dispare uma chamada API para seu software contábil para criar a escritura.

Esta abordagem permite atingir um alto nível de automação em menos de um dia, sem escrever uma única linha de código. É particularmente relevante para PME/TPE ou para contadores que desejam automatizar a coleta de pièces para seus clientes sem mobilizar um desenvolvedor.

Boas práticas de segurança e auditoria para webhooks contábeis

Verificação de assinaturas HMAC e segurança de endpoints

Em um contexto contábil, a confiabilidade dos dados recebidos via webhook é crítica. Um invasor que conseguisse injetar falsos eventos `envelope.completed` poderia corromper sua contabilidade. Três medidas de segurança se impõem:

• Verificação HMAC-SHA256: cada requisição Certyneo inclui um header `X-Certyneo-Signature`. Seu endpoint deve recalcular a assinatura com sua chave secreta e comparar — rejeite qualquer requisição cuja assinatura não corresponda.
• Validação do esquema JSON: antes de qualquer processamento, valide a estrutura e os tipos do payload recebido. Um campo `montant_ht` com valor `null` ou negativo deve disparar um alerta, não uma escritura contábil incorreta.
• Registros imutáveis: mantenha cada payload recebido em um registro com data/hora e não modificável por pelo menos 10 anos, em conformidade com as obrigações de conservação de pièces contábeis (artigo L123-22 do Código de Comércio).

Rastreabilidade e trilha de auditoria para o contador

Uma das principais vantagens da abordagem webhook é a rastreabilidade ponta a ponta que ela gera. Certyneo produz para cada documento assinado uma trilha de auditoria (audit trail) em conformidade com os requisitos eIDAS, incluindo carimbo de data/hora qualificado, endereços IP dos signatários e certificados utilizados.

Ao associar essa trilha de auditoria ao payload webhook, seu ERP pode armazenar não apenas a pièce justificativa mas também a prova de sua validade legal. Para um auditor independente ou um contador, essa dupla camada — documento + prova — simplifica consideravelmente as verificações durante uma auditoria ou revisão. O assinatura eletrônica em empresa detalha os níveis de assinatura e seu valor probante em diferentes contextos de negócio.

Para calcular o retorno sobre investimento dessa automação antes de começar, o calculador ROI de Certyneo permite estimar com precisão os ganhos de tempo e custos de acordo com seu volume de documentos assinados.

Marco legal aplicável aos webhooks e contabilidade digital

A automatização da cadeia contábil via webhooks de assinatura eletrônica inscreve-se em um marco regulatório preciso que é necessário dominar.

Regulamento eIDAS n°910/2014 (e sua revisão eIDAS 2.0): o regulamento europeu sobre identificação eletrônica e serviços de confiança estabelece o valor legal das assinaturas eletrônicas. O artigo 25 dispõe que uma assinatura eletrônica não pode ver recusados seus efeitos legais apenas pelo fato de se apresentar sob forma eletrônica. As assinaturas qualificadas (QES) gozam de uma presunção de confiabilidade equivalente à assinatura manuscrita. Para pièces contábeis, o nível apropriado de assinatura depende da natureza do documento: uma fatura simples pode recorrer a uma assinatura avançada (AES), enquanto um contrato de aluguel de equipamento ou um ato notarial eletrônico requer uma assinatura qualificada.

Código Civil, artigos 1366 e 1367: o artigo 1366 reconhece a escrita eletrônica como prova do mesmo modo que a escrita em suporte papel, sob reserva de que possa ser devidamente identificada a pessoa de cuja parte emana e que seja estabelecida e conservada em condições de natureza a garantir sua integridade. O artigo 1367 define a assinatura eletrônica como o uso de um processo confiável de identificação garantindo a ligação com o ato ao qual se liga. O webhook Certyneo, ao transmitir a trilha de auditoria com cada documento assinado, satisfaz essa exigência de identificação e integridade.

Artigo L123-22 do Código de Comércio: os documentos contábeis e as pièces justificativas devem ser conservados durante dez anos. Os documentos recebidos via webhook e armazenados em um ERP devem, portanto, ser submetidos a uma política de conservação em conformidade, incluindo a imutabilidade e legibilidade a longo prazo dos formatos (PDF/A recomendado pela norma ISO 19005).

RGPD n°2016/679: os payloads webhook contêm dados pessoais (nomes dos signatários, endereços de e-mail, carimbos de data/hora ligados a indivíduos). Seu endpoint e seu ERP são destinatários desses dados — você é responsável pelo tratamento ou co-responsável de acordo com as modalidades contratuais com Certyneo. O DPA (Acordo de Processamento de Dados) deve ser formalizado. Os dados transmitidos devem ser minimizados ao estritamente necessário para a finalidade contábil.

Diretiva NIS2 (2022/2555): para as empresas inseridas no perímetro NIS2 (operadores de serviços essenciais, entidades importantes), a segurança das interfaces API e webhooks constitui uma medida obrigatória de segurança de rede. A verificação HMAC, a criptografia TLS 1.3 mínimo e o registro de acessos se impõem.

Norma ETSI EN 319 132: define o formato XAdES para assinaturas eletrônicas avançadas. As assinaturas produzidas por Certyneo respeitam essas normas ETSI, garantindo sua interoperabilidade com sistemas de arquivamento com valor probante em conformidade com o referencial geral de segurança (RGS) francês.

Cenários de uso concretos

Cenário 1: um escritório de contadoria gerenciando 40 dossiers clientes

Um escritório de contadoria de dez colaboradores gerencia as cartas de contrato, mandatos SEPA e contas anuais de 40 sociedades clientes. Antes da integração dos webhooks Certyneo, cada documento assinado era recuperado manualmente por um gestor de dossier, renomeado de acordo com uma convenção de nomenclatura, depois depositado na pasta cliente do software de produção contábil. Este processo representava cerca de 15 a 20 minutos por documento, ou seja, várias horas por semana em período de enceramento.

Após a configuração de um webhook `envelope.completed` conectado à sua ferramenta de GED via Make, o escritório automatizou a integridade dessa cadeia: assim que a assinatura ocorre, o PDF assinado é automaticamente classificado na pasta cliente correspondente com o nome de arquivo correto, uma notificação é enviada ao gestor concernido, e uma linha é criada no quadro de acompanhamento de pièces recebidas. O ganho de tempo estimado é da ordem de 70 a 80% nessa tarefa, ou seja, aproximadamente 6 a 8 horas recuperadas por semana em período de balanço — um número coerente com os benchmarks publicados pelo Conselho da Profissão Contábil em seus relatórios sobre transformação digital dos escritórios.

Cenário 2: uma PME industrial com um ERP Sage e 300 contratos de fornecedor anuais

Uma PME do setor industrial assina aproximadamente 300 contratos de fornecedor por ano (ordens abertas, aditamentos, acordos de confidencialidade). Cada contrato assinado deve ser anexado a uma ficha de fornecedor em Sage 100cloud e arquivado como justificativo de compromisso. Sem automação, o departamento de compras transmitia os contratos assinados por e-mail ao departamento contábil com uma demora média de 3 a 5 dias úteis.

Após implantação de um middleware Node.js recebendo os webhooks Certyneo e chamando a API Sage, o tempo de anexação caiu para alguns segundos. Os compromissos fora do balanço agora são contabilizados em tempo real, o que permitiu melhorar a confiabilidade das situações intermediárias apresentadas ao CFO. O projeto foi realizado em menos de duas semanas por um desenvolvedor interno, apoiando-se na documentação webhook do centro de ajuda Certyneo.

Cenário 3: um grupo de sociedades gerenciando fluxos intercompanhias complexos

Um grupo constituído de uma dúzia de filiais usa Certyneo para assinar suas convenções de tesouraria intercompanhias e seus contratos de prestações intra-grupo. A consolidação contábil impõe que cada convenção assinada seja simultaneamente registrada no sistema da filial emissora e da filial receptora, com o mesmo identificador de documento para facilitar a eliminação dos fluxos recíprocos.

Ao configurar um webhook único que notifica em paralelo os endpoints das duas filiais concernidas (identificadas via metadados do envelope), o grupo eliminou as discrepâncias de consolidação ligadas a pièces faltantes ou mal referenciadas. O tempo de enceramento consolidado foi reduzido de 2 dias em média, o que representa um ganho significativo para uma direção financeira grupo que encerra trimestralmente. As equipes que consideram uma migração a partir de outra solução podem consultar o guia de migração para Certyneo para avaliar a viabilidade técnica.

Conclusão

Os webhooks Certyneo constituem uma alavanca de automação potente para qualquer ator que deseje integrar a assinatura eletrônica no coração de seu processo contábil. Ao eliminar as etapas manuais entre a assinatura de um documento e seu registro no ERP ou software contábil, reduzem os prazos, os erros de entrada e os riscos de pièces faltantes durante um balanço ou uma auditoria. Seja um escritório de contadoria, uma PME ou um grupo multi-entidades, a configuração webhook é acessível — com ou sem desenvolvedor — e o retorno sobre investimento é mensurável já nas primeiras semanas de utilização.

Para aprofundar, consulte o centro de ajuda Certyneo para acessar a documentação completa da API e dos webhooks. Pronto para automatizar seu balanço contábil? Crie sua conta Certyneo gratuitamente e conecte seus primeiros documentos assinados ao seu ERP hoje mesmo.