Integração · Node.js
Assinatura eletrônica em Node.js
O SDK oficial @assinapi/sdk envia Idempotency-Key em todos os POSTs, refaz chamadas em falhas temporárias e valida webhooks.
curl -X POST /v1/signature-requests
201 Created · 312 ms
"status": "SENT", "signingUrl": "…/s/9xq4m"
webhook signer.signed → 200 OK
Antes de tudo: a chave fica no servidor
Onde fica a chave: Variável de ambiente ASSINAPI_SECRET_KEY (secret manager em produção). O SDK é para uso no servidor.
Como funciona
- 1
npm install @assinapi/sdk
- 2
new AssinAPI({ apiKey: process.env.ASSINAPI_SECRET_KEY })
- 3
assinapi.signatureRequests.create(...) envia PDF e signatário em uma chamada.
- 4
assinapi.webhooks.constructEvent(...) valida HMAC e janela de tempo.
- 5
assinapi.signatureRequests.download(id) baixa o PDF assinado com auditoria.
Código pronto
Envio com o SDK
import { AssinAPI } from '@assinapi/sdk';
const assinapi = new AssinAPI({ apiKey: process.env.ASSINAPI_SECRET_KEY });
const request = await assinapi.signatureRequests.create({
title: 'Contrato de prestação de serviços',
file: pdfBuffer,
filename: 'contrato.pdf',
signer: { name: 'João da Silva', email: 'joao@email.com', cpf: '529.982.247-25', phone: '+5511999999999' },
// authentication omitido = padrão do projeto (avançada: código pelo WhatsApp nos planos pagos; por e-mail no Free)
});
console.log(request.signingUrl);Webhook
import { AssinAPI } from '@assinapi/sdk';
const assinapi = new AssinAPI({ apiKey: process.env.ASSINAPI_SECRET_KEY });
// Next.js Route Handler: app/api/webhooks/assinapi/route.ts
export async function POST(req: Request) {
const event = assinapi.webhooks.constructEvent({
payload: await req.text(),
headers: req.headers,
secret: process.env.ASSINAPI_WEBHOOK_SECRET!,
});
if (event.type === 'envelope.completed') {
// atualize o status no seu banco e baixe as evidências com assinapi.envelopes.evidence(...)
}
return new Response('ok');
}Exemplos apontam para o Sandbox (https://api.assinapi.com.br/v1). Em Produção, troque apenas a chave (ask_live_…); o endereço é o mesmo.
Perguntas frequentes
Perguntas técnicas.
Qual versão do Node é necessária?
Node 18 ou superior (fetch e FormData nativos).
O SDK repete chamadas com segurança?
Sim. Retries em 429/409/5xx/rede reutilizam a mesma Idempotency-Key, então um documento nunca é criado duas vezes.
Como o signatário se autentica? Dá para usar WhatsApp?
WhatsApp está nos planos pagos. Simples: por padrão só o link por e-mail (EMAIL_LINK). Avançada (CPF e data de nascimento conferidos): nos planos pagos, link por e-mail + código pelo WhatsApp (WHATSAPP_OTP) ou só WhatsApp (WHATSAPP_LINK); no Free, link e código por e-mail (EMAIL_OTP), e pedir WhatsApp devolve 402 WHATSAPP_REQUIRES_PAID_PLAN. Envie o celular em phone (+5511999999999) e, se quiser, defina o padrão no projeto.
Consigo testar sem custo?
Sim. O Sandbox é gratuito: chaves ask_test_…, código de confirmação fixo 123456 e CPFs de teste. Documentos de Sandbox não têm validade e não consomem a franquia do plano.
Primeira assinatura no Sandbox em menos de 10 minutos.
Sem cartão de crédito. Sandbox gratuito; você só paga por documentos enviados em Produção.