Quick Start

Do zero ao número ativo em poucos passos: contrate no painel ou API, espere a ativação e use o número como origem de ligações e SMS.

Em poucas palavras

Contrate um número no painel ou com POST /v1/phone-numbers/orders.
Copie o id ou o número para usar como origem (from) em voz e SMS.
Configure a entrada — o que fazer quando alguém liga para esse número.

Antes de começar

Item	Obrigatório?
API Key com escopos certos	Sim — veja Escopos
Autenticação	`Authorization: Bearer sk_live_...` ou `x-api-key`
URL base	`https://api.notifique.dev`

1. Contratar um número

Pelo painel

Configurações → Números de telefone: busque por país e DDD, selecione o número e pague a mensalidade. Quando o pagamento confirma, o número fica ativo e você pode discar.

Pela API (`phone_numbers:create`)

Cria um pedido com pagamento PIX ou cartão:

POST /v1/phone-numbers/orders
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "phoneE164": "+5511987654321",
  "countryCode": "BR",
  "phoneNumberType": "local",
  "features": ["voice", "sms"],
  "billingType": "PIX",
  "label": "Atendimento SP",
  "customer": {
    "name": "Empresa Exemplo LTDA",
    "email": "financeiro@exemplo.com.br",
    "cpfCnpj": "12345678000199",
    "mobilePhone": "5511999887766"
  },
  "regulatory": {
    "endUserType": "BUSINESS",
    "contactName": "Maria Silva",
    "contactPhone": "5511999887766",
    "cpfCnpj": "12345678000199",
    "businessName": "Empresa Exemplo LTDA",
    "street": "Av. Paulista",
    "addressNumber": "1000",
    "city": "São Paulo",
    "state": "SP",
    "postalCode": "01310100"
  }
}

Resposta (201), exemplo

{
  "success": true,
  "data": {
    "order": {
      "id": "ord_abc",
      "phoneE164": "+5511987654321",
      "status": "PENDING_PAYMENT",
      "monthlyPriceBrlCents": 2990
    },
    "payment": {
      "id": "pay_xyz",
      "status": "PENDING",
      "billingType": "PIX",
      "pixCopyPaste": "00020126..."
    },
    "reservedUntil": "2026-08-31T15:30:00.000Z"
  }
}

Acompanhe com GET /v1/phone-numbers/orders/:orderId. Após pagamento → webhook phone_number.activated. Países regulados podem exigir documentos — veja rotas .../regulatory/* na referência OpenAPI.

2. Buscar números disponíveis

Antes de contratar, liste o que está no catálogo:

GET /v1/phone-numbers/available?countryCode=BR&areaCode=11
Authorization: Bearer sk_live_xxxxx

Parâmetros opcionais:

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

Resposta (200), exemplo

{
  "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

Veja os números que você já contratou:

GET /v1/phone-numbers
Authorization: Bearer sk_live_xxxxx

Números liberados (RELEASED) não aparecem na lista. Resposta (200), exemplo

{
  "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"
    }
  ]
}

Use id ou phoneE164 como from em ligações e SMS.

4. Consultar um número

GET /v1/phone-numbers/clxx_phone_1
Authorization: Bearer sk_live_xxxxx

5. Configurar o que fazer quando alguém liga

Quando um cliente liga para o seu número, você define o comportamento:

PATCH /v1/phone-numbers/clxx_phone_1
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

Exemplo — encaminhar para outro número:

{
  "label": "Suporte comercial",
  "inboundVoiceAction": "FORWARD",
  "forwardToE164": "+5511999887766",
  "recordingEnabled": true
}

Opções de entrada

Opção	O que acontece quando alguém liga
`WEBHOOK_CONTROL`	Seu sistema recebe o evento e controla a ligação (padrão)
`FORWARD`	Encaminha para `forwardToE164`
`TTS_HANGUP`	Fala um texto (`inboundTtsText`) e encerra
`REJECT`	Rejeita a ligação
`VOICEMAIL`	Grava recado

Para mensagem falada: inboundTtsText + opcional inboundTtsVoice (female-natural, male-natural, etc.).

6. Webhooks de ciclo de vida

Quando o status do número muda (pagamento, suspensão, devolução):

phone_number.activated — número ativo, pode discar
phone_number.past_due — renovação em atraso
phone_number.suspended — suspenso
phone_number.released — devolvido ao catálogo

Detalhes: Eventos dos Webhooks. Para eventos de ligações (voice.call.*), veja Voz — 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 ligações / SMS	`id` ou `phoneE164` em `POST /v1/voice/calls` ou `POST /v1/sms/messages`
Contratar pela API	`POST /v1/phone-numbers/orders`

Próximos passos

Escopos da API Key
Voice API, Quick Start — primeira ligação
SMS — número próprio

Voz

Voice: Chamadas

Voice: Fluxos IVR

Números de telefone

Números de Telefone

Em poucas palavras

Antes de começar

1. Contratar um número

Pelo painel

Pela API (`phone_numbers:create`)

2. Buscar números disponíveis

3. Listar números do workspace

4. Consultar um número

5. Configurar o que fazer quando alguém liga

Opções de entrada

6. Webhooks de ciclo de vida

Resumo rápido

Próximos passos

​Em poucas palavras

​Antes de começar

​1. Contratar um número

​Pelo painel

​Pela API (phone_numbers:create)

​2. Buscar números disponíveis

​3. Listar números do workspace

​4. Consultar um número

​5. Configurar o que fazer quando alguém liga

​Opções de entrada

​6. Webhooks de ciclo de vida

​Resumo rápido

​Próximos passos

Em poucas palavras

Antes de começar

1. Contratar um número

Pelo painel

Pela API (`phone_numbers:create`)

2. Buscar números disponíveis

3. Listar números do workspace

4. Consultar um número

5. Configurar o que fazer quando alguém liga

Opções de entrada

6. Webhooks de ciclo de vida

Resumo rápido

Próximos passos