# Modo de teste

Fonte: https://lunahia.com.br/docs/modo-de-teste

Para montar e testar a sua integração sem mandar mensagem de verdade, crie uma chave de teste. Com ela, enviar uma mensagem não vai à Meta, não usa número seu e não conta na capacidade do plano: a Luna devolve o mesmo `202` e entrega ao seu webhook os eventos que a Meta mandaria, simulados, assinados e marcados com `test: true`.

A [referência da API](https://lunahia.com.br/docs/referencia) traz cada rota e cada campo. Este guia explica o que ela não cabe em poucas linhas: o que a chave de teste alcança, o que sai e quando, e o que o modo de teste não simula.

## Criar a chave de teste

`POST /v1/api-keys` com `mode: "test"`. A resposta traz o segredo uma única vez, como em qualquer chave. O campo `mode` aparece também na lista de chaves (`live` ou `test`) e **não muda depois**: para sair do modo de teste, use outra chave.

```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": "teste da integração",
  "profile": "agent",
  "mode": "test"
}'
```

```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": "teste da integração",
    "profile": "agent",
    "mode": "test"
  }),
});
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": "teste da integração",
        "profile": "agent",
        "mode": "test",
    },
    timeout=10,
)
print(res.status_code, res.json())
```

- A chave de teste é da conta inteira: `externalId` junto com `mode: "test"` responde `400`.
- Ela **só usa duas rotas**: `POST /v1/messages` e `POST /v1/test-mode/inbound-messages`. Em qualquer outra, a resposta é `403` com `error: "test_key_not_allowed"`, antes de validar o corpo. É isso que garante que ela nunca lê nem muda número, conta ou template, e que nunca chega à Meta.
- Os escopos valem como em qualquer chave: o envio pede `messages:write`. O perfil `agent` já o tem.
- A chave de teste não é um número e **não conta na capacidade do plano**.

## Enviar e receber os estados

Envie como sempre, com a chave de teste. O corpo é validado pelo mesmo contrato do envio de verdade (um corpo inválido responde `400`), e `from` é um texto livre: a Luna não procura o número, então use o `phone_number_id` que o seu código usará em produção.

```bash
curl -X POST "https://api.lunahia.com.br/v1/messages" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "from": "1000000000000001",
  "to": "5511900000000",
  "type": "text",
  "text": {
    "body": "Olá! Esta mensagem é de teste."
  }
}'
```

```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',
  },
  body: JSON.stringify({
    "from": "1000000000000001",
    "to": "5511900000000",
    "type": "text",
    "text": {
      "body": "Olá! Esta mensagem é de teste."
    }
  }),
});
console.log(res.status, await res.json());
```

```python
import os
import requests

res = requests.post(
    "https://api.lunahia.com.br/v1/messages",
    headers={
        "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}",
    },
    json={
        "from": "1000000000000001",
        "to": "5511900000000",
        "type": "text",
        "text": {
            "body": "Olá! Esta mensagem é de teste.",
        },
    },
    timeout=10,
)
print(res.status_code, res.json())
```

Resposta `202`, igual à do envio de verdade

```json
{
  "id": "ae60f288-7565-4315-a440-3663e9c231e1",
  "status": "queued"
}
```

Depois do `202`, a Luna entrega aos seus endpoints de webhook três eventos `message.status`, na ordem: `sent` (cerca de 0,3 segundo depois), `delivered` (cerca de 1 segundo) e `read` (cerca de 2 segundos). Os tempos são aproximados. O `id` do evento é o que o `202` devolveu.

O evento `sent`

```json
{
  "version": "2026-11-10",
  "event_id": "bda40971d61ae76b36ab297565598f9427fd64ef16af8a62d201c8f596eb1006",
  "event_type": "message.status",
  "occurred_at": "2026-11-03T15:00:00.300Z",
  "phone_number_id": "1000000000000001",
  "test": true,
  "number": {
    "id": "03af3f4b-3a6f-4867-880f-eb5e847a6a8f",
    "phone_number_id": "1000000000000001",
    "external_id": null
  },
  "message": {
    "id": "ae60f288-7565-4315-a440-3663e9c231e1",
    "wamid": "wamid.TESTE_ae60f28875654315a4403663e9c231e1",
    "wa_id": "5511900000000",
    "user_id": null,
    "parent_user_id": null,
    "username": null,
    "status": "sent",
    "error_code": null,
    "error": null,
    "pricing": null
  }
}
```

- **`test: true` no envelope.** É o que separa o evento simulado de um de verdade. Se o seu código age sobre o evento, confira esse campo.
- Sai **assinado** com o segredo do seu endpoint, com os mesmos cabeçalhos e a mesma assinatura de uma entrega real. Quem verifica a assinatura de verdade verifica a deste evento. Veja [Receber eventos](https://lunahia.com.br/docs/receber-eventos).
- O `wamid` começa com `wamid.TESTE_`, para nunca se confundir com um da Meta. O `number.id` é um identificador de mentira, estável para o mesmo `phone_number_id`, e `number.external_id` é nulo.
- `pricing` vem nulo: a mensagem não foi à Meta, então ninguém a classificou.

**Quem recebe:** os endpoints ativos, sem filtro de cliente nem de número, que aceitam o tipo do evento. Um endpoint pausado, ou restrito a clientes ou a números, não recebe o evento simulado. A entrega é de **uma tentativa só**: não há reenvio, o evento não vai para a fila de rejeitados e uma falha dele não pausa o endpoint. Sem nenhum endpoint, o `202` sai do mesmo jeito e nada chega.

## Simular uma falha de envio

Três números em `to` fazem o envio de teste terminar em `failed`, para você ver o seu código tratar a recusa sem gastar um número de verdade. Para eles sai **um único** `message.status`, com `status: "failed"`, `error_code` e `error` (`code`, `title` e `message`) no formato do erro que a Meta informa. Não saem `sent`, `delivered` nem `read`.

- `5511900009901`: `failed` com o erro `131026` (mensagem não entregável: o número não tem WhatsApp, ou não aceitou os termos).
- `5511900009902`: `failed` com o erro `131047` (a janela de 24 horas está fechada: só vale um template).
- `5511900009903`: `failed` com o erro `131049` (a Meta não entregou para preservar a saúde do ecossistema, o limite de marketing por pessoa).

Só a chave de teste tem esse comportamento. Com a chave de produção, esses números não têm nada de especial: o envio segue o caminho de sempre.

## Simular uma mensagem recebida

`POST /v1/test-mode/inbound-messages` entrega aos seus endpoints **uma** `message.received` de exemplo, em cerca de meio segundo, para você exercitar o fluxo de atendimento sem esperar um contato escrever. O corpo é opcional: `text` (o texto), `waId` (o telefone de quem "escreveu", só dígitos) e `phoneNumberId` (o que aparece no evento). Ausentes, valem um texto de exemplo, `5511900000000` e `123456789012345`.

```bash
curl -X POST "https://api.lunahia.com.br/v1/test-mode/inbound-messages" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "Quero a segunda via do boleto"
}'
```

```js
const res = await fetch('https://api.lunahia.com.br/v1/test-mode/inbound-messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LUNA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "text": "Quero a segunda via do boleto"
  }),
});
console.log(res.status, await res.json());
```

```python
import os
import requests

res = requests.post(
    "https://api.lunahia.com.br/v1/test-mode/inbound-messages",
    headers={
        "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}",
    },
    json={
        "text": "Quero a segunda via do boleto",
    },
    timeout=10,
)
print(res.status_code, res.json())
```

Resposta `202`

```json
{
  "id": "3f6a1c52-9d4e-4b87-a1f0-5e2c7b9d8a14",
  "wamid": "wamid.TESTE_3f6a1c529d4e4b87a1f05e2c7b9d8a14",
  "endpoints": 1
}
```

`endpoints` diz quantos dos seus endpoints vão receber o evento. Zero quer dizer que nada vai chegar: cadastre um endpoint. Esta rota aceita também a chave comum, e então faz o mesmo que `POST /v1/webhooks/endpoints/{id}/test` com `eventType: "message.received"`, só que para todos os endpoints de uma vez. Para exercitar os outros tipos de evento, use essa rota de teste do endpoint, que aceita qualquer tipo.

## O que o modo de teste não faz

- **Não grava nada.** A mensagem não aparece em `GET /v1/messages`, e a chave de teste nem lê essa rota. O `id` existe só nos eventos.
- **Não confere a janela de 24 horas, o template aprovado, as variáveis dele, o telefone do destinatário (+55) nem o número.** Por isso um envio que a produção recusaria com `409`, `400` ou `422` passa no modo de teste. Teste esses caminhos com um número de verdade.
- **Só simula as três falhas dos números mágicos.** Fora deles os estados são `sent`, `delivered` e `read`. Para outro `failed`, use `POST /v1/webhooks/endpoints/{id}/test` com `eventType: "message.status"` ou construa o evento a partir dos exemplos de [Receber eventos](https://lunahia.com.br/docs/receber-eventos).
- **Não é idempotente.** O cabeçalho `Idempotency-Key` é ignorado: cada envio gera um `id` novo e três eventos novos.
- **Os estados saem de um temporizador do processo da Luna.** Se o processo reiniciar entre um estado e outro, os que faltavam não saem. Repita o envio.
- Há um teto técnico de entregas simuladas agendadas ao mesmo tempo, igual para todos. Passou dele, a resposta é `429` com `Retry-After`. Espere o tempo indicado.
- Conta suspensa recusa o envio de teste como recusa o de verdade (`403`, veja [Plano e números](https://lunahia.com.br/docs/plano-e-numeros)).

## Passar para produção

Troque a chave de teste por uma chave comum. O resto do código é o mesmo, porque o envio e os eventos têm a mesma forma. Enquanto os dois ambientes convivem, descarte ou separe o que vem com `test: true`. Para usar o modo de teste no n8n ou com o SDK, veja [SDK e n8n](https://lunahia.com.br/docs/sdk-e-n8n).
