Requisitos técnicos para integrar uma API de assinatura
A maior parte das perguntas sobre requisitos técnicos tem resposta curta e tranquilizadora: se a sua aplicação faz chamadas HTTP e entende JSON, ela já atende ao essencial. Não há SDK obrigatório, biblioteca proprietária, agente instalado nem linguagem exigida. Mas existem dois requisitos que costumam travar projetos na véspera porque não são de código e ninguém os levanta no começo: um endereço público para receber webhooks e o CPF ou CNPJ de cada signatário. Esta é a lista completa do que precisa existir antes da primeira chamada.
Resposta curta: se a sua aplicação faz requisições HTTPS e entende JSON, o requisito técnico está atendido. Os dois itens que realmente travam projetos não são de código — um endereço público para webhooks e o CPF ou CNPJ de cada signatário.
A lista
| Requisito | Obrigatório? | Observação |
|---|---|---|
| Cliente HTTP com HTTPS e JSON | Sim | Qualquer linguagem; sem SDK obrigatório |
| Lugar seguro para o segredo | Sim | Cofre ou variável de ambiente — nunca no repositório |
| Identificador estável por usuário | Sim | Vira a chave de tudo o que a pessoa assinar |
| CPF ou CNPJ de cada signatário | Sim | Em todos os perfis, inclusive os mais simples |
| Endpoint HTTPS público | Para produção | Recebe os webhooks |
| Onde guardar documento e evidência | Recomendado | URLs de download são de vida curta |
| Certificado ICP-Brasil | Não | Só quando o documento exige — e é do signatário |
O que não é exigido
Vale começar pelo que costuma preocupar sem motivo:
- Nenhum SDK obrigatório. A API é REST com JSON. Existem SDKs oficiais que poupam trabalho, e integrar direto contra os endpoints é igualmente suportado — inclusive com a vantagem de não depender da cadência de atualização de um pacote.
- Nenhuma linguagem, nuvem ou sistema operacional específico.
- Nenhum agente ou componente nativo para instalar. Não há dependência binária no seu servidor.
- Nenhum certificado do lado da sua aplicação para operar a API. Quando um documento exige assinatura com certificado ICP-Brasil, quem o possui é o signatário.
Os dois que travam projetos
1. CPF ou CNPJ de todo signatário
Este é o requisito que mais frequentemente aparece tarde, e ele não tem contorno técnico: é exigido em todos os perfis de verificação, do mais simples ao mais rigoroso. Não é uma regra de certificado digital — vale igualmente para uma assinatura por clique.
O problema prático é que bases de pessoas montadas para outros fins frequentemente não têm esse dado: uma lista de contatos de CRM, um cadastro de e-commerce, uma planilha comercial. Quando o signatário é alguém de fora — um fiador, o representante da outra parte, uma testemunha — o dado quase nunca existe, e a interface que coleta os dados do signatário precisa ter onde digitá-lo.
Não invente um valor de preenchimento. O número entra na evidência e a assinatura se vincula a ele; um número fabricado é prova falseada, e é pior do que a recusa. Se o dado não existe, o caminho é coletá-lo — não contorná-lo.
Vale levantar isso no primeiro dia, com uma consulta simples: quantos dos registros que vão assinar têm CPF ou CNPJ preenchido? A resposta define trabalho de enriquecimento que não aparece em nenhuma estimativa de integração.
2. Um endereço público para webhooks
Em produção, os webhooks são como a sua aplicação fica sabendo que alguém assinou. O requisito é um endereço HTTPS e acessível pela internet — o que costuma esbarrar em ambientes onde tudo é interno e expor um endpoint envolve pedido de rede, revisão de segurança e prazo.
Duas notas práticas. Em desenvolvimento, um túnel local resolve — o que não funciona é um endereço que só existe dentro da sua rede. E dá para integrar sem webhooks, consultando o status periodicamente: funciona em volume baixo, ao custo de requisições, atraso e consumo do seu limite de chamadas. Para qualquer volume relevante, a consulta periódica deixa de ser o mecanismo principal e passa a ser a reconciliação de segurança, que é o papel certo dela.
Os dois que parecem triviais e não são
O identificador de usuário
Toda assinatura exige um identificador do signatário no seu sistema. É um campo de texto livre, nada é validado — e ele se comporta como chave primária: agrupa o histórico da pessoa e endereça o cadastro biométrico dela.
Não existe operação de renomeação. Trocar o valor depois não migra nada; cria um segundo usuário, vazio, ao lado do primeiro. Escolher a chave primária imutável do seu banco, com um prefixo de origem, é uma decisão de dez minutos que evita um problema sem solução barata — detalhada em userExternalId: identificador estável.
Onde guardar o resultado
As URLs de download do documento assinado e da evidência são pré-assinadas e de vida curta. Guardar a URL não funciona — ela vira link quebrado em cerca de uma hora. Guarde o identificador e peça uma URL nova quando alguém for baixar, ou baixe o arquivo e armazene do seu lado se a sua política exige retenção própria.
Requisitos que aparecem conforme o perfil
| Se o seu fluxo usa… | Aparece o requisito de… |
|---|---|
| Código por e-mail ou SMS | Um canal de contato válido por signatário |
| Verificação biométrica | Câmera no dispositivo do signatário; imagem de referência ou documento oficial |
| Certificado ICP-Brasil | O signatário possuir o certificado |
| Assinatura dentro do seu app | Componente de captura e permissão de câmera, no modo em que você conduz |
| Documentos grandes | Capacidade de fazer um PUT direto para uma URL pré-assinada |
A última linha é fácil de atender e fácil de esquecer: acima de certo tamanho, o envio deixa de ser base64 no corpo da requisição e passa a ser um upload direto, como descrito em upload de documentos grandes.
Checklist antes da primeira chamada
- A aplicação faz HTTPS de saída e trata JSON.
- Existe um cofre para o segredo da credencial — e ele não vai para o repositório.
- Está escolhido qual campo do seu banco será o identificador do signatário, e ele é imutável.
- Foi verificado quantos registros têm CPF ou CNPJ, e há plano para os que não têm.
- Existe (ou está pedido) um endereço HTTPS público para webhooks.
- Está decidido onde documento e evidência serão guardados do seu lado.
- Se houver biometria ou certificado, os requisitos do signatário estão mapeados.
Os itens 3 e 4 são os que valem uma consulta ao banco hoje, e não na véspera — são os únicos da lista cuja resposta pode gerar semanas de trabalho.
Com a lista atendida, o percurso seguinte é a primeira assinatura em 5 minutos, e depois a escolha do modelo em transação, sessão ou envelope. Para o prazo do projeto inteiro, quanto tempo leva integrar. E a visão geral da API de assinatura eletrônica descreve o que será construído sobre esses requisitos.
Perguntas Frequentes
Preciso usar um SDK oficial?
Não. A API é REST com JSON e funciona com qualquer cliente HTTP. Existem SDKs oficiais para várias linguagens e eles poupam trabalho, mas nada impede uma integração feita direto contra os endpoints — inclusive porque isso evita depender da cadência de atualização de um pacote.
Que linguagem ou infraestrutura é exigida?
Nenhuma em particular. Não há agente para instalar, componente nativo, dependência de sistema operacional nem exigência de nuvem. O requisito real é conseguir fazer requisições HTTPS de saída e guardar um segredo com segurança.
Preciso mesmo de um endpoint público para webhooks?
Para produção, sim — é como a sua aplicação fica sabendo que alguém assinou sem ficar consultando a API. Precisa ser HTTPS e acessível pela internet. Em desenvolvimento dá para usar um túnel local; o que não funciona é um endereço interno que só existe dentro da sua rede.
Dá para integrar sem webhooks?
Dá, consultando o status periodicamente, e isso funciona para volumes baixos. Mas custa requisições, atrasa a reação e desperdiça o limite de chamadas. Para qualquer volume relevante, webhooks são o caminho e a consulta periódica vira apenas a reconciliação de segurança.
Que dado eu preciso ter de cada signatário?
Nome, um canal de contato e CPF ou CNPJ — este último é obrigatório em todos os perfis de verificação, inclusive nos mais simples. É o requisito que mais trava projetos na véspera, porque bases montadas para outros fins frequentemente não o têm, e não há como sintetizá-lo: o número entra na evidência.
Preciso de certificado digital para integrar?
Para a integração em si, não: as credenciais são obtidas no painel. Certificado ICP-Brasil só entra quando o documento exige assinatura com certificado — e, nesse caso, é o signatário que o possui, não a sua aplicação.
O que preciso guardar do meu lado?
O segredo da credencial, num cofre e nunca no repositório; e um identificador estável por usuário, que será a chave de tudo o que aquela pessoa assinar. O segundo parece trivial e é a decisão mais cara de reverter depois.
Confira a lista antes da primeira chamada
Se a sua aplicação faz HTTP e entende JSON, você já atende ao essencial. As credenciais de homologação são gratuitas e não pedem cartão.
Criar credenciais de homologação Fale com o time comercial