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

# Comprar número de teléfono

> Compra un número de teléfono dedicado en Famulor a través de la API. Adquiere números locales, móviles o de tarifa gratuita para llamadas entrantes o salientes del agente de voz de IA.

<Warning>
  **API de Famulor 1.0 (legado).** Esta página se aplica únicamente a Famulor 1.0 (`app.famulor.de`) y se conserva por compatibilidad. Para la plataforma actual, usa la [referencia de la API de Famulor 2.0](/es/api-reference/introduction).
</Warning>

Este endpoint te permite comprar un número de teléfono que se haya encontrado mediante el [endpoint de búsqueda](/es/api-v1/phone-numbers/search). La plataforma gestiona automáticamente el precio, la facturación y el aprovisionamiento.

<Note>
  Debes tener un método de pago válido registrado antes de poder comprar un número de teléfono. La compra crea una suscripción mensual que se renueva automáticamente.
</Note>

### Cuerpo de la solicitud

<ParamField body="phone_number" type="string" required>
  El número de teléfono que se va a comprar, en formato E.164 (p. ej., +14155551234). Debe ser un número devuelto por el endpoint de búsqueda.
</ParamField>

### Campos de respuesta

<ResponseField name="message" type="string">
  Mensaje de éxito
</ResponseField>

<ResponseField name="data" type="object">
  Los datos del número de teléfono comprado

  <Expandable title="Propiedades de los datos">
    <ResponseField name="id" type="integer">
      El identificador único del número de teléfono
    </ResponseField>

    <ResponseField name="phone_number" type="string">
      El número de teléfono en formato E.164
    </ResponseField>

    <ResponseField name="country_code" type="string">
      El código de país ISO
    </ResponseField>

    <ResponseField name="type" type="string">
      El tipo de número de teléfono (siempre `normal` para los números comprados)
    </ResponseField>

    <ResponseField name="sms_capable" type="boolean">
      Indica si el número admite SMS
    </ResponseField>
  </Expandable>
</ResponseField>

### Cómo funciona

1. **Buscar**: primero usa el [endpoint de búsqueda](/es/api-v1/phone-numbers/search) para encontrar números disponibles
2. **Comprar**: envía el número de teléfono deseado a este endpoint
3. **Procesamiento automático**: la plataforma:
   * Valida que el número siga disponible
   * Determina el precio correcto según el país
   * Crea una suscripción mensual en tu método de pago
   * Aprovisiona el número con nuestro proveedor de telefonía
   * Crea el registro del número de teléfono en tu cuenta

<Warning>
  Las compras de números de teléfono no son reembolsables. La suscripción continuará hasta que [liberes](/es/api-v1/phone-numbers/release) el número.
</Warning>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "message": "Phone number purchased successfully.",
    "data": {
      "id": 123,
      "phone_number": "+14155551234",
      "country_code": "US",
      "type": "normal",
      "sms_capable": true
    }
  }
  ```

  ```json 400 Already In Use theme={null}
  {
    "error": "This phone number is already in use."
  }
  ```

  ```json 400 Not Available theme={null}
  {
    "error": "This phone number is not available for purchase. Please search for available numbers first."
  }
  ```

  ```json 402 No Payment Method theme={null}
  {
    "error": "No payment method found. Please add a payment method to your account."
  }
  ```

  ```json 402 Payment Failed theme={null}
  {
    "error": "Payment failed. Please update your payment method."
  }
  ```

  ```json 422 Invalid Format theme={null}
  {
    "error": "Unable to parse phone number. Please provide a valid E.164 format number."
  }
  ```

  ```json 500 Provider Error theme={null}
  {
    "error": "Failed to purchase phone number from provider. Please contact support."
  }
  ```
</ResponseExample>