# Links de conexão

Fonte: https://lunahia.com.br/docs/referencia/links-de-conexao

Um link que o seu cliente abre para conectar o número de WhatsApp dele, sem receber o login do seu console. Um link por cliente seu, amarrado ao externalId que você escolheu.

### Listar os links de conexão

`GET /v1/onboarding/links`

Os links que você criou, do mais recente para o mais antigo, inclusive os revogados. Filtros: externalId (igualdade), q (começo do externalId) e status (open, used, expired ou revoked).

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

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

#### Parâmetros de consulta

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `q` | `string` | não | O começo do rótulo do seu cliente: os links cujo externalId começa com este texto, sem diferenciar maiúscula. Use no lugar de externalId quando você só lembra do começo. Combina com os outros filtros. |
| `externalId` | `string` | não | O rótulo que você deu ao seu cliente (externalId): só os links dele. Igualdade exata; um rótulo sem link devolve lista vazia. |
| `status` | `string` | não | Só os links neste estado: open, used, expired ou revoked. |
| `limit` | `integer` | não |  |
| `cursor` | `string` | não |  |

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

```json
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "externalId": "YOUR_EXTERNALID",
      "status": "open",
      "createdAt": "YOUR_CREATEDAT",
      "purpose": "new",
      "revokedAt": "YOUR_REVOKEDAT",
      "lastFailure": {
        "step": "YOUR_STEP",
        "reason": "YOUR_REASON",
        "at": "YOUR_AT"
      },
      "allowedActions": [
        "revoke"
      ],
      "expiresAt": "YOUR_EXPIRESAT",
      "usedAt": "YOUR_USEDAT",
      "redirectUrl": "YOUR_REDIRECTURL",
      "displayName": "YOUR_DISPLAYNAME",
      "numberId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
  ],
  "nextCursor": "YOUR_NEXTCURSOR"
}
```

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

### Criar um link de conexão para o seu cliente

`POST /v1/onboarding/links`

Cria um link que o seu cliente abre para conectar o número de WhatsApp dele, sem receber o login do seu console.

Autenticação: Chave de API. Escopo exigido: `onboarding:write`

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

#### Corpo da requisição

`application/json`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `externalId` | `string` | não | O seu identificador para este cliente, em texto livre de 1 a 128 caracteres. A Luna não o interpreta: ele volta como externalId no link e no número que resultar da conexão. · 1 a 128 caracteres |
| `displayName` | `string` | não | O nome do seu cliente, em texto livre de 1 a 120 caracteres, que a página do link mostra ("Conectar o WhatsApp de ..."). Serve para o cliente reconhecer de quem é o pedido. É só texto da página: a janela da Meta que abre em seguida mostra o nome da Luna e não pode ser mudada. · 1 a 120 caracteres |
| `redirectUrl` | `string` | não | Para onde a página do link leva o seu cliente quando a conexão termina (https, até 2048 caracteres). A página acrescenta status (o estado final da conexão) e numberId (o número, quando a Luna já o registrou) na query. Ausente, o cliente fica na página da Luna. · até 2048 caracteres · /^https:\/\/[^\s]+$/ |
| `numberId` | `string` | não | O número a reconectar: o UUID da Luna (o id de GET /v1/numbers) ou o id da Meta (metaPhoneNumberId). Com ele, o link abre a reconexão daquele número em vez de uma conexão nova. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |

#### Exemplos de código

```bash
curl -X POST "https://api.lunahia.com.br/v1/onboarding/links" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "externalId": "YOUR_EXTERNALID",
  "displayName": "YOUR_DISPLAYNAME",
  "redirectUrl": "YOUR_REDIRECTURL"
}'
```

#### Respostas

**201**: Criado.

```json
{
  "id": "5b8a0e0e-9a1f-4d1c-8d27-2f0c5f3a7d10",
  "url": "https://app.lunahia.com.br/conectar/0f2c8e6a-1d3b-4a5c-9e7f-2b4d6a8c0e12.k3JrYq1w2hX9s0Zt4uVb7nLmP5dQe8aRfG6yTcIoWxU",
  "expiresAt": "2026-10-10T14:00:00.000Z",
  "externalId": "cliente-8841",
  "redirectUrl": "https://app.exemplo.com.br/whatsapp/conectado",
  "displayName": "Escritório Silva & Filhos"
}
```

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

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

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

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

### Consultar um link de conexão

`GET /v1/onboarding/links/{id}`

O estado de um link: open, used, expired ou revoked, com a finalidade, a última falha e o que a conta pode fazer com ele.

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

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

#### Parâmetros de caminho

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

#### Exemplos de código

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

#### Respostas

**200**: Sucesso.

```json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "externalId": "YOUR_EXTERNALID",
  "status": "open",
  "createdAt": "YOUR_CREATEDAT",
  "purpose": "new",
  "revokedAt": "YOUR_REVOKEDAT",
  "lastFailure": {
    "step": "YOUR_STEP",
    "reason": "YOUR_REASON",
    "at": "YOUR_AT"
  },
  "allowedActions": [
    "revoke"
  ],
  "expiresAt": "YOUR_EXPIRESAT",
  "usedAt": "YOUR_USEDAT",
  "redirectUrl": "YOUR_REDIRECTURL",
  "displayName": "YOUR_DISPLAYNAME",
  "numberId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
```

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

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

### Revogar um link de conexão

`DELETE /v1/onboarding/links/{id}`

Revoga o link. A url deixa de funcionar na hora e passa a responder 404 a quem a abrir, como uma que nunca existiu. Uma conexão que o cliente já tinha começado na janela da Meta não pode mais ser concluída por ela. O link continua na sua lista, com status revoked e revokedAt. Revogar de novo um link já revogado responde 404.

Autenticação: Chave de API. Escopo exigido: `onboarding:write`

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

#### Parâmetros de caminho

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

#### Exemplos de código

```bash
curl -X DELETE "https://api.lunahia.com.br/v1/onboarding/links/YOUR_ID" \
  -H "Authorization: Bearer $LUNA_API_KEY"
```

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

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

### Criar vários links de conexão de uma vez

`POST /v1/onboarding/links/batch`

Cria até 100 links, cada item no mesmo formato de POST /v1/onboarding/links e com as mesmas regras, inclusive a capacidade do plano. Responde 200 com um resultado por item, com a url de cada link criado; um item que falha não derruba os outros.

Autenticação: Chave de API. Escopo exigido: `onboarding:write`

#### Corpo da requisição

`application/json`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `links` | `array<object>` | sim | De 1 a 100 links, cada um no mesmo formato do corpo de POST /v1/onboarding/links: externalId, displayName, redirectUrl e numberId, todos opcionais. · 1 a 100 itens |
| `links[].externalId` | `string` | não | O seu identificador para este cliente, em texto livre de 1 a 128 caracteres. A Luna não o interpreta: ele volta como externalId no link e no número que resultar da conexão. · 1 a 128 caracteres |
| `links[].displayName` | `string` | não | O nome do seu cliente, em texto livre de 1 a 120 caracteres, que a página do link mostra ("Conectar o WhatsApp de ..."). Serve para o cliente reconhecer de quem é o pedido. É só texto da página: a janela da Meta que abre em seguida mostra o nome da Luna e não pode ser mudada. · 1 a 120 caracteres |
| `links[].redirectUrl` | `string` | não | Para onde a página do link leva o seu cliente quando a conexão termina (https, até 2048 caracteres). A página acrescenta status (o estado final da conexão) e numberId (o número, quando a Luna já o registrou) na query. Ausente, o cliente fica na página da Luna. · até 2048 caracteres · /^https:\/\/[^\s]+$/ |
| `links[].numberId` | `string` | não | O número a reconectar: o UUID da Luna (o id de GET /v1/numbers) ou o id da Meta (metaPhoneNumberId). Com ele, o link abre a reconexão daquele número em vez de uma conexão nova. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ |

#### Exemplos de código

```bash
curl -X POST "https://api.lunahia.com.br/v1/onboarding/links/batch" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "links": [
    {
      "externalId": "YOUR_EXTERNALID",
      "displayName": "YOUR_DISPLAYNAME",
      "redirectUrl": "YOUR_REDIRECTURL"
    }
  ]
}'
```

#### Respostas

**200**: Sucesso.

```json
{
  "results": [
    {
      "index": 1,
      "status": 1,
      "link": {
        "id": "5b8a0e0e-9a1f-4d1c-8d27-2f0c5f3a7d10",
        "url": "https://app.lunahia.com.br/conectar/0f2c8e6a-1d3b-4a5c-9e7f-2b4d6a8c0e12.k3JrYq1w2hX9s0Zt4uVb7nLmP5dQe8aRfG6yTcIoWxU",
        "expiresAt": "2026-10-10T14:00:00.000Z",
        "externalId": "cliente-8841",
        "redirectUrl": "https://app.exemplo.com.br/whatsapp/conectado",
        "displayName": "Escritório Silva & Filhos"
      },
      "error": {
        "error": "YOUR_ERROR",
        "message": "YOUR_MESSAGE"
      }
    }
  ]
}
```

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

### Gerar de novo a url de um link de conexão

`POST /v1/onboarding/links/{id}/reissue`

Gera um token novo para o mesmo link (mesmo id, mesmo rótulo, mesmo prazo): a url antiga deixa de funcionar na hora e a nova aparece só nesta resposta. Só vale para um link aberto; usado, vencido ou revogado responde 409. Use quando o seu cliente perdeu a url, em vez de revogar e criar outro.

Autenticação: Chave de API. Escopo exigido: `onboarding:write`

#### Parâmetros de caminho

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

#### Exemplos de código

```bash
curl -X POST "https://api.lunahia.com.br/v1/onboarding/links/YOUR_ID/reissue" \
  -H "Authorization: Bearer $LUNA_API_KEY"
```

#### Respostas

**200**: Sucesso.

```json
{
  "id": "5b8a0e0e-9a1f-4d1c-8d27-2f0c5f3a7d10",
  "url": "https://app.lunahia.com.br/conectar/0f2c8e6a-1d3b-4a5c-9e7f-2b4d6a8c0e12.k3JrYq1w2hX9s0Zt4uVb7nLmP5dQe8aRfG6yTcIoWxU",
  "expiresAt": "2026-10-10T14:00:00.000Z",
  "externalId": "cliente-8841",
  "redirectUrl": "https://app.exemplo.com.br/whatsapp/conectado",
  "displayName": "Escritório Silva & Filhos"
}
```

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

**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": "link_not_open",
  "docsUrl": "https://lunahia.com.br/docs/conectar-numero",
  "message": "Só um link aberto pode ser reemitido, e este está usado. Crie um link novo com POST /v1/onboarding/links.",
  "status": "used"
}
```

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