Pular para o conteúdo
AssinAPI

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. 1

    npm install @assinapi/sdk

  2. 2

    new AssinAPI({ apiKey: process.env.ASSINAPI_SECRET_KEY })

  3. 3

    assinapi.signatureRequests.create(...) envia PDF e signatário em uma chamada.

  4. 4

    assinapi.webhooks.constructEvent(...) valida HMAC e janela de tempo.

  5. 5

    assinapi.signatureRequests.download(id) baixa o PDF assinado com auditoria.

Código pronto

Envio com o SDK

typescript
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

typescript
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.