API de Assinatura para Contabilidade e Contadores

Poucos profissionais vivem o ICP-Brasil tão de perto quanto o contador. e-CNPJ, e-CPF, certificados A1 e A3 já fazem parte da rotina de quem transmite declarações, emite guias e representa clientes perante a Receita. Uma API de assinatura para contabilidade leva essa fluência ao próximo nível: permite que o escritório envie contratos contábeis, procurações e documentos com e-CNPJ para assinatura em escala, diretamente do seu sistema, sem reuploads manuais e sem perder a trilha de auditoria.

Este guia é voltado a desenvolvedores e líderes técnicos de escritórios contábeis, fintechs de contabilidade e softwares de gestão contábil (ERPs contábeis) que precisam embutir assinatura digital nativa ICP-Brasil em seus fluxos. Vamos cobrir os tipos de documento, o tratamento de certificados e-CNPJ, o envio de lotes de documentos de clientes e a prova jurídica de cada assinatura.

A SignDocs Brasil é uma plataforma de assinatura nativa em ICP-Brasil, com API REST, SDKs oficiais e foco em LGPD. Se você ainda está mapeando o terreno, comece pela visão geral da API de assinatura digital e volte aqui para o recorte contábil.

Que documentos o escritório contábil assina com a API

A demanda de assinatura de um escritório de contabilidade é alta, recorrente e heterogênea. Em um mesmo dia, o time pode precisar coletar a assinatura de centenas de clientes em documentos completamente diferentes. A API cobre toda essa variedade:

• Contratos de prestação de serviços contábeis: o documento que formaliza o honorário e o escopo entre escritório e cliente, geralmente assinado por ambas as partes.
• Procurações e termos de representação: instrumentos que autorizam o contador a representar o cliente perante a Receita Federal, juntas comerciais, prefeituras e órgãos de classe.
• Distratos e aditivos contratuais: alterações de honorário, mudança de regime tributário ou encerramento da relação.
• Guias, declarações e documentos com e-CNPJ: documentos em que o próprio escritório assina como pessoa jurídica usando seu e-CNPJ.
• Termos de ciência e autorizações LGPD: consentimentos para tratamento de dados fiscais e financeiros dos clientes.
• Balancetes, demonstrações e relatórios gerenciais: entregas periódicas que o cliente assina como aceite formal.

O ponto comum é que esses documentos exigem prova robusta de autoria e integridade. Para os de maior formalidade — contratos e procurações — o caminho natural é a assinatura com certificado ICP-Brasil. Para entregas mais leves e de alto volume, perfis de assinatura eletrônica com autenticação por OTP reduzem a fricção. A boa notícia é que a mesma API atende aos dois cenários; basta escolher o nível de assinatura. Vale entender em detalhe os níveis de assinatura qualificada, avançada e simples antes de decidir o perfil de cada fluxo.

ICP-Brasil nativo: e-CNPJ, e-CPF, A1 e A3

O diferencial de uma API pensada para contabilidade é tratar o certificado digital como cidadão de primeira classe, não como um anexo opcional. Contadores já operam com:

• e-CNPJ: certificado da pessoa jurídica, vinculado ao responsável legal do CNPJ. É o que o escritório usa para assinar como entidade.
• e-CPF: certificado da pessoa física do contador ou do cliente, usado quando a assinatura precisa identificar o indivíduo.
• A1 (arquivo): certificado armazenado em arquivo no computador ou servidor, válido por um ano, ideal para automações e assinatura no servidor.
• A3 (hardware): certificado em token USB ou cartão inteligente, com chave privada que nunca sai do dispositivo, válido por até três anos.

Na API SignDocs, você seleciona a assinatura por certificado ICP-Brasil definindo o perfil de assinatura como DIGITAL_CERTIFICATE. Esse perfil cobre tanto e-CNPJ quanto e-CPF na modalidade A1 — o formato adequado a integrações e automações, com um protocolo de duas fases em que a chave privada nunca sai do lado do titular. Para quem só possui certificado A3 (token ou cartão), o aplicativo SignDocs oferece o assinador desktop (Windows/macOS/Linux), que conversa diretamente com o middleware PKCS#11. A classe do certificado utilizada fica registrada no resultado da assinatura, para fins de auditoria.

Como o e-CNPJ é tratado na assinatura

Quando o escritório assina um documento com o e-CNPJ, a SignDocs verifica que o certificado é válido, está dentro do prazo, encadeia até uma Autoridade Certificadora confiável do ICP-Brasil e não foi revogado. A assinatura é gerada localmente, no aplicativo ou no assinador do titular, de modo que a chave privada do e-CNPJ nunca trafega pela rede. O resultado é incorporado ao PDF no padrão PAdES, no nível baseline (PAdES-B), com a cadeia de certificados ICP-Brasil, carimbo de hora do servidor e trilha de auditoria append-only — preservando o registro da assinatura no momento em que foi feita, com verificação pública em verificador.signdocs.com.br. O carimbo de tempo de uma ACT (TSA) e a validação de longo prazo (LTV), níveis PAdES-B-T/B-LT/B-LTA, não são emitidos atualmente pela API.

O próprio e-CNPJ carrega, por padrão ICP-Brasil, os dois níveis de identidade: a pessoa jurídica (CNPJ e razão social) e o responsável legal vinculado ao certificado. Esses atributos ficam preservados no resultado da assinatura e no evidence pack, documentando tanto que o escritório assinou quanto qual representante é o titular do certificado — uma necessidade comum em procurações e contratos contábeis. Para os detalhes de como o container criptográfico é montado, consulte o aprofundamento sobre PKCS#7, CMS, PAdES e CAdES.

Autenticação da API e primeiros passos

A integração começa pela autenticação. A SignDocs usa OAuth2 client-credentials: o sistema do escritório troca um par client id/secret por um token bearer de curta duração, que acompanha todas as chamadas seguintes. O token é um JWT assinado com ECDSA (ES256), expira em 15 minutos e tem as chaves protegidas em KMS.

O host api-hml.signdocs.com.br é o ambiente de homologação (sandbox), onde você valida toda a integração sem custo. Atenção: as entidades criadas em homologação têm TTL de 7 dias, então não dependa delas para guardar histórico. Para o passo a passo completo do handshake, dos escopos e da renovação do token, veja o guia de autenticação OAuth2 da API de assinatura. Escritórios em setores regulados ou que operam integrações com bancos podem ainda adicionar mTLS sobre o OAuth2.

Fluxo: enviar um lote de documentos de clientes para assinatura

O caso de uso mais valioso para um escritório contábil é o envio em lote. Imagine o início do ano: você precisa coletar a assinatura de cada cliente no novo contrato de honorários, ou enviar a procuração de renovação para 300 empresas. Fazer isso manualmente, um a um, no painel, é inviável. Com a API, o fluxo se resume a iterar sobre a lista de clientes reaproveitando o mesmo token.

Há duas formas de criar cada documento, e a escolha depende de como você quer entregar o link:

• Transaction API: cria um envelope com múltiplos signatários, lifecycle completo e suporte a ordem de assinatura. Ideal quando o documento tem mais de uma parte (escritório + cliente).
• Assinatura Expressa (Signing Sessions): uma única chamada a POST /v1/signing-sessions devolve um checkout hospedado ou widget embutido. Ideal para o cenário de um signatário por documento e entrega rápida do link.

O passo a passo do lote, conceitualmente:

1. Autentique uma vez e guarde o token bearer em memória.
2. Para cada cliente, monte o documento (PDF do contrato ou procuração) com os dados já preenchidos.
3. Crie uma transação ou sessão de assinatura, definindo o signatário, o perfil de assinatura (DIGITAL_CERTIFICATE para ICP-Brasil ou um perfil com OTP) e um metadata.client_id para correlacionar com o seu sistema.
4. Capture o link de assinatura retornado e entregue por e-mail, WhatsApp ou pelo seu portal.
5. Acompanhe o progresso por webhooks — não por consultas em loop.

Veja a criação de uma sessão de Assinatura Expressa dentro do laço de lote — com owner definido, a própria SignDocs envia o convite por e-mail a cada cliente:

Cada chamada cria uma sessão (e sua transação) independente, o que dá acompanhamento granular: você sabe exatamente quem já assinou. Para escritórios com grande volume, enfileire as criações com controle de concorrência, envie um X-Idempotency-Key por cliente (retries não duplicam) e respeite os limites de taxa — o ciclo completo está no guia de fluxo transacional da API.

Alternativa: Assinatura Expressa em lote

Quando cada documento tem um único signatário (o cliente), a Assinatura Expressa simplifica ainda mais. Uma chamada e você recebe a URL pronta:

Acompanhamento do lote com webhooks

Com centenas de documentos em circulação, consultar o status de cada um em loop é insustentável. A forma correta de acompanhar é por webhooks: você registra uma URL e a SignDocs notifica seu sistema sempre que algo acontece. Cada webhook chega como HTTP POST com assinatura HMAC-SHA256 no header, deduplicação pelo id do evento e retry com backoff exponencial em caso de falha.

Combinando o metadata.client_id que você gravou na criação com o evento recebido, é trivial reconciliar o estado de cada cliente no seu sistema. Para a arquitetura completa de recepção segura — verificação HMAC, fila de processamento e estratégia de retry — veja o guia de webhooks e eventos da API de assinatura.

Trilha de auditoria e prova jurídica

Para contabilidade, prova vale ouro. Cada transação na SignDocs gera uma trilha de auditoria completa que registra, para cada etapa: data e hora, endereço IP, geolocalização quando disponível, método de autenticação usado e os dados do certificado quando a assinatura é digital.

Ao concluir, a plataforma produz um pacote de evidências (evidence pack) no formato .p7m, um container PKCS#7/CMS que consolida o documento original, todas as assinaturas e os metadados de prova em um único arquivo verificável. Esse pacote é o que você guarda junto à documentação fiscal do cliente para qualquer eventual contestação. Qualquer parte pode conferir a validade no verificador público, sem precisar de conta nem de software proprietário.

Integração com software contábil e ERPs

A assinatura não é um fim em si: ela precisa estar acoplada ao sistema onde o escritório já trabalha. A SignDocs oferece SDKs oficiais que cobrem as linguagens mais comuns em backends de software contábil:

Não há SDK para Ruby — nesse caso, use a API REST diretamente via cliente HTTP. Independentemente da linguagem, o ciclo de integração é o mesmo: o seu sistema cria o documento, recebe o status por webhooks e baixa o PDF assinado para arquivar. Esse padrão é idêntico ao usado em outros setores que dependem de assinatura embutida, como mostram nossos guias para jurídico e advocacia, RH e admissão digital e imobiliárias e contratos de locação.

Como a SignDocs roda em infraestrutura multirregião na AWS (sa-east-1 e us-east-1) com postura LGPD-first, o escritório tem alta disponibilidade sem abrir mão da conformidade com a lei brasileira de proteção de dados — algo essencial quando se manipula informação fiscal e financeira sensível dos clientes.

Boas práticas para o escritório contábil integrador

• Escolha o nível de assinatura por documento, não por padrão único. Procurações e contratos pedem ICP-Brasil; aceites de relatório podem usar OTP. Defina isso por tipo de fluxo.
• Grave sempre o metadata.client_id. É a chave que correlaciona a transação com o cadastro no seu sistema e simplifica toda a reconciliação por webhook.
• Valide tudo em homologação primeiro. Use api-hml.signdocs.com.br, lembrando do TTL de 7 dias das entidades de teste.
• Arquive o evidence pack .p7m, não só o PDF. O pacote de evidências é a prova completa para uma eventual contestação fiscal ou cível.
• Não faça polling de status. Configure webhooks; use uma reconciliação periódica apenas como rede de segurança.
• Reaproveite o token OAuth2. Em lotes grandes, autentique uma vez e renove o token só quando expirar, evitando estourar limites de taxa.