Integrando com n8n

Use o node HTTP Request com uma credencial Header Auth e o node Webhook para receber eventos.

Secret key

Credentials → Header Auth → Name: Authorization, Value: Bearer ask_test_…

Arquitetura

Trigger → HTTP Request (AssinAPI) → … · Webhook node ← AssinAPI (valide o HMAC em um Code node).

Criar envelope

Cria um envelope (rascunho).
Cole no editor do n8n. Crie a credencial "Header Auth" com Authorization = Bearer <sua chave>.

json

{
  "nodes": [
    {
      "name": "AssinAPI create-envelope",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.2,
      "position": [
        0,
        0
      ],
      "parameters": {
        "method": "POST",
        "url": "https://sandbox.api.assinapi.com.br/v1/envelopes",
        "authentication": "genericCredentialType",
        "genericAuthType": "httpHeaderAuth",
        "sendBody": true,
        "specifyBody": "json",
        "jsonBody": "{\n  \"title\": \"Contrato de prestação de serviços\",\n  \"expirationDays\": 7\n}"
      }
    }
  ]
}

Enviar PDF

Anexa o PDF ao envelope. O SHA-256 é calculado pela AssinAPI.
Cole no editor do n8n. Crie a credencial "Header Auth" com Authorization = Bearer <sua chave>.

json

{
  "nodes": [
    {
      "name": "AssinAPI upload-pdf",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.2,
      "position": [
        0,
        0
      ],
      "parameters": {
        "method": "POST",
        "url": "https://sandbox.api.assinapi.com.br/v1/envelopes/ENVELOPE_ID/documents",
        "authentication": "genericCredentialType",
        "genericAuthType": "httpHeaderAuth",
        "sendBody": true,
        "contentType": "multipart-form-data",
        "bodyParameters": {
          "parameters": [
            {
              "parameterType": "formBinaryData",
              "name": "file",
              "inputDataFieldName": "data"
            }
          ]
        }
      }
    }
  ]
}

Adicionar signatário

Adiciona um signatário (CPF obrigatório na assinatura avançada).
Cole no editor do n8n. Crie a credencial "Header Auth" com Authorization = Bearer <sua chave>.

json

{
  "nodes": [
    {
      "name": "AssinAPI add-signer",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.2,
      "position": [
        0,
        0
      ],
      "parameters": {
        "method": "POST",
        "url": "https://sandbox.api.assinapi.com.br/v1/envelopes/ENVELOPE_ID/signers",
        "authentication": "genericCredentialType",
        "genericAuthType": "httpHeaderAuth",
        "sendBody": true,
        "specifyBody": "json",
        "jsonBody": "{\n  \"name\": \"João da Silva\",\n  \"email\": \"joao@email.com\",\n  \"cpf\": \"529.982.247-25\",\n  \"authenticationMethod\": \"EMAIL_OTP\"\n}"
      }
    }
  ]
}

Enviar para assinatura

Envia para assinatura. A resposta traz os signingLinks.
Cole no editor do n8n. Crie a credencial "Header Auth" com Authorization = Bearer <sua chave>.

json

{
  "nodes": [
    {
      "name": "AssinAPI send",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.2,
      "position": [
        0,
        0
      ],
      "parameters": {
        "method": "POST",
        "url": "https://sandbox.api.assinapi.com.br/v1/envelopes/ENVELOPE_ID/send",
        "authentication": "genericCredentialType",
        "genericAuthType": "httpHeaderAuth",
        "sendBody": true,
        "specifyBody": "json",
        "jsonBody": "{\n  \"notify\": true\n}"
      }
    }
  ]
}

Consultar status

Consulta status do envelope e dos signatários.
Cole no editor do n8n. Crie a credencial "Header Auth" com Authorization = Bearer <sua chave>.

json

{
  "nodes": [
    {
      "name": "AssinAPI status",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.2,
      "position": [
        0,
        0
      ],
      "parameters": {
        "method": "GET",
        "url": "https://sandbox.api.assinapi.com.br/v1/envelopes/ENVELOPE_ID",
        "authentication": "genericCredentialType",
        "genericAuthType": "httpHeaderAuth",
        "sendBody": false
      }
    }
  ]
}

Baixar documento assinado

Retorna URLs temporárias do PDF assinado, certificado e manifesto.
Cole no editor do n8n. Crie a credencial "Header Auth" com Authorization = Bearer <sua chave>.

json

{
  "nodes": [
    {
      "name": "AssinAPI download",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.2,
      "position": [
        0,
        0
      ],
      "parameters": {
        "method": "GET",
        "url": "https://sandbox.api.assinapi.com.br/v1/envelopes/ENVELOPE_ID/evidence",
        "authentication": "genericCredentialType",
        "genericAuthType": "httpHeaderAuth",
        "sendBody": false
      }
    }
  ]
}

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.
Plataformas low-code: receba o webhook em um backend (Supabase Edge Function, Cloudflare Worker ou n8n com Code node) para validar o HMAC.

text

1) Registre o endpoint:
curl -X POST "https://sandbox.api.assinapi.com.br/v1/webhooks" \
  -H "Authorization: Bearer $ASSINAPI_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://seu-sistema.com/api/webhooks/assinapi", "events": ["envelope.completed", "signer.signed"] }'
# Guarde o "secret" (whsec_…) retornado em ASSINAPI_WEBHOOK_SECRET

2) No receptor, calcule:
   HMAC_SHA256(secret, X-Event-Id + "." + X-Timestamp + "." + corpo_bruto)
   e compare com X-Signature (formato v1=<hex>).