# Account and plan

Fonte: https://lunahia.com.br/en/docs/reference/account-and-plan

The credential's account, the plan, the number capacity and how many are in use in the period.

### Read the plan and the subscription

`GET /v1/subscription`

The account's plan (free trial or contracted), the number capacity and how many are in use, and what Helsen charges for the period: the capacity of active numbers, and nothing beyond that.

Authentication: API key. Required scope: `numbers:read`

Topic guide: https://lunahia.com.br/en/docs/account-and-keys#rota-get-v1-subscription

#### Query parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `inicio` | `string` | no |  |
| `fim` | `string` | no |  |

#### Code examples

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

#### Responses

**200**: Success.

```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**: The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.

```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**: The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.

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

**403**: The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives 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**: Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.

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

**503**: The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.

```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."
}
```

### Read the platform's technical limits

`GET /v1/limits`

The ceilings the API applies, each with its value, unit and reason. They are the same for every customer and do not depend on the plan: they exist for infrastructure capacity or because Meta imposes them. They are not a count of your usage and do not enter billing.

Authentication: API key. Required scope: `numbers:read`

#### Code examples

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

#### Responses

**200**: Success.

```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**: The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.

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

**403**: The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives 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**: Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.

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

**503**: The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.

```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."
}
```

### Read Meta's pricing rules

`GET /v1/meta-pricing`

The rules by which Meta charges for the use of WhatsApp to the business that owns the number, and the day Luna read them. It carries no monetary values: the rate table stays at Meta. Luna charges none of this.

Authentication: API key. Required scope: `numbers:read`

#### Code examples

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

#### Responses

**200**: Success.

```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**: The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.

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

**403**: The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives 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**: Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.

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

**503**: The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.

```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."
}
```

### Read your own account

`GET /v1/account`

Returns the account behind the credential presented: identifier, name, whether the email has been confirmed, and when the account was created.

Authentication: API key. Required scope: `numbers:read`

Topic guide: https://lunahia.com.br/en/docs/account-and-keys#rota-get-v1-account

#### Code examples

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

#### Responses

**200**: Success.

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

**401**: The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.

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

**403**: The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives 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**: Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.

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

**503**: The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.

```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."
}
```

### Rename the account

`PATCH /v1/account`

Changes the account name, the same one GET /v1/account returns. Returns the account with the new name. Only the console session does this.

Authentication: API key. Required scope: `session:end`

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | yes | O novo nome da conta, de 1 a 120 caracteres: o mesmo limite do cadastro. · 1 to 120 characters |

#### Code examples

```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"
}'
```

#### Responses

**200**: Success.

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

**400**: The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.

```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**: The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.

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

**403**: The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives 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**: The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.

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

**429**: Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.

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

**503**: The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.

```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."
}
```

### See the account summary

`GET /v1/account/overview`

What the account needs to look at now (alerts, most serious first), the four first steps, and the numbers by connection state. Everything is decided by the API, so a home screen has nothing to calculate.

Authentication: API key. Required scope: `numbers:read`

#### Code examples

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

#### Responses

**200**: Success.

```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**: The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.

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

**403**: The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives 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**: Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.

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

**503**: The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.

```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."
}
```
