# SDK e n8n

Fonte: https://lunahia.com.br/docs/sdk-e-n8n

A API da Luna é HTTP comum com uma especificação OpenAPI, e você pode chamá-la de qualquer linguagem e de qualquer ferramenta. No n8n, o caminho que funciona hoje usa só os nós padrão: um Webhook para receber, um Code para conferir a assinatura e um HTTP Request para enviar. O SDK Node/TypeScript e o nó próprio do n8n estão em preparação.

A [referência da API](https://lunahia.com.br/docs/referencia) é o contrato. As ferramentas não têm regra de negócio: a [janela de 24 horas](https://lunahia.com.br/docs/glossario#janela), a capacidade do plano e o template aprovado são conferidos pela API, que responde com o motivo.

## n8n hoje: os nós padrão

Um fluxo de quatro peças, todas de fábrica no n8n: o **Webhook** recebe o evento da Luna (com o corpo bruto), o **Code** confere a assinatura, o **Respond to Webhook** devolve `200` ou `401`, e o **HTTP Request** envia a resposta pela API. Você precisa de uma chave de API com `messages:write` e do número de origem (`metaPhoneNumberId`, de `GET /v1/numbers`).

### 1. O nó Webhook

- **HTTP Method**: `POST`. **Path**: `luna` (ou o que preferir).
- **Respond**: “Using ‘Respond to Webhook’ Node”. É o que permite responder `401` a uma assinatura que não confere.
- Em **Options**, ligue **Raw Body**. Este é o passo que costuma faltar: a assinatura é calculada sobre os **bytes exatos** do corpo, e sem essa opção o n8n entrega o JSON já aberto e a conta não bate. Com ela, o corpo chega como dado binário na propriedade `data`.
- Ative o fluxo e copie a **Production URL**. Cadastre-a como endpoint da Luna (`POST /v1/webhooks/endpoints`, como em [Primeiros passos](https://lunahia.com.br/docs/primeiros-passos#webhook)) e guarde o `secret` da resposta: ele aparece uma única vez. A URL de teste do n8n não serve, porque só vive enquanto você escuta no editor.

### 2. O nó Code: conferir a assinatura

Modo **Run Once for All Items**, linguagem JavaScript. O código faz a conferência que [Receber eventos](https://lunahia.com.br/docs/receber-eventos#assinatura) explica em palavras, e devolve `valid` (verdadeiro ou falso) e, se valer, o `event` já lido. Troque `SECRET` pelo segredo do passo anterior.

```js
const crypto = require('crypto');

const SECRET = 'whsec_PASTE_YOUR_SECRET_HERE'; // cole aqui o segredo do seu endpoint (whsec_...). Em produção, guarde-o numa credencial ou numa variável.
const TOLERANCE_SECONDS = 300;

const header = $input.first().json.headers['x-luna-signature'] ?? ''; // o cabeçalho da assinatura (o nó Webhook escreve os nomes dos cabeçalhos em minúsculas)
const raw = await this.helpers.getBinaryDataBuffer(0, 'data'); // os bytes exatos que chegaram: o nó Webhook precisa estar com a opção Raw Body ligada

const m = /^t=(\d{1,15}),/.exec(header);
if (!m) return [{ json: { valid: false } }];
const t = Number(m[1]);

// recuse o que é velho demais (uma entrega capturada e repetida depois)
if (Math.abs(Math.floor(Date.now() / 1000) - t) > TOLERANCE_SECONDS) {
  return [{ json: { valid: false } }];
}

// refaça a conta com o seu segredo e compare com cada v1
const expected = crypto.createHmac('sha256', SECRET).update(t + '.').update(raw).digest();
let valid = false;
// na troca do segredo o cabeçalho traz dois valores v1: confira todos
for (const [, hex] of header.matchAll(/v1=([0-9a-fA-F]{64})/g)) {
  if (crypto.timingSafeEqual(Buffer.from(hex, 'hex'), expected)) valid = true;
}

// o próximo nó lê valid e, se for verdadeiro, o evento
return [{ json: { valid, event: valid ? JSON.parse(raw.toString('utf8')) : null } }];
```

> O nó Code só usa os módulos do Node que o administrador do n8n liberou. Se o `require('crypto')` for recusado, defina `NODE_FUNCTION_ALLOW_BUILTIN=crypto` no ambiente do n8n (num n8n que você mesmo hospeda) e reinicie.

### 3. O nó HTTP Request: enviar a resposta

Depois de um nó “IF” que deixa passar só o que tem `valid` verdadeiro, e de outro que filtra `event.event_type` igual a `message.received`, o HTTP Request chama a API:

| Campo | Valor |
| --- | --- |
| Method | `POST` |
| URL | `https://api.lunahia.com.br/v1/messages` |
| Cabeçalho `Authorization` | `Bearer hlsn_...` (a sua chave; no n8n, prefira uma credencial “Header Auth”) |
| Cabeçalho `Idempotency-Key` | `resp-` seguido do `id` da mensagem recebida: com ele, repetir a execução não envia duas respostas |
| Body (JSON) | `from` (o seu número), `to` (o `wa_id` do evento) e `text.body` |

### Um fluxo pronto para importar

O JSON abaixo é o fluxo inteiro: Webhook, Code, IF, as duas respostas, o filtro de mensagem recebida e o HTTP Request. Copie, e no n8n cole no canvas (Ctrl+V ou Cmd+V) ou use **Import from File**. Depois troque os três valores `PASTE_...`: o segredo no nó Code, a chave de API e o número no HTTP Request.

```json
{
  "name": "Luna: responder mensagem recebida",
  "nodes": [
    {
      "parameters": {
        "httpMethod": "POST",
        "path": "luna",
        "responseMode": "responseNode",
        "options": {
          "rawBody": true
        }
      },
      "id": "5b0c1c1e-2f3a-4b5c-8d6e-7f8091a2b3c1",
      "name": "Webhook da Luna",
      "type": "n8n-nodes-base.webhook",
      "typeVersion": 2,
      "position": [
        0,
        300
      ],
      "webhookId": "9d8c7b6a-5e4f-4a3b-9c2d-1e0f9a8b7c6d"
    },
    {
      "parameters": {
        "jsCode": "const crypto = require('crypto');\n\nconst SECRET = 'whsec_PASTE_YOUR_SECRET_HERE'; // cole aqui o segredo do seu endpoint (whsec_...). Em produção, guarde-o numa credencial ou numa variável.\nconst TOLERANCE_SECONDS = 300;\n\nconst header = $input.first().json.headers['x-luna-signature'] ?? ''; // o cabeçalho da assinatura (o nó Webhook escreve os nomes dos cabeçalhos em minúsculas)\nconst raw = await this.helpers.getBinaryDataBuffer(0, 'data'); // os bytes exatos que chegaram: o nó Webhook precisa estar com a opção Raw Body ligada\n\nconst m = /^t=(\\d{1,15}),/.exec(header);\nif (!m) return [{ json: { valid: false } }];\nconst t = Number(m[1]);\n\n// recuse o que é velho demais (uma entrega capturada e repetida depois)\nif (Math.abs(Math.floor(Date.now() / 1000) - t) > TOLERANCE_SECONDS) {\n  return [{ json: { valid: false } }];\n}\n\n// refaça a conta com o seu segredo e compare com cada v1\nconst expected = crypto.createHmac('sha256', SECRET).update(t + '.').update(raw).digest();\nlet valid = false;\n// na troca do segredo o cabeçalho traz dois valores v1: confira todos\nfor (const [, hex] of header.matchAll(/v1=([0-9a-fA-F]{64})/g)) {\n  if (crypto.timingSafeEqual(Buffer.from(hex, 'hex'), expected)) valid = true;\n}\n\n// o próximo nó lê valid e, se for verdadeiro, o evento\nreturn [{ json: { valid, event: valid ? JSON.parse(raw.toString('utf8')) : null } }];"
      },
      "id": "6c1d2d2f-3a4b-4c5d-9e7f-8a9102b3c4d2",
      "name": "Verificar a assinatura",
      "type": "n8n-nodes-base.code",
      "typeVersion": 2,
      "position": [
        240,
        300
      ]
    },
    {
      "parameters": {
        "conditions": {
          "options": {
            "caseSensitive": true,
            "leftValue": "",
            "typeValidation": "strict",
            "version": 2
          },
          "conditions": [
            {
              "id": "a1b2c3d4-0001-4000-8000-000000000001",
              "leftValue": "={{ $json.valid }}",
              "rightValue": "",
              "operator": {
                "type": "boolean",
                "operation": "true",
                "singleValue": true
              }
            }
          ],
          "combinator": "and"
        },
        "options": {}
      },
      "id": "7d2e3e30-4b5c-4d6e-8f80-9b0213c4d5e3",
      "name": "Assinatura válida?",
      "type": "n8n-nodes-base.if",
      "typeVersion": 2.2,
      "position": [
        480,
        300
      ]
    },
    {
      "parameters": {
        "respondWith": "noData",
        "options": {
          "responseCode": 200
        }
      },
      "id": "8e3f4f41-5c6d-4e7f-9091-ac1324d5e6f4",
      "name": "Responder 200",
      "type": "n8n-nodes-base.respondToWebhook",
      "typeVersion": 1.1,
      "position": [
        720,
        200
      ]
    },
    {
      "parameters": {
        "respondWith": "noData",
        "options": {
          "responseCode": 401
        }
      },
      "id": "9f405052-6d7e-4f80-a1a2-bd2435e6f705",
      "name": "Responder 401",
      "type": "n8n-nodes-base.respondToWebhook",
      "typeVersion": 1.1,
      "position": [
        720,
        420
      ]
    },
    {
      "parameters": {
        "conditions": {
          "options": {
            "caseSensitive": true,
            "leftValue": "",
            "typeValidation": "strict",
            "version": 2
          },
          "conditions": [
            {
              "id": "a1b2c3d4-0002-4000-8000-000000000002",
              "leftValue": "={{ $('Verificar a assinatura').item.json.event.event_type === 'message.received' }}",
              "rightValue": "",
              "operator": {
                "type": "boolean",
                "operation": "true",
                "singleValue": true
              }
            }
          ],
          "combinator": "and"
        },
        "options": {}
      },
      "id": "a0516163-7e8f-4091-b2b3-ce3546f70816",
      "name": "É mensagem recebida?",
      "type": "n8n-nodes-base.if",
      "typeVersion": 2.2,
      "position": [
        960,
        200
      ]
    },
    {
      "parameters": {
        "method": "POST",
        "url": "https://api.lunahia.com.br/v1/messages",
        "sendHeaders": true,
        "headerParameters": {
          "parameters": [
            {
              "name": "Authorization",
              "value": "Bearer hlsn_PASTE_YOUR_KEY_HERE"
            },
            {
              "name": "Idempotency-Key",
              "value": "=resp-{{ $('Verificar a assinatura').item.json.event.message.id }}"
            }
          ]
        },
        "sendBody": true,
        "specifyBody": "json",
        "jsonBody": "={{ JSON.stringify({ from: 'PASTE_YOUR_NUMBER_ID_HERE', to: $('Verificar a assinatura').item.json.event.message.wa_id, text: { body: 'Recebi: ' + $('Verificar a assinatura').item.json.event.message.text } }) }}",
        "options": {}
      },
      "id": "b1627274-8f90-4102-83c4-df4657081927",
      "name": "Enviar a resposta",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.2,
      "position": [
        1200,
        100
      ]
    }
  ],
  "connections": {
    "Webhook da Luna": {
      "main": [
        [
          {
            "node": "Verificar a assinatura",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Verificar a assinatura": {
      "main": [
        [
          {
            "node": "Assinatura válida?",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Assinatura válida?": {
      "main": [
        [
          {
            "node": "Responder 200",
            "type": "main",
            "index": 0
          }
        ],
        [
          {
            "node": "Responder 401",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Responder 200": {
      "main": [
        [
          {
            "node": "É mensagem recebida?",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "É mensagem recebida?": {
      "main": [
        [
          {
            "node": "Enviar a resposta",
            "type": "main",
            "index": 0
          }
        ]
      ]
    }
  },
  "pinData": {},
  "settings": {
    "executionOrder": "v1"
  }
}
```

> **O que foi conferido, e o que não foi.** O código do nó Code é executado nos testes da documentação contra a assinatura de verdade da Luna. O fluxo em JSON foi escrito a partir da documentação dos nós padrão do n8n, e a Helsen ainda não o importou num n8n real: se a sua versão nomear alguma opção de outro jeito, o que muda é a tela, e não a lógica. Para conferir de ponta a ponta, mande o evento de teste (`POST /v1/webhooks/endpoints/{id}/test`, veja [Receber eventos](https://lunahia.com.br/docs/receber-eventos#gerir)): se o nó Code responder `valid` verdadeiro, a conta bate.

Para montar e testar o fluxo sem mandar mensagem de verdade, use uma chave de teste no HTTP Request: o envio não vai à Meta, e a Luna entrega ao seu webhook os estados `sent`, `delivered` e `read` com `test: true`. Veja [Modo de teste](https://lunahia.com.br/docs/modo-de-teste). Um agente de IA que responde com um modelo no meio do fluxo segue o laço de [Agente de IA](https://lunahia.com.br/docs/agente-de-ia).

## Em breve: o SDK e o nó próprio

> **O SDK Node/TypeScript e o nó do n8n da Luna ainda não estão publicados** (nem no npm, nem no diretório de nós do n8n), e não há data. Eles vivem no repositório da Luna, em `packages/sdk` e `packages/n8n-nodes-luna`. O n8n de hoje é o fluxo acima, e o Node de hoje é o `fetch` (veja [Agente de IA](https://lunahia.com.br/docs/agente-de-ia)).

## SDK Node/TypeScript

O SDK é o cliente tipado gerado da especificação, com três acréscimos: a URL de produção como padrão (`criarLuna`), o tratamento de erro (`exigir` devolve o corpo de uma resposta boa e lança `LunaErro` na recusa, com `status`, `codigo` e `docsUrl`) e a verificação da assinatura do webhook. Cada caminho e cada verbo vêm da especificação, então uma rota que a API não serve é erro de compilação.

Criar o cliente e enviar

```js
import { criarLuna, exigir } from '@helsen/sdk';

const luna = criarLuna({ apiKey: process.env.LUNA_API_KEY });

const envio = exigir(
  await luna.POST('/v1/messages', {
    body: { from: '1000000000000001', to: '5511900000000', type: 'text', text: { body: 'Olá!' } },
  }),
);
console.log(envio.id, envio.status);
```

### Conferir a assinatura do webhook

`lerEvento` confere a assinatura (`x-luna-signature`) sobre os **bytes exatos** do corpo e só então lê o JSON, devolvendo o evento tipado por `event_type`. Com assinatura que não confere, lança `AssinaturaInvalida`, e o corpo não é lido. `verificarAssinatura` só devolve `true` ou `false`. Durante a rotação do segredo, passe uma lista com o novo e o antigo. É o mesmo código que a Luna usa para assinar, então o resultado concorda com o do verificador de referência em [Receber eventos](https://lunahia.com.br/docs/receber-eventos).

Um servidor de webhook com o SDK

```js
import express from 'express';
import { lerEvento, AssinaturaInvalida, CABECALHO_DA_ASSINATURA } from '@helsen/sdk';

const app = express();

// O corpo precisa chegar como bytes, sem passar por express.json() antes.
app.post('/luna', express.raw({ type: 'application/json' }), (req, res) => {
  try {
    const evento = lerEvento(req.body, req.headers[CABECALHO_DA_ASSINATURA], process.env.LUNA_WEBHOOK_SECRET);
    if (evento.event_type === 'message.received') console.log(evento.message.text);
    res.sendStatus(200);
  } catch (erro) {
    if (erro instanceof AssinaturaInvalida) return res.sendStatus(401);
    throw erro;
  }
});
```

Um evento com `test: true` é de teste. Veja [Modo de teste](https://lunahia.com.br/docs/modo-de-teste).

## Nó do n8n

O pacote traz uma credencial e dois nós. A **credencial Luna API** guarda a chave (`hlsn_...`) e a URL da API, e o botão de teste dela lê `GET /v1/numbers`, então a chave precisa do escopo `numbers:read`. O nó **Luna** envia texto, envia template e lista os números. O gatilho **Luna Trigger** inicia o fluxo quando a Luna entrega um evento.

### Enviar uma mensagem

1. Crie a credencial com a sua chave de API.
2. No nó Luna, escolha Mensagem e Enviar Texto, ou Enviar Template. Preencha o número de origem (o `metaPhoneNumberId` que Listar Números devolve), o telefone do destinatário (só dígitos) e o conteúdo.
3. A saída é o `202` da API, com o `id` da mensagem. Se a API recusar (por exemplo `409`, texto fora da janela de 24 horas), o nó falha com a resposta dela; com "Continuar em caso de erro" ligado, o erro vira um item.

### Receber eventos no n8n

1. Ative o fluxo e copie a URL de produção do webhook do nó Luna Trigger.
2. Cadastre essa URL como endpoint da Luna (`POST /v1/webhooks/endpoints`). A resposta traz o segredo uma única vez.
3. Cole o segredo no campo "Segredo de Assinatura" do nó.

O nó confere a assinatura sobre os bytes exatos do corpo e responde `401`, sem rodar o fluxo, quando ela não confere. Ele **não cadastra o endpoint sozinho**. Dá para filtrar por tipo de evento (separados por vírgula, vazio quer dizer todos) e descartar os eventos com `test: true`.

> **O nó do n8n nunca foi carregado num n8n de verdade.** Ele foi escrito e testado com um duplo do contexto do n8n. O comportamento do corpo bruto e da resposta `401` no gatilho está a confirmar num n8n real, antes de qualquer publicação.

## Montar o fluxo sem mandar mensagem de verdade

Use uma chave de teste na credencial do n8n, ou no SDK. Enviar não vai à Meta, e a Luna entrega ao seu webhook os estados `sent`, `delivered` e `read`, com `test: true`. O botão de teste da credencial do n8n lê `GET /v1/numbers` e uma chave de teste não passa nele, mas as operações de enviar funcionam. O guia [Modo de teste](https://lunahia.com.br/docs/modo-de-teste) explica tudo.
