# Conta e plano

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

A conta da credencial, o plano, a capacidade de números e quantos estão em uso no período.

### Consultar o plano e a assinatura

`GET /v1/subscription`

O plano da conta (teste grátis ou contratado), a capacidade de números e quantos estão em uso, e o que é cobrado pela Helsen no período: a capacidade de números ativos, e nada além disso.

Autenticação: Chave de API. Escopo exigido: `numbers:read`

Guia do tema: https://lunahia.com.br/docs/conta-e-chaves#rota-get-v1-subscription

#### Parâmetros de consulta

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `inicio` | `string` | não |  |
| `fim` | `string` | não |  |

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

```json
{
  "planName": "Growth",
  "status": "trial",
  "suspendedReason": null,
  "capacity": 20,
  "activeNumbers": 3,
  "trialEndsAt": "2026-11-03T13:00:00.000Z",
  "trialDaysLeft": 5,
  "periodo": {
    "inicio": "2026-03-01T00:00:00.000Z",
    "fim": "2026-04-01T00:00:00.000Z"
  },
  "canConnectNumber": true,
  "capacityLeft": 17,
  "capacityNotice": null,
  "writesAllowed": true,
  "suspendedNotice": null,
  "pricePerMonth": 990,
  "currency": "BRL",
  "contactEmail": "contato@lunahia.com.br",
  "numerosAtivos": 3,
  "phoneNumberIds": [
    "15550001111",
    "15550002222"
  ]
}
```

**400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

```json
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
```

**401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.

```json
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
```

**403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.

```json
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
```

**429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.

```json
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}
```

### Ler os limites técnicos da plataforma

`GET /v1/limits`

Os tetos que a API aplica, cada um com o valor, a unidade e o motivo. São iguais para todos os clientes e não dependem do plano: existem por capacidade de infraestrutura ou porque a Meta os impõe. Não são contagem do seu uso e não entram em cobrança.

Autenticação: Chave de API. Escopo exigido: `numbers:read`

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

```json
{
  "data": [
    {
      "key": "webhook_endpoints",
      "label": "Endpoints de webhook por cliente",
      "value": 25,
      "unit": "endpoints",
      "reason": "Cada evento é entregue a cada endpoint que o aceita. Remover um endpoint libera a vaga."
    }
  ]
}
```

**401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.

```json
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
```

**403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.

```json
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
```

**429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.

```json
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}
```

### Ler as regras de preço da Meta

`GET /v1/meta-pricing`

As regras com que a Meta cobra o uso do WhatsApp do negócio dono do número, e o dia em que a Luna as leu. Não traz valor em moeda: a tabela de tarifas fica na Meta. A Luna não cobra nada disto.

Autenticação: Chave de API. Escopo exigido: `numbers:read`

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

```json
{
  "readAt": "2026-10-07",
  "sourceUrl": "https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing",
  "aiProvidersUrl": "https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing/ai-providers",
  "rules": [
    {
      "key": "marketing_templates",
      "title": "Template de marketing",
      "text": "É sempre cobrado pela Meta, dentro ou fora da janela de 24 horas."
    }
  ]
}
```

**401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.

```json
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
```

**403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.

```json
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
```

**429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.

```json
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}
```

### Ler a própria conta

`GET /v1/account`

Devolve a conta da credencial apresentada: identificador, nome, se o e-mail já foi confirmado e quando a conta foi criada.

Autenticação: Chave de API. Escopo exigido: `numbers:read`

Guia do tema: https://lunahia.com.br/docs/conta-e-chaves#rota-get-v1-account

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

```json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "YOUR_NAME",
  "emailConfirmed": true,
  "createdAt": "YOUR_CREATEDAT",
  "operatorEmail": "YOUR_OPERATOREMAIL"
}
```

**401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.

```json
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
```

**403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.

```json
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
```

**429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.

```json
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}
```

### Trocar o nome da conta

`PATCH /v1/account`

Troca o nome da conta, o mesmo que GET /v1/account devolve. Devolve a conta já com o nome novo. Só a sessão do console faz isto.

Autenticação: Chave de API. Escopo exigido: `session:end`

#### Corpo da requisição

`application/json`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `name` | `string` | sim | O novo nome da conta, de 1 a 120 caracteres: o mesmo limite do cadastro. · 1 a 120 caracteres |

#### Exemplos de código

```bash
curl -X PATCH "https://api.lunahia.com.br/v1/account" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "YOUR_NAME"
}'
```

#### Respostas

**200**: Sucesso.

```json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "YOUR_NAME",
  "emailConfirmed": true,
  "createdAt": "YOUR_CREATEDAT",
  "operatorEmail": "YOUR_OPERATOREMAIL"
}
```

**400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.

```json
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
```

**401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.

```json
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
```

**403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.

```json
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
```

**415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.

```json
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
```

**429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.

```json
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}
```

### Ver o resumo da conta

`GET /v1/account/overview`

O que a conta precisa olhar agora (avisos em ordem de gravidade), os quatro primeiros passos e os números por estado de conexão. Tudo decidido pela API, para uma tela inicial não precisar calcular nada.

Autenticação: Chave de API. Escopo exigido: `numbers:read`

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

```json
{
  "attention": [
    {
      "code": "number_credential_expiring",
      "severity": "warning",
      "title": "Autorização do cliente perto de vencer (+55 11 90000-0000)",
      "message": "A autorização que o seu cliente deu à Luna vence em até 14 dias. O número continua enviando até lá.",
      "solution": "Gere um link de reconexão com POST /v1/onboarding/links informando numberId e envie ao seu cliente.",
      "resource": {
        "type": "number",
        "id": "ed404df1-b420-4ed6-8743-ba1609892e0a"
      },
      "action": "reconnect_link",
      "actionUrl": null,
      "since": "2026-10-25T12:00:00.000Z"
    }
  ],
  "checklist": [
    {
      "key": "connect_number",
      "done": true,
      "doneAt": "2026-08-07T11:28:14.597Z"
    },
    {
      "key": "create_key",
      "done": true,
      "doneAt": "2026-08-07T12:10:44.201Z"
    },
    {
      "key": "add_webhook_endpoint",
      "done": true,
      "doneAt": "2026-08-08T09:00:00.000Z"
    },
    {
      "key": "send_message",
      "done": false,
      "doneAt": null
    }
  ],
  "numbers": {
    "total": 1,
    "byStatus": {
      "connected": 1,
      "connecting": 0,
      "action_required": 0,
      "disconnected": 0
    }
  }
}
```

**401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.

```json
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
```

**403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.

```json
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
```

**429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.

```json
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}
```
