# SaaS com N clientes

Fonte: https://lunahia.com.br/docs/saas-com-n-clientes

Você tem um produto, os seus clientes têm negócios, e cada negócio precisa do próprio WhatsApp dentro do seu produto. Na Luna, cada negócio conecta o número dele (a “instância” é o número), e o fio que amarra tudo é o [`externalId`](https://lunahia.com.br/docs/glossario#externalid): o rótulo que você dá ao cliente. Ele volta no link, no número, na chave, no webhook e em todo evento de número e de link. Este guia segue o caminho de um SaaS que contrata 20 números.

O contrato de cada rota, campo a campo, está na [referência da API](https://lunahia.com.br/docs/referencia). Este guia segue a ordem em que um produto com muitos clientes usa as rotas.

## O fio: um externalId por cliente

O `externalId` é texto livre de 1 a 128 caracteres que a Luna nunca interpreta. Use o identificador do cliente no seu sistema. Ele nasce no link de conexão, vai para o número quando o cliente conecta, e a partir daí amarra o resto:

| Onde | O que o externalId faz |
| --- | --- |
| `POST /v1/onboarding/links` | Marca o link e o número que resultar dele. |
| Todo evento de número e de link | Vem em `number.external_id` (e em `link.external_id` nos eventos do link). Separa os clientes num endpoint só. Os eventos de template e o de teste não têm cliente: veja a tabela da seção 3. |
| As listas de números, mensagens, conversas e links | O filtro `?externalId=` devolve só o que é do cliente, sem você guardar o mapa de números. |
| `POST /v1/api-keys` | A chave de UM cliente: só enxerga e usa os números dele. |
| `POST /v1/webhooks/endpoints` | O endpoint de UM cliente (`externalIds`), se você prefere uma URL por cliente. |

> Um número conectado pelo console, sem link, nasce sem `externalId`. Dê um com `PATCH /v1/numbers/{id}`; o mesmo vale para reaproveitar um número para outro cliente seu.

## 1. A capacidade do plano

O plano define uma coisa só: quantos números a conta mantém ativos ao mesmo tempo. Com 20 números contratados, você conecta 20 clientes. `GET /v1/subscription` diz a capacidade e quantos estão em uso, e o 21º link responde `409` com `error: "number_capacity_reached"`. Para contratar ou ampliar, escreva para contato@lunahia.com.br. Detalhes em [Plano e números](https://lunahia.com.br/docs/plano-e-numeros).

```bash
curl -X GET "https://api.lunahia.com.br/v1/subscription" \
  -H "Authorization: Bearer $LUNA_API_KEY"
```

```js
const res = await fetch('https://api.lunahia.com.br/v1/subscription', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.LUNA_API_KEY}`,
  },
});
console.log(res.status, await res.json());
```

```python
import os
import requests

res = requests.get(
    "https://api.lunahia.com.br/v1/subscription",
    headers={
        "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}",
    },
    timeout=10,
)
print(res.status_code, res.json())
```

## 2. Um link por cliente

Crie um link com o `externalId` do cliente e mande a `url` a ele. A `url` sai **uma vez**: guarde ou envie na hora. O cliente abre a página da Luna, aceita os termos da Meta e conecta o número dele. Com `redirectUrl` (https), a página o devolve ao seu produto quando a conexão termina.

> **Testando no teste grátis.** O teste tem capacidade para 1 número. Se esse número já está conectado, `POST /v1/onboarding/links` responde `409` com `error: "number_capacity_reached"`, mesmo com o corpo certo: a capacidade é conferida antes de tudo. Para ver o fluxo do link de ponta a ponta, desconecte o número (`DELETE /v1/numbers/{id}`, veja a seção 8) e crie o link para o cliente de teste, ou peça a ampliação da capacidade em contato@lunahia.com.br.

```bash
curl -X POST "https://api.lunahia.com.br/v1/onboarding/links" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "externalId": "cliente-42",
  "redirectUrl": "https://app.example.com/whatsapp/conectado"
}'
```

```js
const res = await fetch('https://api.lunahia.com.br/v1/onboarding/links', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LUNA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "externalId": "cliente-42",
    "redirectUrl": "https://app.example.com/whatsapp/conectado"
  }),
});
console.log(res.status, await res.json());
```

```python
import os
import requests

res = requests.post(
    "https://api.lunahia.com.br/v1/onboarding/links",
    headers={
        "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}",
    },
    json={
        "externalId": "cliente-42",
        "redirectUrl": "https://app.example.com/whatsapp/conectado",
    },
    timeout=10,
)
print(res.status_code, res.json())
```

Para os 20 clientes de uma vez, um laço sobre a sua lista. O script abaixo lê `customers.json`, cria um link por cliente e imprime as URLs; um `409` de capacidade aparece no terminal e o laço segue.

create-links.mjs (Node 18 ou mais novo)

```js
// create-links.mjs: one connect link per customer of yours.
import { readFile } from 'node:fs/promises';

const API = 'https://api.lunahia.com.br';
const customers = JSON.parse(await readFile('./customers.json', 'utf8'));
// customers.json: [{ "externalId": "cliente-1" }, { "externalId": "cliente-2" }]

for (const customer of customers) {
  const res = await fetch(`${API}/v1/onboarding/links`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.LUNA_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      externalId: customer.externalId,
      // where the link page sends your customer back to when the connection ends
      redirectUrl: `https://app.example.com/whatsapp/done?customer=${customer.externalId}`,
    }),
  });

  if (!res.ok) {
    // 409 number_capacity_reached: the plan is full. Disconnect a number or ask for more capacity.
    console.error(customer.externalId, res.status, await res.json());
    continue;
  }

  const link = await res.json();
  // The url is returned ONCE. Send it to the customer now.
  console.log(customer.externalId, link.url);
}

```

Quando a conexão termina, a página leva o cliente à sua `redirectUrl` e acrescenta na query `status` (o estado final da conexão), `externalId` (o rótulo do link), `numberId` (o número, quando a Luna já o registrou; logo depois de concluir ele costuma vir vazio e some da query) e `signature`:

```text
https://app.example.com/whatsapp/conectado?status=APP_SUBSCRIBED&externalId=cliente-8841&signature=t%3D1793800000%2Cv1%3D9f2c...
```

### Confira que o retorno veio da Luna

Qualquer pessoa pode abrir a sua `redirectUrl` com um `status` inventado. A `signature` prova que a Luna montou aqueles valores: é a **mesma assinatura dos webhooks** (`t=<t>,v1=<hmac>`), feita com o segredo do endpoint de webhook mais antigo da sua conta (o mesmo `whsec_` que você já usa para validar eventos), sobre o texto `status=<status>&numberId=<numberId>&externalId=<externalId>`, com os valores como estão na query (vazios quando ausentes). O instante vale 5 minutos: confira ao receber o cliente, e não depois. Sem endpoint de webhook cadastrado, a `signature` não vai, e nesse caso trate o retorno como não confiável e leia o estado em `GET /v1/numbers`.

```js
import { verifyLunaSignature } from './verify.mjs';

// a mesma conferência de um webhook, sobre o texto que a página do link assinou (os valores como estão na query)
export function verifyConnectionReturn(returnUrl, secret, nowMs = Date.now()) {
  const q = new URL(returnUrl).searchParams;
  const text = `status=${q.get('status') ?? ''}&numberId=${q.get('numberId') ?? ''}&externalId=${q.get('externalId') ?? ''}`;
  return verifyLunaSignature(Buffer.from(text), q.get('signature'), secret, nowMs);
}
```

```python
from urllib.parse import parse_qs, urlparse

from verify import verify_luna_signature


def verify_connection_return(return_url, secret, now=None):
    # a mesma conferência de um webhook, sobre o texto que a página do link assinou (os valores como estão na query)
    q = {k: v[0] for k, v in parse_qs(urlparse(return_url).query).items()}
    text = f"status={q.get('status', '')}&numberId={q.get('numberId', '')}&externalId={q.get('externalId', '')}"
    return verify_luna_signature(text.encode(), q.get("signature"), secret, now)
```

O cliente também pode ser reconhecido na página: mande `displayName` (de 1 a 120 caracteres) em `POST /v1/onboarding/links` e ela mostra "Conexão do WhatsApp de ..." acima do título. **O nome que a janela da Meta mostra não dá para mudar:** a janela é da Meta e mostra o nome da Luna e do negócio, e não o do seu cliente.

Para achar o link de um cliente, filtre pelo rótulo:

```bash
curl -X GET "https://api.lunahia.com.br/v1/onboarding/links?externalId=cliente-42" \
  -H "Authorization: Bearer $LUNA_API_KEY"
```

```js
const res = await fetch('https://api.lunahia.com.br/v1/onboarding/links?externalId=cliente-42', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.LUNA_API_KEY}`,
  },
});
console.log(res.status, await res.json());
```

```python
import os
import requests

res = requests.get(
    "https://api.lunahia.com.br/v1/onboarding/links?externalId=cliente-42",
    headers={
        "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}",
    },
    timeout=10,
)
print(res.status_code, res.json())
```

O link vale 72 horas, abre uma vez e se revoga com `DELETE /v1/onboarding/links/{id}`. Mais sobre o fluxo do cliente e a coexistência em [Conectar um número](https://lunahia.com.br/docs/conectar-numero).

## 3. Todos os eventos num endpoint só

O caminho recomendado é **um endpoint** para todos os clientes. Cadastre-o como em [Receber eventos](https://lunahia.com.br/docs/receber-eventos), verifique a assinatura, e separe os clientes por `number.external_id`. Quatro eventos contam a conexão de um cliente, e todos trazem o `externalId`:

| Evento | O que diz |
| --- | --- |
| `onboarding.link.completed` | O cliente concluiu a conexão por um link. |
| `onboarding.link.failed` | Uma tentativa não deu certo, com `reason` (abandonou, erro da Meta, número fora do +55, registro bloqueado) e `step`, a tela em que ele parou. |
| `onboarding.link.expired` | O link venceu sem uso. Gere outro. |
| `number.connected` | O número ficou pronto: já pode enviar e receber. |

number.connected

```json
{
  "version": "2026-11-10",
  "event_id": "458470a340db14358f03ac02fde7e3839cb6887f3071c06c57a3d9d456621996",
  "event_type": "number.connected",
  "occurred_at": "2026-10-07T13:45:00.000Z",
  "phone_number_id": "123456789012345",
  "number": {
    "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "phone_number_id": "123456789012345",
    "display_number": "+55 11 90000-0000",
    "external_id": "cliente-8841",
    "waba_id": "102290129340398",
    "coexistence": false
  }
}
```

O roteador abaixo é a parte do seu servidor que decide a quem o evento pertence. Chame-o depois de verificar a assinatura; ele descarta repetições pelo `event_id` e ignora o rótulo que você não conhece (responda `2xx` em qualquer caso).

router.mjs

```js
// router.mjs: one webhook endpoint for all your customers.
// Call route(event) AFTER verifying the signature (see the Receive events guide).

/** externalId -> { onEvent(event) } for each customer of yours. */
export function createRouter(handlers) {
  const seen = new Set();

  return function route(event) {
    // The same delivery can arrive more than once: drop repeats by event_id.
    if (seen.has(event.event_id)) return 'duplicate';
    seen.add(event.event_id);

    // number.external_id is on every event that goes through a number;
    // link events carry it in link.external_id.
    const customer = event.number?.external_id ?? event.link?.external_id ?? null;
    if (customer === null) return 'no-customer';

    const handler = handlers.get(customer);
    // A label you do not know, or an event type you do not handle: answer 2xx anyway.
    if (handler === undefined) return 'unknown-customer';

    handler.onEvent(event);
    return 'handled';
  };
}

```

### Onde está o externalId em cada evento

| Evento | Onde vem o externalId |
| --- | --- |
| Mensagens e contatos: `message.received`, `message.status`, `message.echo`, `contact.*`, `backlog.dropped`, `history_sync.deadline_approaching` | `number.external_id` |
| `number.*` (conectou, desconectou, qualidade, pagamento, ação, credencial, nome) e `account.*` | `number.external_id` |
| `onboarding.link.completed` | `link.external_id`, e `number.external_id` do número que acabou de conectar |
| Os outros do link: `onboarding.link.opened`, `onboarding.link.failed`, `onboarding.link.expired` | `link.external_id` (ainda não há número) |
| Templates e o teste: `template.status`, `template.category`, `template.quality`, `webhook.test` | Em lugar nenhum: são da conta de negócio ou do teste, e não de um cliente. O roteador devolve `no-customer`, e só um endpoint sem filtro os recebe. |

O `number.external_id` é `null` num número que nunca recebeu rótulo. Esse caso, e os eventos da última linha, são o `no-customer` do roteador: trate-os à parte, ou ignore.

> **Um endpoint único é um ponto único de falha.** Se ele cair ou ficar lento, as entregas de **todos** os clientes esperam juntas: cinco falhas seguidas abrem o disjuntor desse endpoint, e quando ele volta o acumulado de todos chega de uma vez (veja [Receber eventos](https://lunahia.com.br/docs/receber-eventos#retentativas)). Com poucos clientes e um servidor que só grava e responde `200`, isso raramente pesa. Se o código de um cliente costuma falhar ou demorar, ou se um cliente não pode ser atrasado pelo outro, use **um endpoint por cliente** (seção 7): a falha de um não atrasa os demais.

### Um servidor completo em TypeScript

O arquivo abaixo junta tudo: verifica a assinatura, responde `200`, descarta a repetição e entrega cada evento ao código do cliente certo, por um `Map`. Os tipos mostram que `external_id` pode ser `null`. Rode com `node server.ts` (Node 24 ou mais novo, que apaga os tipos sozinho) e `LUNA_WEBHOOK_SECRET` definida.

server.ts

```ts
// server.ts: run with Node 24 or newer: node server.ts
import crypto from 'node:crypto';
import http from 'node:http';

// Os campos do evento que este arquivo lê (há mais: veja Receber eventos).
interface LunaEvent {
  event_id: string;
  event_type: string;
  number?: { id: string; phone_number_id: string; external_id: string | null } | null; // external_id: null num número que nunca recebeu rótulo
  link?: { id: string; external_id: string | null } | null;
}

// 1. Verifique a assinatura (a explicação está no guia Receber eventos).
const SECRET = process.env.LUNA_WEBHOOK_SECRET ?? '';
const TOLERANCE_SECONDS = 300;

function verify(raw: Buffer, header: string | undefined): boolean { // raw: os bytes exatos que chegaram, nunca o JSON reserializado
  const m = /^t=(\d{1,15}),/.exec(header ?? '');
  if (!m || !SECRET) return false;
  const t = Number(m[1]);
  if (Math.abs(Math.floor(Date.now() / 1000) - t) > TOLERANCE_SECONDS) return false;

  const expected = crypto.createHmac('sha256', SECRET).update(`${t}.`).update(raw).digest();
  let ok = 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 as string, 'hex'), expected)) ok = true;
  }
  return ok;
}

// 2. Os clientes: externalId -> o código que trata aquele cliente.
type CustomerHandler = (event: LunaEvent) => void | Promise<void>;

const customers = new Map<string, CustomerHandler>([
  ['cliente-1', (event) => console.log('cliente-1', event.event_type)],
  ['cliente-2', (event) => console.log('cliente-2', event.event_type)],
]);

const seen = new Set<string>(); // em produção: um banco ou Redis, com prazo de validade

function route(event: LunaEvent): 'duplicate' | 'no-customer' | 'unknown-customer' | 'handled' {
  if (seen.has(event.event_id)) return 'duplicate';
  seen.add(event.event_id);

  // number.external_id nos eventos de um número; link.external_id nos eventos de um link
  const customer = event.number?.external_id ?? event.link?.external_id ?? null;
  if (customer === null) return 'no-customer';

  const handler = customers.get(customer);
  if (handler === undefined) return 'unknown-customer'; // um rótulo que você não conhece: responda 2xx do mesmo jeito

  void Promise.resolve(handler(event)).catch((err) => console.error(customer, 'handler failed', err));
  return 'handled';
}

// 3. O servidor: verifique, responda e só então roteie.
http
  .createServer((req, res) => {
    const chunks: Buffer[] = [];
    req.on('data', (chunk: Buffer) => chunks.push(chunk));
    req.on('end', () => {
      const raw = Buffer.concat(chunks);
      const header = req.headers['x-luna-signature'];
      if (!verify(raw, typeof header === 'string' ? header : undefined)) {
        res.writeHead(401).end();
        return;
      }
      res.writeHead(200).end(); // responda primeiro, trabalhe depois
      console.log(route(JSON.parse(raw.toString('utf8')) as LunaEvent));
    });
  })
  .listen(Number(process.env.PORT ?? 3000));

```

## 4. Enviar por número

Ache os números do cliente pelo rótulo e envie por um deles. `from` aceita o UUID da Luna ou o id da Meta. `?canSend=true` devolve só os números por onde enviar funciona agora.

```bash
curl -X GET "https://api.lunahia.com.br/v1/numbers?externalId=cliente-42&canSend=true" \
  -H "Authorization: Bearer $LUNA_API_KEY"
```

```js
const res = await fetch('https://api.lunahia.com.br/v1/numbers?externalId=cliente-42&canSend=true', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.LUNA_API_KEY}`,
  },
});
console.log(res.status, await res.json());
```

```python
import os
import requests

res = requests.get(
    "https://api.lunahia.com.br/v1/numbers?externalId=cliente-42&canSend=true",
    headers={
        "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}",
    },
    timeout=10,
)
print(res.status_code, res.json())
```

```bash
curl -X POST "https://api.lunahia.com.br/v1/messages" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "from": "YOUR_NUMBER_ID",
  "to": "5511900000000",
  "type": "text",
  "text": {
    "body": "Seu pedido saiu para entrega."
  }
}'
```

```js
const res = await fetch('https://api.lunahia.com.br/v1/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LUNA_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    "from": "YOUR_NUMBER_ID",
    "to": "5511900000000",
    "type": "text",
    "text": {
      "body": "Seu pedido saiu para entrega."
    }
  }),
});
console.log(res.status, await res.json());
```

```python
import os
import uuid
import requests

res = requests.post(
    "https://api.lunahia.com.br/v1/messages",
    headers={
        "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "from": "YOUR_NUMBER_ID",
        "to": "5511900000000",
        "type": "text",
        "text": {
            "body": "Seu pedido saiu para entrega.",
        },
    },
    timeout=10,
)
print(res.status_code, res.json())
```

O histórico e as conversas também filtram pelo cliente, e o envio fora da janela de 24 horas é só por template. Veja [Enviar mensagens](https://lunahia.com.br/docs/enviar-mensagens) e [Templates](https://lunahia.com.br/docs/templates). Com uma conta de negócio por cliente, `GET /v1/templates?wabaId=` ou `?phoneNumberId=` mostra os templates de cada um.

```bash
curl -X GET "https://api.lunahia.com.br/v1/messages?externalId=cliente-42&limit=20" \
  -H "Authorization: Bearer $LUNA_API_KEY"
```

```js
const res = await fetch('https://api.lunahia.com.br/v1/messages?externalId=cliente-42&limit=20', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.LUNA_API_KEY}`,
  },
});
console.log(res.status, await res.json());
```

```python
import os
import requests

res = requests.get(
    "https://api.lunahia.com.br/v1/messages?externalId=cliente-42&limit=20",
    headers={
        "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}",
    },
    timeout=10,
)
print(res.status_code, res.json())
```

## 5. O estado de cada número

Para mostrar ao cliente se o número dele está bem, leia `connection` (a mesma conta que decide os eventos): `status` (`connected`, `connecting`, `action_required` ou `disconnected`), `canSend` e `reasons`, cada motivo com `code`, `message` e `solution` em português, prontos para repassar.

```bash
curl -X GET "https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID" \
  -H "Authorization: Bearer $LUNA_API_KEY"
```

```js
const res = await fetch('https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.LUNA_API_KEY}`,
  },
});
console.log(res.status, await res.json());
```

```python
import os
import requests

res = requests.get(
    "https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID",
    headers={
        "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}",
    },
    timeout=10,
)
print(res.status_code, res.json())
```

Resposta (resumida)

```json
{
  "id": "ed404df1-b420-4ed6-8743-ba1609892e0a",
  "metaPhoneNumberId": "123456789012345",
  "externalId": "cliente-42",
  "state": "REGISTERED",
  "ready": true,
  "connection": {
    "status": "connected",
    "canSend": true,
    "reasons": []
  }
}
```

Você não precisa consultar os 20 números: `number.action_required` avisa quando um passa a precisar de ação (autorização vencendo, método de pagamento ausente na Meta, conta restrita), e `number.action_resolved` avisa quando deixa de precisar. A lista de números aceita `?state=`, `?ready=`, `?canSend=`, `?limit=` e `?cursor=` para montar o painel de todos de uma vez.

number.action_required

```json
{
  "version": "2026-11-10",
  "event_id": "8832cdd12544436fce3b39d709158baa046091d010b5ed144a289c81b807c710",
  "event_type": "number.action_required",
  "occurred_at": "2026-10-28T15:02:00.000Z",
  "phone_number_id": "123456789012345",
  "number": {
    "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "phone_number_id": "123456789012345",
    "display_number": "+55 11 90000-0000",
    "external_id": "cliente-8841",
    "status": "action_required",
    "can_send": false,
    "reasons": [
      {
        "code": "payment_required",
        "message": "A Meta recusou um envio deste número por falta de método de pagamento na conta de WhatsApp Business do negócio.",
        "solution": "O dono da conta cadastra o método de pagamento no WhatsApp Manager da Meta. A Luna não intermedeia esse pagamento. Quando um envio voltar a ser aceito, o aviso sai do ar."
      }
    ]
  }
}
```

Autorização perto de vencer é o caso que se repete: abra um link de reconexão com `POST /v1/onboarding/links` informando `numberId`, e o cliente renova sem contar um número novo. Os casos estão em [Saúde da conta](https://lunahia.com.br/docs/saude-da-conta) e [Pagamento na Meta](https://lunahia.com.br/docs/pagamento-na-meta).

## 6. Uma chave por cliente

Se o cliente do seu cliente acessa a API diretamente, ou se você quer reduzir o estrago de uma chave vazada, crie uma chave com `externalId`. Ela só lê e envia pelos números com aquele rótulo (inclusive os conectados depois), só cria link com ele, só vê os templates e as contas de negócio desses números, e **não** lista nem cria endpoints de webhook nem chaves, nem lê o plano. O número de outro cliente responde `404`, igual a um que não existe, mesmo que o id dele seja passado de propósito; uma rota fora do conjunto responde `403`. O `externalId` de uma chave não muda: para mudar, crie outra.

**Quem cria a chave precisa do escopo `keys:write`.** A chave que você usa para chamar `POST /v1/api-keys` tem de tê-lo (no console, a sessão ganha esse poder por duas horas depois de você confirmar a senha). Sem o escopo, a resposta é `403`, e o corpo diz qual falta: `requiredScope: "keys:write"`. Os escopos da chave nova são escolhidos por você, dentro do que a chave de um cliente pode usar (mensagens, números, templates e o link de conexão).

```bash
curl -X POST "https://api.lunahia.com.br/v1/api-keys" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "Clínica Exemplo",
  "scopes": [
    "messages:read",
    "messages:write",
    "numbers:read"
  ],
  "externalId": "cliente-42"
}'
```

```js
const res = await fetch('https://api.lunahia.com.br/v1/api-keys', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LUNA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "label": "Clínica Exemplo",
    "scopes": [
      "messages:read",
      "messages:write",
      "numbers:read"
    ],
    "externalId": "cliente-42"
  }),
});
console.log(res.status, await res.json());
```

```python
import os
import requests

res = requests.post(
    "https://api.lunahia.com.br/v1/api-keys",
    headers={
        "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}",
    },
    json={
        "label": "Clínica Exemplo",
        "scopes": [
            "messages:read",
            "messages:write",
            "numbers:read",
        ],
        "externalId": "cliente-42",
    },
    timeout=10,
)
print(res.status_code, res.json())
```

A resposta `201` traz o `secret` da chave (`hlsn_...`) **uma única vez**: guarde-o agora, no seu banco, na linha daquele cliente, junto do `externalId`. Não há rota que o devolva depois; se você o perder, revogue a chave (`POST /v1/api-keys/{id}/revoke`) e crie outra.

## 7. Um webhook por cliente (opcional)

Se o seu produto prefere uma URL por cliente, o endpoint aceita `externalIds` (e `phoneNumberIds`): ele só recebe os eventos de números com aquele rótulo, inclusive os conectados depois, e os eventos de link dele. Ausentes, ele recebe de todos. O `external_id` continua em todo evento, nos dois jeitos. A assinatura, a ordem, o reenvio e a fila de rejeitados são os de qualquer endpoint.

```bash
curl -X POST "https://api.lunahia.com.br/v1/webhooks/endpoints" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://saas.example.com/luna/cliente-42",
  "externalIds": [
    "cliente-42"
  ]
}'
```

```js
const res = await fetch('https://api.lunahia.com.br/v1/webhooks/endpoints', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LUNA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "url": "https://saas.example.com/luna/cliente-42",
    "externalIds": [
      "cliente-42"
    ]
  }),
});
console.log(res.status, await res.json());
```

```python
import os
import requests

res = requests.post(
    "https://api.lunahia.com.br/v1/webhooks/endpoints",
    headers={
        "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}",
    },
    json={
        "url": "https://saas.example.com/luna/cliente-42",
        "externalIds": [
            "cliente-42",
        ],
    },
    timeout=10,
)
print(res.status_code, res.json())
```

```bash
curl -X PATCH "https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ENDPOINT_ID" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "externalIds": [
    "cliente-42",
    "cliente-43"
  ]
}'
```

```js
const res = await fetch('https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ENDPOINT_ID', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.LUNA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "externalIds": [
      "cliente-42",
      "cliente-43"
    ]
  }),
});
console.log(res.status, await res.json());
```

```python
import os
import requests

res = requests.patch(
    "https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ENDPOINT_ID",
    headers={
        "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}",
    },
    json={
        "externalIds": [
            "cliente-42",
            "cliente-43",
        ],
    },
    timeout=10,
)
print(res.status_code, res.json())
```

> Cada conta pode ter até **25 endpoints**, o mesmo limite para todos, de infraestrutura: um por cliente de um plano de 20 números, com folga. O endpoint com filtro de um cliente não recebe os eventos de outro; um evento que não diz sobre quem fala só chega a endpoint sem filtro.

## 8. Desconectar e trocar o cliente

O cliente 21 entra no lugar do 3? Desconecte o número do 3 com `DELETE /v1/numbers/{id}`: ele sai da Luna, para de contar na capacidade e o evento `number.disconnected` avisa (`reason: "requested_by_tenant"`). A Luna não chama `deregister` na Meta, para não derrubar o número do cliente em outro provedor ou no aplicativo. O histórico fica. Para reaproveitar um número para outro cliente seu, troque o rótulo com `PATCH /v1/numbers/{id}`.

```bash
curl -X DELETE "https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID" \
  -H "Authorization: Bearer $LUNA_API_KEY"
```

```js
const res = await fetch('https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.LUNA_API_KEY}`,
  },
});
console.log(res.status);
```

```python
import os
import requests

res = requests.delete(
    "https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID",
    headers={
        "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}",
    },
    timeout=10,
)
print(res.status_code)
```

```bash
curl -X PATCH "https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "externalId": "cliente-43"
}'
```

```js
const res = await fetch('https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.LUNA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "externalId": "cliente-43"
  }),
});
console.log(res.status, await res.json());
```

```python
import os
import requests

res = requests.patch(
    "https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID",
    headers={
        "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}",
    },
    json={
        "externalId": "cliente-43",
    },
    timeout=10,
)
print(res.status_code, res.json())
```

## Em uma tabela

| O que o seu produto faz | Como na Luna |
| --- | --- |
| Entrar um cliente | `POST /v1/onboarding/links` com `externalId` e `redirectUrl` |
| Saber que ele conectou | `onboarding.link.completed` e `number.connected` |
| Saber que ele desistiu | `onboarding.link.failed` e `onboarding.link.expired` |
| Enviar | `POST /v1/messages` com `from` (UUID da Luna ou id da Meta) |
| Receber de todos | Um endpoint e o `number.external_id` de cada evento |
| Mostrar o estado | `connection` e `number.action_required` / `number.action_resolved` |
| Dar acesso direto ao cliente | `POST /v1/api-keys` com `externalId` |
| Uma URL por cliente | `externalIds` no endpoint de webhook |
| Sair um cliente | `DELETE /v1/numbers/{id}` |
| Ver a capacidade | `GET /v1/subscription` |

> Vindo da Z-API ou da Evolution API? A página [Vindo da Z-API ou da Evolution](https://lunahia.com.br/migrar-da-evolution-api) traduz cada verbo da instância para esta lista.

## Detalhes das rotas deste guia

A [referência da API](https://lunahia.com.br/docs/referencia) diz como chamar cada rota, em poucas linhas. O que explica o motivo de cada decisão, os casos de borda e os avisos está aqui, na ordem da referência.

### GET /v1/onboarding/links

Cada um traz o status (open, used, expired ou revoked), o externalId que você deu e, depois que o cliente conecta, o numberId do número que resultou. Traz também createdAt, purpose (new para um número novo, reconnect para renovar a autorização de um número que já existe), revokedAt, lastFailure (a última tentativa que não deu certo, com step, reason e at, os mesmos do evento onboarding.link.failed, ou nulo) e allowedActions (revoke, só num link aberto). Nenhum traz o token nem a url: ela só saiu na criação.

Use ?externalId= para achar os links de um cliente seu: a comparação é exata, e um rótulo sem link devolve lista vazia. Use ?status= (open, used, expired ou revoked) para filtrar pelo estado. Os links revogados continuam na lista.

Para paginar, mande de volta o nextCursor da resposta anterior em cursor. Nulo significa fim.

### POST /v1/onboarding/links

A janela de conexão da Meta só abre em domínio cadastrado no aplicativo da Luna. Por isso o link aponta para uma página do console da Luna, que mostra o nome da sua conta, explica o que será pedido e abre a janela da Meta para o seu cliente. Quem entra com o Facebook e aceita os termos da Meta é o negócio dele, e não você em nome dele.

externalId é o seu identificador para este cliente, em texto livre de 1 a 128 caracteres. Ele fica no link e no número que resultar da conexão, e volta em GET /v1/numbers.

redirectUrl, opcional, é para onde a página do link leva o seu cliente quando a conexão termina (https). A página acrescenta na query status (o estado final da conexão), externalId (o rótulo do link), numberId (o número, quando a Luna já o registrou; logo depois de concluir ele costuma vir vazio e então não vai, e o evento number.connected avisa quando fica pronto) e signature, a assinatura de webhook sobre status, numberId e externalId com o segredo do seu endpoint de webhook mais antigo, para você conferir que o retorno veio da Luna (código em SaaS com N clientes). Sem redirectUrl, o cliente fica na página da Luna.

displayName, opcional, é o nome do seu cliente (de 1 a 120 caracteres) que a página do link mostra para ele reconhecer o pedido. A janela da Meta que abre em seguida mostra o nome da Luna e do negócio, e esse nome não dá para mudar.

O ciclo do link também chega por webhook: onboarding.link.completed quando o cliente conclui, onboarding.link.failed quando uma tentativa não dá certo (com o motivo e a tela em que ele parou) e onboarding.link.expired quando o link vence sem uso, todos com o externalId.

O link vale 72 horas para ser aberto. A resposta traz a url uma única vez: guarde-a ou envie-a agora, porque nenhuma rota devolve o token de novo. Quem tem a url pode conectar um número à sua conta, então trate-a como um segredo e mande-a só ao cliente certo.

numberId é opcional e transforma o link em link de RECONEXÃO: a página do seu cliente abre direto a renovação da autorização daquele número, sem contar um número novo. Use quando credentialStatus for reauth_required, ou quando o evento number.credential_expiring avisar que a autorização vence em até 14 dias. As regras são as de POST /v1/onboarding/reconnect: número seu e com autorização que admite reconexão (podeReconectar true); caso contrário responde 409, e número que não é seu responde 404. Sem externalId, o link herda o do número.

Para acompanhar, use GET /v1/onboarding/links/{id}, ou liste os números com ?externalId=. Para cancelar, use DELETE /v1/onboarding/links/{id}.

As mesmas condições de POST /v1/onboarding/sessions valem aqui: a conta precisa ter o e-mail confirmado.

### GET /v1/onboarding/links/{id}

Quem avisa que o seu cliente terminou é o evento number.connected, entregue no seu endpoint de webhook com o externalId do cliente. Esta leitura é a reserva, para o caso de o seu endpoint ter estado fora do ar, e não um laço de espera: não é preciso consultar de tempos em tempos. Quando o status vira used, usedAt traz o instante e numberId traz o número que resultou. O numberId aparece alguns instantes depois do used, porque a Luna registra o número em seguida; nulo no used significa que a conta foi conectada sem número.

Um link que você revogou continua aqui, com status revoked e revokedAt. Quem abre a url dele recebe 404, como se nunca tivesse existido.

### DELETE /v1/onboarding/links/{id}

Funciona também em link já usado ou vencido, e aí só o marca como revogado: o número conectado e o externalId dele continuam. O link fica na sua lista com status revoked. Revogar de novo um link já revogado responde 404.

### GET /v1/public/onboarding-links/{token}

O token é a credencial, e não há chave de API. Token desconhecido, malformado ou revogado responde 404, sempre igual. Um link vencido ou já usado responde 200 com o status, para a página poder dizer ao cliente que peça um novo.

A rota tem teto por endereço de origem.

### POST /v1/public/onboarding-links/{token}/sessions

Num link de reconexão (criado com numberId), a sessão já nasce amarrada à conta do número, como em POST /v1/onboarding/reconnect.

Pode ser chamada mais de uma vez enquanto o link está aberto: o cliente que fecha a janela da Meta tenta de novo. Link vencido ou já usado responde 410 com o motivo. Qualquer outro token inválido responde 404. A rota tem teto por endereço de origem.

### POST /v1/public/onboarding-links/{token}/sessions/{sessionId}/complete

Só conclui uma sessão aberta por este mesmo link. Quando a conexão conclui, o link passa a used, e o externalId dele vai para o número. Se o número escolhido não é +55, o estado é COUNTRY_NOT_SUPPORTED, nada é conectado e o link continua aberto para um número brasileiro.

Responde 200 mesmo quando um passo falha: o corpo traz o estado e a orientação. A rota tem teto por endereço de origem.

### POST /v1/public/onboarding-links/{token}/sessions/{sessionId}/abandon

Não muda o estado da sessão. A rota tem teto por endereço de origem.
