# Console e páginas públicas

Fonte: https://lunahia.com.br/docs/referencia/console-e-paginas-publicas

Rotas que o console da Luna e a página pública do link de conexão usam: cadastro, login, sessão e conclusão do fluxo. Você normalmente não precisa delas. Elas existem aqui porque o console é cliente desta mesma API, sem rota privilegiada.

### Ler o link de conexão (página do cliente)

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

Para a página que o seu cliente abre. Devolve o nome da conta que pediu a conexão, o status do link e os identificadores públicos do aplicativo da Meta que a janela de conexão usa. Nada mais da sua conta sai aqui.

Autenticação: Pública, sem chave

Guia do tema: https://lunahia.com.br/docs/saas-com-n-clientes#rota-get-v1-public-onboarding-links-token

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `token` | `string` | sim |  |

#### Exemplos de código

```bash
curl -X GET "https://api.lunahia.com.br/v1/public/onboarding-links/YOUR_TOKEN"
```

#### Respostas

**200**: Sucesso.

```json
{
  "accountName": "YOUR_ACCOUNTNAME",
  "displayName": "YOUR_DISPLAYNAME",
  "status": "open",
  "expiresAt": "YOUR_EXPIRESAT",
  "metaAppId": "YOUR_METAAPPID",
  "metaConfigId": "YOUR_METACONFIGID",
  "sdkVersion": "YOUR_SDKVERSION",
  "redirectUrl": "YOUR_REDIRECTURL",
  "reconnect": true
}
```

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

```json
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
```

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

### Abrir a sessão de conexão pelo link

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

Abre a sessão que a janela da Meta preenche, para a conta dona do link. É a mesma abertura de POST /v1/onboarding/sessions, pela porta do token.

Autenticação: Pública, sem chave

Guia do tema: https://lunahia.com.br/docs/saas-com-n-clientes#rota-post-v1-public-onboarding-links-token-sessions

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `token` | `string` | sim |  |

#### Exemplos de código

```bash
curl -X POST "https://api.lunahia.com.br/v1/public/onboarding-links/YOUR_TOKEN/sessions"
```

#### Respostas

**201**: Criado.

```json
{
  "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "state": "YOUR_STATE",
  "configId": "YOUR_CONFIGID",
  "sdkVersion": "YOUR_SDKVERSION",
  "csrfState": "YOUR_CSRFSTATE",
  "expiresAt": "YOUR_EXPIRESAT"
}
```

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

```json
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
```

**409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.

```json
{
  "error": "account_at_capacity",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "A conta que pediu esta conexão atingiu o máximo de números. Avise quem enviou este link: assim que ela abrir uma vaga, ele poderá enviar um link novo."
}
```

**410**: O link de conexão venceu ou já foi usado. O campo error diz qual dos dois.

```json
{
  "error": "link_expired",
  "docsUrl": "https://lunahia.com.br/docs/conectar-numero",
  "message": "Este link venceu. Peça um novo a quem enviou este."
}
```

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

### Concluir a conexão pelo link

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

Troca o código da janela da Meta por acesso à conta do cliente. É a mesma conclusão de POST /v1/onboarding/sessions/{id}/complete, pela porta do token, e vale o mesmo aviso: o código dura 30 segundos, então chame no instante em que ele chega.

Autenticação: Pública, sem chave

Guia do tema: https://lunahia.com.br/docs/saas-com-n-clientes#rota-post-v1-public-onboarding-links-token-sessions-sessionid-complete

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `token` | `string` | sim |  |
| `sessionId` | `string` | sim |  |

#### Corpo da requisição

`application/json`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `code` | `string` | sim |  |
| `csrfState` | `string` | sim |  |
| `wabaId` | `string \| null` | não |  |
| `phoneNumberId` | `string \| null` | não |  |
| `businessId` | `string \| null` | não |  |

#### Exemplos de código

```bash
curl -X POST "https://api.lunahia.com.br/v1/public/onboarding-links/YOUR_TOKEN/sessions/YOUR_SESSION_ID/complete" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "YOUR_CODE",
  "csrfState": "YOUR_CSRFSTATE"
}'
```

#### Respostas

**200**: Sucesso.

```json
{
  "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "state": "YOUR_STATE",
  "orientacao": "YOUR_ORIENTACAO",
  "terminal": true,
  "motivo": "YOUR_MOTIVO",
  "podeRetentar": true,
  "numberId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "returnUrl": "YOUR_RETURNURL"
}
```

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

```json
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
```

**410**: O link de conexão venceu ou já foi usado. O campo error diz qual dos dois.

```json
{
  "error": "link_used",
  "docsUrl": "https://lunahia.com.br/docs/conectar-numero",
  "message": "Este link já foi usado. Se precisar conectar outro número, peça um novo a quem enviou este."
}
```

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

### Registrar abandono ou erro pelo link

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

Telemetria do que aconteceu na janela da Meta quando o cliente não concluiu. É o mesmo relato de POST /v1/onboarding/sessions/{id}/abandon, pela porta do token, e só vale para uma sessão aberta por este mesmo link.

Autenticação: Pública, sem chave

Guia do tema: https://lunahia.com.br/docs/saas-com-n-clientes#rota-post-v1-public-onboarding-links-token-sessions-sessionid-abandon

#### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `token` | `string` | sim |  |
| `sessionId` | `string` | sim |  |

#### Corpo da requisição

`application/json`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `csrfState` | `string` | sim |  |
| `currentStep` | `string \| null` | não | 1 a 120 caracteres |
| `errorCode` | `integer \| null` | não |  |
| `errorMessage` | `string \| null` | não |  |

#### Exemplos de código

```bash
curl -X POST "https://api.lunahia.com.br/v1/public/onboarding-links/YOUR_TOKEN/sessions/YOUR_SESSION_ID/abandon" \
  -H "Content-Type: application/json" \
  -d '{
  "csrfState": "YOUR_CSRFSTATE"
}'
```

#### Respostas

**200**: Sucesso.

```json
{
  "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "state": "YOUR_STATE",
  "orientacao": "YOUR_ORIENTACAO",
  "abandonedAtStep": "YOUR_ABANDONEDATSTEP"
}
```

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

**404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.

```json
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
```

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

### Criar uma conta

`POST /v1/operators/signup`

Cria a conta e o primeiro operador dela, numa única chamada e sem credencial.

Autenticação: Pública, sem chave

Guia do tema: https://lunahia.com.br/docs/conta-e-chaves#rota-post-v1-operators-signup

#### Corpo da requisição

`application/json`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `email` | `string` | sim | até 254 caracteres |
| `password` | `string` | sim | 12 a 512 caracteres |
| `tenantName` | `string` | sim | 1 a 120 caracteres |

#### Exemplos de código

```bash
curl -X POST "https://api.lunahia.com.br/v1/operators/signup" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "ana@suaempresa.com.br",
  "password": "YOUR_PASSWORD",
  "tenantName": "YOUR_TENANTNAME"
}'
```

#### Respostas

**201**: Criado.

```json
{
  "nextStep": "login"
}
```

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

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

### Confirmar o e-mail de uma conta

`GET /v1/operators/confirm`

Destino do link enviado por e-mail quando a conta é criada. Ela responde com um redirecionamento para o console, e não com JSON, porque quem a abre é uma pessoa num navegador.

Autenticação: Pública, sem chave

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

#### Parâmetros de consulta

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

#### Exemplos de código

```bash
curl -X GET "https://api.lunahia.com.br/v1/operators/confirm"
```

#### Respostas

**200**: Sucesso.

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

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

### Pedir a redefinição da senha

`POST /v1/operators/password/forgot`

Pede o envio de um link para escolher uma senha nova. Recebe só o e-mail da conta.

Autenticação: Pública, sem chave

Guia do tema: https://lunahia.com.br/docs/conta-e-chaves#rota-post-v1-operators-password-forgot

#### Corpo da requisição

`application/json`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `email` | `string` | sim | até 254 caracteres |

#### Exemplos de código

```bash
curl -X POST "https://api.lunahia.com.br/v1/operators/password/forgot" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "ana@suaempresa.com.br"
}'
```

#### Respostas

**202**: Aceito: o pedido foi registrado e será processado.

```json
{
  "accepted": true
}
```

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

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

### Escolher uma senha nova

`POST /v1/operators/password/reset`

Troca a senha do operador a partir do token do link enviado por e-mail, e responde 204.

Autenticação: Pública, sem chave

Guia do tema: https://lunahia.com.br/docs/conta-e-chaves#rota-post-v1-operators-password-reset

#### Corpo da requisição

`application/json`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `token` | `string` | sim | até 512 caracteres |
| `password` | `string` | sim | 12 a 512 caracteres |

#### Exemplos de código

```bash
curl -X POST "https://api.lunahia.com.br/v1/operators/password/reset" \
  -H "Content-Type: application/json" \
  -d '{
  "token": "YOUR_TOKEN",
  "password": "YOUR_PASSWORD"
}'
```

#### Respostas

**204**: Sem conteúdo: a operação foi feita e a resposta não tem corpo.

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

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

### Conferir o link de redefinição

`POST /v1/operators/password/reset/check`

Responde 204 quando o token do link ainda vale e 400 quando não vale, sem consumi-lo. Serve para a tela avisar antes de a pessoa digitar a senha nova.

Autenticação: Pública, sem chave

#### Corpo da requisição

`application/json`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `token` | `string` | sim | até 512 caracteres |

#### Exemplos de código

```bash
curl -X POST "https://api.lunahia.com.br/v1/operators/password/reset/check" \
  -H "Content-Type: application/json" \
  -d '{
  "token": "YOUR_TOKEN"
}'
```

#### Respostas

**204**: Sem conteúdo: a operação foi feita e a resposta não tem corpo.

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

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

### Ler a regra de senha

`GET /v1/public/password-policy`

O comprimento mínimo de uma senha de operador, o mesmo no cadastro, na redefinição e na troca. Não pede credencial.

Autenticação: Pública, sem chave

#### Exemplos de código

```bash
curl -X GET "https://api.lunahia.com.br/v1/public/password-policy"
```

#### Respostas

**200**: Sucesso.

```json
{
  "minLength": 12
}
```

**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 a senha

`POST /v1/operators/password/change`

Troca a senha do operador da sessão apresentada, conferindo a senha atual, e responde 204. As outras sessões do mesmo operador são encerradas e a apresentada continua valendo. Senha atual errada, ou credencial sem operador (chave de integração), responde 401.

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

#### Corpo da requisição

`application/json`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `currentPassword` | `string` | sim | A senha de hoje do operador da sessão. · até 512 caracteres |
| `newPassword` | `string` | sim | A senha nova, pela mesma regra do cadastro (GET /v1/public/password-policy diz o mínimo). · 12 a 512 caracteres |

#### Exemplos de código

```bash
curl -X POST "https://api.lunahia.com.br/v1/operators/password/change" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "currentPassword": "YOUR_CURRENTPASSWORD",
  "newPassword": "YOUR_NEWPASSWORD"
}'
```

#### Respostas

**204**: Sem conteúdo: a operação foi feita e a resposta não tem corpo.

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

### Reenviar o e-mail de confirmação

`POST /v1/operators/confirmation/resend`

Envia de novo o link de confirmação para o e-mail do operador da sessão, e invalida o link anterior que ainda não tinha sido aberto. O link novo vale por sete dias e é aceito uma única vez.

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

Guia do tema: https://lunahia.com.br/docs/conta-e-chaves#rota-post-v1-operators-confirmation-resend

#### Exemplos de código

```bash
curl -X POST "https://api.lunahia.com.br/v1/operators/confirmation/resend" \
  -H "Authorization: Bearer $LUNA_API_KEY"
```

#### Respostas

**202**: Aceito: o pedido foi registrado e será processado.

```json
{
  "emailConfirmed": true
}
```

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

### Autenticar um operador

`POST /v1/operators/login`

Troca email e senha por uma credencial de sessão de oito horas, usada pelo console web.

Autenticação: Pública, sem chave

Guia do tema: https://lunahia.com.br/docs/conta-e-chaves#rota-post-v1-operators-login

#### Corpo da requisição

`application/json`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `email` | `string` | sim | 1 a 254 caracteres |
| `password` | `string` | sim | 1 a 512 caracteres |

#### Exemplos de código

```bash
curl -X POST "https://api.lunahia.com.br/v1/operators/login" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "ana@suaempresa.com.br",
  "password": "YOUR_PASSWORD"
}'
```

#### Respostas

**200**: Sucesso.

```json
{
  "tenantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "operatorId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "token": "YOUR_TOKEN",
  "expiresAt": "YOUR_EXPIRESAT",
  "scopes": [
    "YOUR_SCOPES"
  ]
}
```

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

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

### Reautenticar para uma ação sensível

`POST /v1/operators/step-up`

Confirma a senha do operador da sessão apresentada e abre uma janela de duas horas em que essa mesma sessão pode criar e revogar chaves de API.

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

Guia do tema: https://lunahia.com.br/docs/conta-e-chaves#rota-post-v1-operators-step-up

#### Corpo da requisição

`application/json`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `password` | `string` | sim | 1 a 512 caracteres |

#### Exemplos de código

```bash
curl -X POST "https://api.lunahia.com.br/v1/operators/step-up" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "password": "YOUR_PASSWORD"
}'
```

#### Respostas

**200**: Sucesso.

```json
{
  "elevatedUntil": "YOUR_ELEVATEDUNTIL",
  "scopes": [
    "YOUR_SCOPES"
  ]
}
```

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

### Ler a sessão apresentada

`GET /v1/operators/session`

Quando a credencial apresentada expira, até quando vale a elevação aberta por POST /v1/operators/step-up (nulo sem elevação ou com a janela fechada) e os escopos que ela tem agora. Lê só a própria credencial: o identificador vem da autenticação e nunca do caminho.

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

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

```json
{
  "expiresAt": "2026-11-03T20:00:00.000Z",
  "elevatedUntil": "2026-11-03T14:30:00.000Z",
  "scopes": [
    "numbers:read",
    "session:end",
    "session:elevate",
    "keys:write"
  ]
}
```

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

### Encerrar a sessão

`POST /v1/operators/logout`

Revoga a credencial apresentada, e apenas ela. O identificador vem da própria autenticação e nunca do corpo, então esta rota não consegue revogar chave de terceiro.

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

#### Exemplos de código

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

#### Respostas

**204**: Sem conteúdo: a operação foi feita e a resposta não tem corpo.

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