# Plano e números

Fonte: https://lunahia.com.br/docs/plano-e-numeros

O plano da Luna define uma coisa só: quantos números a sua conta pode manter ativos ao mesmo tempo. Este guia mostra como ler esse limite, o que fazer quando ele chega, e como abrir uma vaga.

## O teste grátis

Toda conta nova começa com um teste grátis de 14 dias, contados da confirmação do e-mail do cadastro, com capacidade para 1 número. Não precisa de liberação manual: depois de confirmar o e-mail, a conta conecta o número sozinha. A Helsen pode bloquear uma conta, e o bloqueio para a escrita e o envio como o fim do teste.

A cobrança automática ainda não existe. Para contratar um plano, ampliar a capacidade ou tirar a conta da suspensão, escreva para contato@lunahia.com.br. O uso da plataforma da Meta é pago pelo negócio dono do número, direto à Meta, e não entra em nada disso. Veja [Custos da Meta](https://lunahia.com.br/docs/custos-da-meta).

## Ler o plano e o uso

`GET /v1/subscription` devolve o plano da conta e quantos números estão em uso, sem que o seu sistema precise calcular nada. O escopo é `numbers:read`.

```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())
```

Uma conta no teste grátis

```json
{
  "planName": "Teste grátis",
  "status": "trial",
  "suspendedReason": null,
  "capacity": 1,
  "activeNumbers": 1,
  "canConnectNumber": false,
  "capacityLeft": 0,
  "capacityNotice": "Esta conta já tem 1 número ativo, o máximo contratado (1). Para conectar outro, desconecte um número (DELETE /v1/numbers/{id}) ou escreva para contato@lunahia.com.br.",
  "writesAllowed": true,
  "suspendedNotice": null,
  "pricePerMonth": null,
  "currency": null,
  "contactEmail": "contato@lunahia.com.br",
  "trialEndsAt": "2026-11-03T13:00:00.000Z",
  "trialDaysLeft": 5,
  "periodo": {
    "inicio": "2026-10-01T00:00:00.000Z",
    "fim": "2026-11-01T00:00:00.000Z"
  },
  "numerosAtivos": 1,
  "phoneNumberIds": ["123456789012345"]
}
```

| Campo | O que diz |
| --- | --- |
| `capacity` | Quantos números a conta pode manter ativos ao mesmo tempo. |
| `activeNumbers` | Quantos números estão ativos agora. É a conta que a capacidade usa. |
| `status` | `trial` (teste em curso), `active` (conta contratada), `suspended` (escrita e envio pausados) ou `none` (e-mail ainda não confirmado). |
| `suspendedReason` | Quando `status` é `suspended`: `trial_expired` (o teste terminou) ou `account_blocked` (a Helsen bloqueou a conta). |
| `trialEndsAt` | Quando o teste termina. Fica preenchido depois que a conta é contratada, como registro. |
| `trialDaysLeft` | Os dias que faltam para o teste terminar, já calculados pela API. |
| `planName` | O nome do plano: Teste grátis durante o teste, e o nome da faixa que comporta a capacidade depois. |
| `periodo` | O período corrente, calculado pela API. Mostre-o como veio. |
| `canConnectNumber` | Se a conta pode abrir a conexão de um número novo agora: e-mail confirmado, conta não suspensa e vaga na capacidade. É a mesma decisão que a abertura da conexão aplica, então mostre ou esconda o botão por este campo. |
| `capacityLeft` | Quantos números ainda cabem na capacidade, nunca negativo. Nulo antes de a conta começar o plano. |
| `capacityNotice` | Quando `canConnectNumber` é `false`, o texto da recusa, o mesmo que a API devolve ao tentar conectar. Nulo quando pode conectar. |
| `writesAllowed` | `false` só com a conta suspensa. Ler, desconectar número e revogar chave continuam valendo. |
| `suspendedNotice` | O texto da suspensão, o mesmo das recusas de escrita. Nulo quando a conta não está suspensa. |
| `pricePerMonth` e `currency` | O valor mensal da faixa de capacidade contratada, em reais. A Helsen cobra pela capacidade de números e por mais nada. Nulos no teste grátis e acima da última faixa (Sob consulta). Nunca é zero. |
| `contactEmail` | O e-mail do comercial da Helsen, para contratar, ampliar a capacidade ou sair da suspensão. |

Quando o seu sistema mostrar uma barra de uso, use `activeNumbers` e `capacity` como vieram. Um número aguardando o pagamento do cliente na Meta continua contando, porque a capacidade é de números configurados, e não de números aptos a enviar agora.

## Quando a capacidade chega

Quando `activeNumbers` chega a `capacity`, abrir uma sessão de conexão (`POST /v1/onboarding/sessions`) ou criar um link de conexão (`POST /v1/onboarding/links`) responde `409` com `error: "number_capacity_reached"`. A recusa vem **antes** de o cliente final abrir a tela da Meta, porque o código que a Meta entrega no fim da conexão vale 30 segundos, e a Luna não deixa o seu cliente chegar até ali para recusar depois.

Resposta `409`

```json
{
  "error": "number_capacity_reached",
  "message": "Esta conta já tem 1 número ativo, o máximo contratado (1). Para conectar outro, desconecte um número (DELETE /v1/numbers/{id}) ou escreva para contato@lunahia.com.br.",
  "capacity": 1,
  "activeNumbers": 1
}
```

- Reconectar um número que já conta na capacidade **não** é recusado: ele não acrescenta nenhum.
- Capacidade menor que o uso nunca desconecta ninguém. Só a próxima conexão é recusada.
- Os dois caminhos para seguir são desconectar um número, ou ampliar a capacidade com o comercial.

**O link de conexão não reserva vaga.** A checagem acontece quando o link é criado e quando a sessão é aberta, e de novo quando o número é registrado, que é o instante em que ele passa a contar. Se você criar 20 links numa conta com capacidade 5, os cinco primeiros clientes que terminarem ficam com os números; os outros ficam em `connecting`: o link vira `used`, mas o número não conta nem envia, e a Luna tenta de novo de tempos em tempos. Se a capacidade aumentar, eles conectam sozinhos; se as tentativas se esgotarem antes, a sessão termina em `FAILED`. Crie os links na medida em que há vaga em `GET /v1/subscription`, ou amplie a capacidade antes de mandar os links. Para o seu cliente final nunca ficar nessa espera, conte as vagas antes de entregar cada link: `capacityLeft` de `GET /v1/subscription` menos os links de número novo que continuam `open` em `GET /v1/onboarding/links?status=open`. Só entregue o link se sobrar vaga; se não sobrar, amplie a capacidade primeiro. Link de reconexão de um número que já existe não ocupa vaga nova.

## Desconectar um número

`DELETE /v1/numbers/{id}` tira o número da Luna e abre uma vaga na hora. O escopo é `numbers:write`.

```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)
```

- O número passa para `DISCONNECTED`, não envia mais e deixa de contar na capacidade a partir daquele instante.
- O evento `number.disconnected`, com `reason: "requested_by_tenant"`, é entregue aos seus endpoints. Veja [Saúde da conta](https://lunahia.com.br/docs/saude-da-conta).
- Se era o último número da Luna naquela conta de negócio, a Luna também remove a inscrição dela na conta, e a Meta deixa de mandar eventos dela.
- A Luna **não** desregistra o número na Meta. O número do seu cliente continua funcionando no outro provedor ou no aplicativo do celular dele.
- O histórico fica. As mensagens e as conversas continuam em `GET /v1/messages`, e o número continua em `GET /v1/numbers`, com o `externalId` e o `label` dele.
- Repetir a chamada é seguro: um número já desconectado responde `204` de novo, sem novo evento. Se a Meta estiver indisponível, a chamada falha sem marcar nada e pode ser repetida.
- A rota continua funcionando com o teste terminado, justamente para liberar vaga.

## Voltar a conectar

Para voltar a usar um número desconectado, conecte-o de novo pelo mesmo caminho de qualquer número: um link de conexão ou uma sessão. Veja [Conectar um número](https://lunahia.com.br/docs/conectar-numero). Ele volta a contar na capacidade, e a abertura da sessão é recusada com `409 number_capacity_reached` se a conta estiver cheia.

## Dar nome a um número

`PATCH /v1/numbers/{id}` troca o `externalId` (o seu identificador para o cliente dono do número) e o `label` (um nome livre e curto, de 1 a 128 caracteres, para você reconhecer o número). Mande só o que quer mudar: um campo ausente fica como está, e `null` limpa o campo. Com `autoRead: true`, a Luna marca como lida, na Meta, cada mensagem que o número receber daqui em diante, sem indicador de digitando, alguns segundos depois de ela chegar; o padrão é `false`, e o campo aparece em `GET /v1/numbers`. O escopo é `numbers:write`, e a resposta é o número inteiro.

```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-8841",
  "label": "Atendimento Pinheiros"
}'
```

```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-8841",
    "label": "Atendimento Pinheiros"
  }),
});
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-8841",
        "label": "Atendimento Pinheiros",
    },
    timeout=10,
)
print(res.status_code, res.json())
```

## Quando o teste termina

Três dias antes do fim, a Luna manda um e-mail ao responsável pela conta. Com o teste terminado e a conta sem contratação, `status` vira `suspended` com `suspendedReason: "trial_expired"`.

### Continua funcionando

- Ler os seus dados (`GET`), inclusive mensagens, números e este plano.
- Receber o que chega e entregar ao seu webhook.
- O número continua conectado na Meta.
- Desconectar um número, para liberar vaga.

### Pausa, com `403`

- Enviar mensagens e as demais escritas.
- Abrir uma sessão de conexão ou criar um link.
- Mensagens que já estavam na fila de saída: são recusadas, com o mesmo motivo.

Resposta `403` com o teste terminado

```json
{
  "error": "trial_expired",
  "message": "O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."
}
```

Para continuar, escreva para contato@lunahia.com.br. Quando a conta é contratada, a suspensão sai e o envio volta, sem o seu sistema precisar refazer nada. O mesmo corpo de erro, com `account_blocked`, vale para a conta bloqueada pela Helsen. A lista completa de erros está em [Erros](https://lunahia.com.br/docs/erros).

> Consulte [a referência da API](https://lunahia.com.br/docs/referencia) para os campos completos de cada rota deste guia.

## 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/numbers

Dois campos parecidos e diferentes: throughputLevel é VELOCIDADE, quantas mensagens por segundo a Meta processa; limiteDiarioDeConversas é o LIMITE DE MENSAGENS da Meta, do portfólio empresarial (business portfolio) e não de cada número: conta pessoas únicas a quem a empresa escreve fora da janela de atendimento, nas faixas TIER_250, TIER_2K, TIER_10K, TIER_100K e TIER_UNLIMITED. Um não substitui o outro, e nenhum dos dois conta o que já foi usado.

throughputLevel descreve uma progressão que a Meta sobe sozinha conforme a qualidade do número. Nem todo número segue essa progressão: um número conectado em coexistência tem teto FIXO, que não sobe nunca. Quem diz qual é o caso é tetoDeVazaoPorSegundo, e ele sai na leitura de um número e na saúde dele, não nesta lista.

podeRetentar diz se o estado admite nova tentativa de conexão. A decisão é da plataforma e não sua, porque cada tentativa de registro consome uma cota que a Meta conta por número numa janela de 72 horas. Esgotar essa cota do lado da Meta trava o número até a janela correr.

orientacao traz, em português, o que está acontecendo com a conexão e o que fazer a respeito. Ela é escrita para você repassar ao seu cliente sem reescrever.

externalId é o rótulo que você deu ao seu cliente no link de conexão. Use ?externalId= para listar só os números dele: a comparação é exata e sensível a maiúsculas, e um rótulo sem número devolve lista vazia.

connection é o estado resumido, calculado pela API: status (connected, connecting, action_required ou disconnected), canSend (se enviar vai funcionar agora) e reasons, a lista de motivos com code, message e solution, prontos para você repassar ao seu cliente. É o que você mostra no painel dele em vez de combinar vários campos. ready é o veredito de prontidão: o número está registrado e a inscrição do aplicativo foi confirmada.

Para filtrar, use ?state= (o estado do número), ?ready= e ?canSend= (true ou false). Para percorrer páginas, use ?limit= (de 1 a 100, 50 se omitido) e mande de volta o nextCursor da resposta anterior em ?cursor=; nulo significa o fim. O cursor é opaco: ele carrega posição, não contagem.

### GET /v1/numbers/{id}

tetoDeVazaoPorSegundo é o campo que distingue teto que sobe de teto que não sobe. throughputLevel descreve a progressão que a Meta concede conforme a qualidade do número, e ela sobe com o tempo. Um número conectado em coexistência, que continua funcionando no aplicativo de celular do negócio, tem teto fixo e não entra nessa progressão. Com valor, este campo diz qual é o teto fixo em mensagens por segundo; nulo, a progressão vale e quem a descreve é throughputLevel. O valor vem do que a plataforma observou no tráfego deste número, e não do rótulo que a Meta devolveu.

sincronizacaoDoHistorico conta a importação das conversas anteriores do aparelho, num número conectado em coexistência, e são QUATRO situações e não três. Nulo significa que não há importação para este número. em_curso significa que ela está acontecendo, e sincronizacaoPrazo diz até quando: passado esse instante sem concluir, a plataforma da Meta desconecta o negócio final. concluida significa que terminou, e as conversas antigas já aparecem em GET /v1/messages. recusada significa que o dono do negócio recusou compartilhar no aparelho dele, e aí não vai concluir e pedir de novo não muda isso.

Não leia o percentual sozinho. sincronizacaoProgresso é um rótulo que a plataforma da Meta atribui, e cem por cento NÃO significa sucesso: a recusa chega com o progresso que já havia sido registrado. Quem diz o desfecho é sincronizacaoDoHistorico, e só ele. E ausência não é progresso zero: nulo é não haver importação, e zero é uma importação que começou e ainda não andou.

Quando a Meta recusa o envio por falta de método de pagamento do negócio final, o número fica registrado e sem enviar. Esse não é um erro da plataforma e não há nada a fazer do lado da Helsen: o campo orientacao diz o que falta e onde resolver, em texto pronto para você repassar ao seu cliente. O campo awaitingPaymentSince traz o instante em que a recusa foi vista e é nulo quando não há espera. A Meta não avisa quando o pagamento é regularizado nem oferece consulta: ele só volta a nulo quando um envio seguinte é aceito. Os eventos number.payment_required e number.payment_resolved avisam as duas passagens.

waba traz o estado da conta de negócio do número: restricted e disabled, lidos do último aviso da Meta; credentialExpiresAt e credentialNeverExpires, até quando vale a autorização que o cliente deu à Luna; e paymentMethodOnMeta e currency, a forma de pagamento da conta na Meta (sem ela, a Meta para de entregar mensagens de serviço depois da franquia de 1.000 por número por mês). São da conta, e valem para todos os números dela; os detalhes estão em GET /v1/business-accounts.

connection é o estado resumido da conexão: status, canSend e reasons (code, message e solution de cada motivo). É a mesma conta que decide os eventos number.action_required e number.action_resolved.

subscriptionConfirmedAt é o campo que mais importa aqui. Ele registra quando a inscrição do aplicativo na conta foi confirmada por leitura de volta. Sem essa inscrição nenhum evento chega, e a falha é silenciosa: o número parece perfeito e não recebe nada.

credentialStatus diz se a autorização do cliente continua válida. Quando ela morre, o número precisa ser reconectado.

coexistence e ready são booleanos prontos. coexistence é true quando a Luna já observou tráfego de coexistência neste número (a mesma regra do evento number.connected, e ele pode passar de false para true depois da conexão). ready é true quando o número está registrado e a inscrição foi confirmada, ou seja, quando o envio está liberado: use este campo em vez de combinar state e subscriptionConfirmedAt.

### PATCH /v1/numbers/{id}

externalId é o seu identificador para o cliente dono do número, de 1 a 128 caracteres. É o fio que amarra o número ao seu cliente: ?externalId= em GET /v1/numbers, o evento number.connected e os que vêm depois trazem o mesmo valor. label é um nome livre e curto, de 1 a 128 caracteres, para você reconhecer o número. A Luna não interpreta nenhum dos dois.

Mande só o que quer mudar. Um campo ausente fica como está, e null limpa o campo. O corpo precisa ter pelo menos um dos dois. Repetir o mesmo pedido deixa o mesmo estado.

A resposta é o número inteiro, como em GET /v1/numbers/{id}. Número que não é seu responde 404, igual a número que não existe.

### DELETE /v1/numbers/{id}

O que acontece: o número passa para o estado DISCONNECTED, não envia mais, e o evento number.disconnected, com reason requested_by_tenant, é entregue aos seus endpoints. Se era o último número da Luna naquela conta de negócio, a Luna também remove a inscrição dela na conta, e a Meta deixa de mandar eventos dela.

O que NÃO acontece: a Luna não desregistra o número na Meta. O número do seu cliente continua funcionando no outro provedor ou no aplicativo do celular dele, e continua registrado na Meta. O histórico fica: mensagens e conversas continuam em GET /v1/messages, e o número continua em GET /v1/numbers com o externalId e o label dele.

Para voltar a usar o número, conecte-o de novo com um link de conexão (POST /v1/onboarding/links) ou com POST /v1/onboarding/sessions. Isso conta de novo na capacidade, e é recusado com 409 number_capacity_reached se a conta estiver cheia.

Repetir a chamada é seguro: um número já desconectado responde 204 de novo, sem novo evento. Se a Meta estiver indisponível, a chamada falha sem marcar nada e pode ser repetida.

A rota continua funcionando com o teste grátis terminado, justamente para liberar vaga. Número que não é seu responde 404, igual a número que não existe.
