Inicio rápido

De cero al número activo en pocos pasos: contrata en el panel o API, espera la activación y usa el número como origen de llamadas y SMS.

En resumen

Contrata un número en el panel o con POST /v1/phone-numbers/orders.
Copia el id o el número para usarlo como origen (from) en voz y SMS.
Configura la entrada — qué hacer cuando alguien llama a ese número.

Antes de empezar

Item	¿Obligatorio?
API Key con ámbitos correctos	Sí — ver Ámbitos
Autenticación	`Authorization: Bearer sk_live_...` o `x-api-key`
URL base	`https://api.notifique.dev`

1. Contratar un número

Por el panel

Configuración → Números de teléfono: busca por país y código de área, selecciona el número y paga la mensualidad. Cuando el pago se confirma, el número queda activo y puedes marcar.

Por la API (`phone_numbers:create`)

Crea un pedido con pago PIX o tarjeta:

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": "Atención SP",
  "customer": {
    "name": "Empresa Ejemplo LTDA",
    "email": "finanzas@ejemplo.com.br",
    "cpfCnpj": "12345678000199",
    "mobilePhone": "5511999887766"
  },
  "regulatory": {
    "endUserType": "BUSINESS",
    "contactName": "María Silva",
    "contactPhone": "5511999887766",
    "cpfCnpj": "12345678000199",
    "businessName": "Empresa Ejemplo LTDA",
    "street": "Av. Paulista",
    "addressNumber": "1000",
    "city": "São Paulo",
    "state": "SP",
    "postalCode": "01310100"
  }
}

Respuesta (201), ejemplo

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

Sigue con GET /v1/phone-numbers/orders/:orderId. Tras el pago → webhook phone_number.activated. Países regulados pueden exigir documentos — ver rutas .../regulatory/* en la referencia OpenAPI.

2. Buscar números disponibles

Antes de contratar, lista lo que hay en el catálogo:

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

Parámetros opcionales:

Parámetro	Descripción
`countryCode`	País (predeterminado `US`)
`phoneNumberType`	ej.: `local`, `mobile`
`areaCode`	Código de área
`contains`	Dígitos que el número debe contener

Respuesta (200), ejemplo

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

3. Listar números del workspace

Mira los números que ya contrataste:

GET /v1/phone-numbers
Authorization: Bearer sk_live_xxxxx

Los números liberados (RELEASED) no aparecen en la lista. Respuesta (200), ejemplo

{
  "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": "Atención 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"
    }
  ]
}

Usa id o phoneE164 como from en llamadas y SMS.

4. Consultar un número

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

5. Configurar qué hacer cuando alguien llama

Cuando un cliente llama a tu número, defines el comportamiento:

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

Ejemplo — reenviar a otro número:

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

Opciones de entrada

Opción	Qué pasa cuando alguien llama
`WEBHOOK_CONTROL`	Tu sistema recibe el evento y controla la llamada (predeterminado)
`FORWARD`	Reenvía a `forwardToE164`
`TTS_HANGUP`	Habla un texto (`inboundTtsText`) y cuelga
`REJECT`	Rechaza la llamada
`VOICEMAIL`	Graba mensaje

Para mensaje hablado: inboundTtsText + opcional inboundTtsVoice (female-natural, male-natural, etc.).

6. Webhooks de ciclo de vida

Cuando el estado del número cambia (pago, suspensión, devolución):

phone_number.activated — número activo, puede marcar
phone_number.past_due — renovación atrasada
phone_number.suspended — suspendido
phone_number.released — devuelto al catálogo

Detalles: Eventos de webhooks. Para eventos de llamadas (voice.call.*), ver Voz — webhooks.

Resumen rápido

Objetivo	Ruta
Buscar disponibles	`GET /v1/phone-numbers/available`
Listar contratados	`GET /v1/phone-numbers`
Detalle	`GET /v1/phone-numbers/:id`
Configurar entrada	`PATCH /v1/phone-numbers/:id`
Origen de llamadas / SMS	`id` o `phoneE164` en `POST /v1/voice/calls` o `POST /v1/sms/messages`
Contratar por la API	`POST /v1/phone-numbers/orders`

Próximos pasos

Ámbitos de la API Key
Voice API, Inicio rápido — primera llamada
SMS — número propio

Voz

Voice: Chamadas

Voice: Fluxos IVR

Números de teléfono

Números de Telefone

Números de teléfono

En resumen

Antes de empezar

1. Contratar un número

Por el panel

Por la API (`phone_numbers:create`)

2. Buscar números disponibles

3. Listar números del workspace

4. Consultar un número

5. Configurar qué hacer cuando alguien llama

Opciones de entrada

6. Webhooks de ciclo de vida

Resumen rápido

Próximos pasos

​En resumen

​Antes de empezar

​1. Contratar un número

​Por el panel

​Por la API (phone_numbers:create)

​2. Buscar números disponibles

​3. Listar números del workspace

​4. Consultar un número

​5. Configurar qué hacer cuando alguien llama

​Opciones de entrada

​6. Webhooks de ciclo de vida

​Resumen rápido

​Próximos pasos

En resumen

Antes de empezar

1. Contratar un número

Por el panel

Por la API (`phone_numbers:create`)

2. Buscar números disponibles

3. Listar números del workspace

4. Consultar un número

5. Configurar qué hacer cuando alguien llama

Opciones de entrada

6. Webhooks de ciclo de vida

Resumen rápido

Próximos pasos