Integração com Node.js / TypeScript em poucos minutos

Exemplos prontos para copiar com fetch nativo (Node 18+): criar assinatura, consultar status, baixar o PDF e validar webhooks.

Sem bibliotecas extras: só HTTP. Execute sempre no servidor — a chave de API nunca vai para o navegador.

1. 1.SDK leve (opcional, sem dependências)

   Prefere um cliente pronto? Copie a pasta sdk/node do repositório: um único arquivo com cliente, tipos TypeScript e validação de webhook.

   uso.tsCopiar

   import { AssinaturaClient, verifyWebhook } from "./assinatura-sdk/index.js";
   
   const client = new AssinaturaClient({ apiKey: process.env.ASSINATURA_API_KEY! });
   
   const sig = await client.createSimpleSignature({
     documentName: "Contrato",
     pdfBase64,
     signers: [{ full_name: "Maria Exemplo", email: "maria@example.com" }],
     sendEmailInvitation: true,
   });
   const status = await client.getSignature(sig.signature_id);
   const pdf = await client.downloadPdf(sig.signature_id); // Buffer

2. 2.Configure as credenciais

   Guarde a chave e o segredo de webhook em variáveis de ambiente do servidor.

   .envCopiar

   ASSINATURA_API_KEY=sk_sua_chave
   ASSINATURA_API_SECRET=seu_segredo_de_webhook
   ASSINATURA_BASE_URL=https://assinatura.online/api/public/v1

3. 3.Crie uma assinatura simples

   O signatário recebe o convite por e-mail e confirma com um código. A resposta traz o sign_url.

   criar-assinatura.tsCopiar

   const BASE = process.env.ASSINATURA_BASE_URL!;
   const headers = {
     Authorization: `Bearer ${process.env.ASSINATURA_API_KEY}`,
     "Content-Type": "application/json",
   };
   
   export async function criarAssinatura(pdfBase64: string) {
     const res = await fetch(`${BASE}/signatures/create`, {
       method: "POST",
       headers,
       body: JSON.stringify({
         mode: "simple",
         document_name: "Contrato de prestação de serviços",
         pdf_base64: pdfBase64,
         signer: { full_name: "Maria Exemplo", email: "maria@example.com" },
         send_email_invitation: true,
         external_id: "pedido-123",
       }),
     });
     const data = await res.json();
     if (!res.ok) throw new Error(`${data.code}: ${data.error}`);
     return data as { signature_id: string; status: string; sign_url: string };
   }

4. 4.Assinatura qualificada com Bird ID ou VIDaaS

   Troque o modo pelo provedor e informe o CPF do titular do certificado.

   qualificada.tsCopiar

   await fetch(`${BASE}/signatures/create`, {
     method: "POST",
     headers,
     body: JSON.stringify({
       provider: "birdid", // ou "vidaas" / "a1"
       document_name: "Laudo técnico",
       pdf_base64: pdfBase64,
       signer: { cpf: "52998224725", full_name: "Ana Exemplo" },
     }),
   });

5. 5.Consulte o status e baixe o PDF

   Use para conferir o resultado no servidor. O PDF fica disponível após a conclusão.

   status.tsCopiar

   const r = await fetch(`${BASE}/signatures/get?signature_id=${id}`, { headers });
   const assinatura = await r.json(); // assinatura.status
   
   const pdf = await fetch(`${BASE}/signatures/pdf?signature_id=${id}`, { headers });
   const bytes = Buffer.from(await pdf.arrayBuffer());

6. 6.Valide o webhook (HMAC-SHA256)

   Leia o corpo bruto, confira a assinatura e só então processe o evento.

   webhook.tsCopiar

   import crypto from "node:crypto";
   
   export async function handleWebhook(request: Request) {
     const timestamp = request.headers.get("X-Assinatura-Timestamp") ?? "";
     const received = (request.headers.get("X-Assinatura-Signature") ?? "").split("v1=")[1] ?? "";
     const rawBody = await request.text();
   
     const expected = crypto
       .createHmac("sha256", process.env.ASSINATURA_API_SECRET!)
       .update(`${timestamp}.${rawBody}`)
       .digest("hex");
   
     const ok = received.length === expected.length &&
       crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
     if (!ok) return new Response("assinatura inválida", { status: 401 });
   
     const event = JSON.parse(rawBody);
     if (event.event === "signature.completed") {
       // marque o pedido event.external_id como assinado
     }
     return new Response("ok");
   }

Integre a API da assinatura.online neste projeto Node.js/TypeScript, apenas no servidor.
Base: https://assinatura.online/api/public/v1, header Authorization: Bearer <ASSINATURA_API_KEY>.
1) Função que faz POST /signatures/create com mode "simple", document_name, pdf_base64, signer { full_name, email }, send_email_invitation: true e external_id; retorne signature_id e sign_url.
2) GET /signatures/get?signature_id= para status e GET /signatures/pdf?signature_id= para o PDF.
3) Rota de webhook que valida HMAC-SHA256 de "<X-Assinatura-Timestamp>.<corpo bruto>" com ASSINATURA_API_SECRET contra o valor v1= do header X-Assinatura-Signature, usando comparação em tempo constante.
Nunca exponha a chave no navegador. Consulte https://assinatura.online/documentacao.