Integrando com Node.js

Use o SDK oficial @assinapi/sdk ou fetch nativo (Node 18+).

Secret key

Variável de ambiente ASSINAPI_SECRET_KEY (secret manager em produção).

Arquitetura

Seu servidor (Express/Fastify/Nest) → AssinAPI.

Criar envelope

Cria um envelope (rascunho).
npm install @assinapi/sdk

typescript

import { AssinAPI } from '@assinapi/sdk';

const assinapi = new AssinAPI({ apiKey: process.env.ASSINAPI_SECRET_KEY });

const envelope = await assinapi.envelopes.create({ title: 'Contrato de prestação de serviços', expirationDays: 7 });
console.log(envelope.id, envelope.status); // env_… DRAFT

Enviar PDF

Anexa o PDF ao envelope. O SHA-256 é calculado pela AssinAPI.
npm install @assinapi/sdk

typescript

import { AssinAPI } from '@assinapi/sdk';

const assinapi = new AssinAPI({ apiKey: process.env.ASSINAPI_SECRET_KEY });

import { readFile } from 'node:fs/promises';

await assinapi.envelopes.addDocument('ENVELOPE_ID', { file: await readFile('contrato.pdf'), filename: 'contrato.pdf' });

Adicionar signatário

Adiciona um signatário (CPF obrigatório na assinatura avançada).
npm install @assinapi/sdk

typescript

import { AssinAPI } from '@assinapi/sdk';

const assinapi = new AssinAPI({ apiKey: process.env.ASSINAPI_SECRET_KEY });

await assinapi.envelopes.addSigner('ENVELOPE_ID', {
  name: 'João da Silva',
  email: 'joao@email.com',
  cpf: '529.982.247-25',
  authenticationMethod: 'EMAIL_OTP',
});

Enviar para assinatura

Envia para assinatura. A resposta traz os signingLinks.
npm install @assinapi/sdk

typescript

import { AssinAPI } from '@assinapi/sdk';

const assinapi = new AssinAPI({ apiKey: process.env.ASSINAPI_SECRET_KEY });

const sent = await assinapi.envelopes.send('ENVELOPE_ID');
for (const link of sent.signingLinks) console.log(link.name, link.signingUrl);

Consultar status

Consulta status do envelope e dos signatários.
npm install @assinapi/sdk

typescript

import { AssinAPI } from '@assinapi/sdk';

const assinapi = new AssinAPI({ apiKey: process.env.ASSINAPI_SECRET_KEY });

const envelope = await assinapi.envelopes.get('ENVELOPE_ID');
console.log(envelope.status, envelope.signers.map((s) => s.status));

Baixar documento assinado

Retorna URLs temporárias do PDF assinado, certificado e manifesto.
npm install @assinapi/sdk

typescript

import { AssinAPI } from '@assinapi/sdk';

const assinapi = new AssinAPI({ apiKey: process.env.ASSINAPI_SECRET_KEY });

const evidence = await assinapi.envelopes.evidence('ENVELOPE_ID');
console.log(evidence.downloads.documents[0].final); // URL temporária do PDF assinado
console.log(evidence.downloads.certificate);

Receber webhooks

Valide SEMPRE a assinatura HMAC (X-Signature) usando o corpo bruto.
Rejeite eventos com X-Timestamp com mais de 5 minutos e deduplique por X-Event-Id.
Responda 2xx rapidamente; processe de forma assíncrona. Falhas são reenviadas com backoff exponencial.

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');
}