Como integrar assinatura eletrônica via API REST

Sim, dá para integrar assinatura eletrônica ao seu próprio sistema sem trocar a interface do seu produto: o eSocial Sign expõe uma API REST v1 (/api/v1), autenticada por token Bearer, que cobre o mesmo ciclo do painel — criar envelope, subir documentos, adicionar signatários, enviar para assinatura e acompanhar o status.

Na prática, a integração segue um fluxo simples: sua aplicação autentica e recebe um token, cria o envelope com os documentos e signatários, envia para assinatura e depois recebe notificações automáticas (webhooks) conforme cada signatário assina, até o envelope ser concluído. Não é preciso o usuário final abrir o painel do eSocial Sign em nenhum momento — ele assina pelo link que sua aplicação já dispara via API.

Por que integrar via API em vez de usar o painel

Times de produto costumam usar o painel quando o volume de documentos é baixo e cada envio pode ser feito manualmente. A API entra quando a assinatura precisa nascer de um evento do seu próprio sistema — um contrato gerado pelo seu ERP, um termo de aceite disparado pelo seu CRM, uma admissão criada pelo seu módulo de RH. Nesses casos, criar o envelope, subir o documento e adicionar os signatários programaticamente evita retrabalho manual e mantém o status de assinatura sincronizado com o seu banco de dados, via webhook.

Isso não muda a base jurídica do processo: a validade da assinatura continua amparada pela Lei 14.063/2020, que regula o uso de assinaturas eletrônicas no Brasil. A API não é um atalho jurídico, é só outra porta de entrada para o mesmo fluxo de coleta de evidências (IP, data/hora, código de verificação e demais elementos do nível de segurança escolhido).

Autenticação: como o token funciona

A API usa autenticação por token Bearer, implementada sobre o Laravel Sanctum. O fluxo básico é:

1. Sua aplicação envia as credenciais de um usuário da empresa (e-mail, senha e um identificador do seu sistema, algo como um device_name) para o endpoint de autenticação.
2. A resposta traz um token de acesso.
3. Esse token vai no header Authorization de toda requisição seguinte:

Authorization: Bearer <seu-token>

Alguns pontos importantes de projeto ao integrar:

• O token tem validade de 30 dias — sua integração precisa renovar antes de expirar (existe um endpoint de refresh dedicado para isso), em vez de tratar a expiração como um erro inesperado.
• Cada identificador de aplicação mantém apenas um token ativo por vez: gerar um novo token com o mesmo identificador revoga automaticamente o anterior. Se você tem múltiplos ambientes (produção, homologação), use identificadores diferentes para não derrubar um token que ainda está em uso.
• Existe um endpoint para revogar o token atual quando a integração for desligada — trate isso como parte do desligamento de um ambiente, não como algo opcional.
• O token concede acesso em nome da conta que o gerou. Guarde-o como qualquer outro segredo de produção (variável de ambiente, cofre de secrets), nunca em texto plano no repositório.

O fluxo de integração, em alto nível

Depois de autenticado, o ciclo de um documento pela API segue a mesma lógica do painel:

autenticar
  → criar envelope (título, nível de segurança)
  → anexar documento(s)
  → adicionar signatário(s)
  → enviar para assinatura
  → acompanhar status via consulta ou webhook
  → baixar o PDF final quando concluído

Cada etapa tem seu próprio endpoint dentro de /api/v1, documentado com exemplos de request e response na documentação técnica da plataforma. Evite tentar adivinhar nomes de campo ou formato de payload a partir de suposições — a resposta de cada chamada já retorna a estrutura que a próxima etapa espera receber (por exemplo, o identificador do envelope criado é o que você usa para anexar documentos e signatários a ele).

Um ponto que costuma pegar quem está automatizando pela primeira vez: documentos em formatos como Word, Excel ou imagem passam por uma conversão automática para PDF depois do upload. Se sua integração tentar enviar o envelope para assinatura imediatamente após subir o arquivo, pode encontrar um estado de "conversão em andamento" — vale checar o status antes de disparar o envio, em vez de assumir que o upload já deixa o documento pronto.

Recebendo eventos por webhook em vez de fazer polling

Para saber quando um signatário assinou ou quando o envelope foi concluído, a forma recomendada é configurar um webhook em vez de ficar consultando a API em intervalos fixos. Você cadastra uma URL HTTPS do seu sistema e escolhe quais eventos quer receber — envelope criado, enviado, concluído, cancelado, expirado, além de eventos por signatário (assinou, recusou).

Cada entrega chega como um POST em JSON, com um campo identificando o evento e um campo com os dados daquele evento específico. Junto vem um header de assinatura HMAC-SHA256, calculado com um secret exclusivo do seu webhook — seu endpoint deve validar essa assinatura antes de confiar no conteúdo, para garantir que a notificação realmente veio do eSocial Sign e não foi forjada por terceiros. Responda com um status HTTP de sucesso (2xx) rapidamente; se seu processamento for pesado, enfileire o trabalho e responda em seguida, em vez de deixar a entrega esperando.

Essa combinação — autenticação por token de curta duração, criação de envelope programática e notificação por webhook validado — é o mesmo padrão usado por integrações de pagamento e ERPs maduros. Não é um desenho exclusivo da assinatura eletrônica, e por isso costuma ser rápido de plugar em quem já integrou outras APIs REST antes.

O que muda entre ambiente de teste e produção

A base da URL muda entre ambientes (o endpoint de produção é o domínio oficial da plataforma), mas a estrutura de chamadas é a mesma. Antes de apontar sua integração para produção, vale simular o ciclo completo — criar, enviar, assinar (usando um signatário de teste) e conferir se o webhook chegou e a assinatura HMAC validou — para não descobrir um detalhe de payload só quando o primeiro cliente real estiver assinando um documento.

Comece a integrar

Se sua aplicação já gera documentos que precisam de assinatura com validade jurídica, a API do eSocial Sign permite plugar esse fluxo sem construir nada de evidência, OTP ou geração de PDF final do zero. Crie uma conta gratuita, gere seu primeiro token de acesso e teste o ciclo completo em poucos minutos.