Integração · Next.js
Assinatura eletrônica em projetos Next.js
Use Route Handlers ou Server Actions — sempre no servidor — e receba os eventos em app/api/webhooks/assinapi/route.ts.
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: Vercel → Settings → Environment Variables → ASSINAPI_SECRET_KEY (sem o prefixo NEXT_PUBLIC_).
Como funciona
- 1
Um Client Component chama uma Server Action ou Route Handler.
- 2
O servidor chama a AssinAPI com a chave do ambiente.
- 3
O signatário assina; o redirectUrl pode trazê-lo de volta ao seu app.
- 4
O Route Handler de webhook valida o HMAC com o corpo bruto (req.text()).
- 5
O status é salvo no banco e a interface é revalidada.
Código pronto
Route Handler / Server Action
// app/api/assinapi/create-envelope/route.ts
export async function POST(request: Request) {
const res = await fetch('https://api.assinapi.com.br/v1/envelopes', {
method: 'POST',
headers: { Authorization: `Bearer ${process.env.ASSINAPI_SECRET_KEY}`, 'Content-Type': 'application/json', 'Idempotency-Key': crypto.randomUUID() },
body: JSON.stringify({
"title": "Contrato de prestação de serviços",
"expirationDays": 7
}),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message} (requestId ${data.error.requestId})`);
return Response.json(data, { status: res.status });
}Webhook com o SDK
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.
Funciona no Edge Runtime?
As chamadas são HTTP simples; o SDK usa fetch. Para o webhook, leia o corpo bruto com req.text() antes de validar o HMAC.
Como meu sistema fica sabendo que o documento foi assinado?
Por webhooks assinados com HMAC-SHA256 (eventos como signer.signed e envelope.completed) ou consultando GET /v1/signature-requests/:id, que devolve o status e o próximo passo em português.
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.