> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notifique.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Gerencie números de telefone do workspace pela API, consultar, buscar disponíveis e configurar voz de entrada.

## Em poucas palavras

* **Contratar** número é no **painel**; a API lista, consulta disponíveis e configura **voz de entrada**.
* Escopos: `phone_numbers:read` (consultar) e `phone_numbers:update` (configurar). Detalhe em **[Escopos da API Key](/phone-numbers-api/como-funciona/escopos-da-api-key)**.
* Use o `id` ou `phoneE164` como origem em chamadas, veja **[Voice API Quick Start](/voice-api/como-funciona/quick-start)**.

Para quem **integra** gestão de números (CRM, telefonia). Compra e pagamento ficam no painel.

***

## Antes de começar

* **Número ativo** contratado em **Configurações → Números de telefone**.
* **API Key** com escopos necessários. Veja [Escopos](/phone-numbers-api/como-funciona/escopos-da-api-key).
* Autenticação: `Authorization: Bearer sk_live_...` ou `x-api-key`.
* **URL base** (ex.: `https://api.notifique.dev`).

***

## O caminho em três passos

1. **Contratar** no painel (busca, reserva, pagamento).
2. **Listar** números e copiar **`id`** ou **`phoneE164`**.
3. **Configurar** o que acontece quando alguém **liga** (encaminhar, TTS, webhook…).

***

## 1. Contratar um número (painel)

**Configurações → Números de telefone:**

1. Busque por país, DDD ou padrão.
2. Selecione e pague (mensalidade recorrente).
3. Ativação → webhook **`phone_number.activated`** (se configurado).

A API busca **disponíveis**; a **compra** é pelo painel.

***

## 2. Buscar números disponíveis

Lista opções antes de mandar o usuário ao checkout do painel.

**Pedido**

```http theme={null}
GET /v1/phone-numbers/available?countryCode=BR&areaCode=11
Authorization: Bearer sk_live_xxxxx
```

Parâmetros opcionais:

| Parâmetro         | Descrição                        |
| ----------------- | -------------------------------- |
| `countryCode`     | ISO (padrão `US`)                |
| `phoneNumberType` | ex.: `local`, `mobile`           |
| `areaCode`        | DDD                              |
| `contains`        | Dígitos que o número deve conter |

**Resposta (200), exemplo**

```json theme={null}
{
  "success": true,
  "data": [
    {
      "phoneE164": "+5511987654321",
      "countryCode": "BR",
      "phoneNumberType": "local",
      "features": ["voice", "sms"],
      "region": "SP",
      "locality": "São Paulo",
      "monthlyPriceBrlCents": 2990
    }
  ]
}
```

***

## 3. Listar números do workspace

**Pedido**

```http theme={null}
GET /v1/phone-numbers
Authorization: Bearer sk_live_xxxxx
```

Retorna números **não liberados** (`RELEASED` não aparece).

**Resposta (200), exemplo**

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "clxx_phone_1",
      "workspaceId": "clxx_ws",
      "phoneE164": "+5511987654321",
      "countryCode": "BR",
      "phoneNumberType": "local",
      "features": ["voice", "sms"],
      "status": "ACTIVE",
      "monthlyPriceBrlCents": 2990,
      "renewsAt": "2026-07-11T00:00:00.000Z",
      "label": "Atendimento SP",
      "inboundVoiceAction": "WEBHOOK_CONTROL",
      "forwardToE164": null,
      "inboundTtsText": null,
      "inboundTtsVoice": null,
      "recordingEnabled": false,
      "createdAt": "2026-06-11T12:00:00.000Z",
      "updatedAt": "2026-06-11T12:00:00.000Z"
    }
  ]
}
```

***

## 4. Consultar um número

**Pedido**

```http theme={null}
GET /v1/phone-numbers/clxx_phone_1
Authorization: Bearer sk_live_xxxxx
```

***

## 5. Configurar voz de entrada

Define o que acontece quando alguém **liga**, como escolher se a chamada vai para recepção, correio de voz ou seu sistema.

**Pedido**

```http theme={null}
PATCH /v1/phone-numbers/clxx_phone_1
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx
```

```json theme={null}
{
  "label": "Suporte comercial",
  "inboundVoiceAction": "FORWARD",
  "forwardToE164": "+5511999887766",
  "recordingEnabled": true
}
```

### Valores de `inboundVoiceAction`

| Valor             | Comportamento                                    |
| ----------------- | ------------------------------------------------ |
| `WEBHOOK_CONTROL` | Sua app controla via webhooks Voice API (padrão) |
| `FORWARD`         | Encaminha para `forwardToE164`                   |
| `TTS_HANGUP`      | Fala `inboundTtsText` e encerra                  |
| `REJECT`          | Rejeita                                          |
| `VOICEMAIL`       | Grava recado                                     |

TTS: `inboundTtsText` + opcional `inboundTtsVoice` (`female-natural`, `male-natural`, etc.).

***

## 6. Webhooks de ciclo de vida

Eventos: **`phone_number.activated`**, **`phone_number.past_due`**, **`phone_number.suspended`**, **`phone_number.released`**.

Detalhes: [**Eventos dos Webhooks**](/voice-api/como-funciona/eventos-do-webhooks).

***

## Resumo rápido

| Objetivo           | Caminho                                       |
| ------------------ | --------------------------------------------- |
| Buscar disponíveis | `GET /v1/phone-numbers/available`             |
| Listar contratados | `GET /v1/phone-numbers`                       |
| Detalhe            | `GET /v1/phone-numbers/:id`                   |
| Configurar entrada | `PATCH /v1/phone-numbers/:id`                 |
| Origem de chamadas | `id` ou `phoneE164` em `POST /v1/voice/calls` |

***

## Próximos passos

* **[Escopos da API Key](/phone-numbers-api/como-funciona/escopos-da-api-key)**
* **[Voice API, Quick Start](/voice-api/como-funciona/quick-start)**
* **[Eventos dos Webhooks](/voice-api/como-funciona/eventos-do-webhooks)**
* **[Chaves de API](/guides/api-key/index)**