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

# Закупуване на телефонен номер

> Закупуване на специализиран телефонен номер

Този endpoint ви позволява да закупите телефонен номер, който е намерен чрез [search endpoint](/api-reference/phone-numbers/search-phone-numbers). Платформата автоматично управлява ценообразуването, фактурирането и предоставянето.

<Note>
  Трябва да имате валиден начин на плащане в профила си преди закупуване на телефонен номер. Покупката създава месечен абонамент, който ще се подновява автоматично.
</Note>

### Request Body

<ParamField body="phone_number" type="string" required>
  Телефонният номер за закупуване в E.164 формат (напр., +14155551234). Трябва да е номер, върнат от search endpoint.
</ParamField>

### Response

<ResponseField name="message" type="string">
  Съобщение за успех
</ResponseField>

<ResponseField name="data" type="object">
  Детайли за закупения телефонен номер

  <Expandable title="data properties">
    <ResponseField name="id" type="integer">
      Уникалният идентификатор на телефонния номер
    </ResponseField>

    <ResponseField name="phone_number" type="string">
      Телефонният номер в E.164 формат
    </ResponseField>

    <ResponseField name="country_code" type="string">
      ISO кодът на страната
    </ResponseField>

    <ResponseField name="type" type="string">
      Типът на телефонния номер (винаги `normal` за закупени номера)
    </ResponseField>

    <ResponseField name="sms_capable" type="boolean">
      Дали номерът поддържа SMS
    </ResponseField>
  </Expandable>
</ResponseField>

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

### Как работи

1. **Търсене** - Първо използвайте [search endpoint](/api-reference/phone-numbers/search-phone-numbers) за да намерите налични номера
2. **Закупуване** - Изпратете желания телефонен номер до този endpoint
3. **Автоматична обработка** - Платформата:
   * Валидира че номерът все още е наличен
   * Определя правилната цена въз основа на страната
   * Създава месечен абонамент към вашия метод на плащане
   * Предоставя номера чрез нашия телефонен доставчик
   * Създава записа за телефонния номер във вашия акаунт

<Warning>
  Покупките на телефонни номера не подлежат на връщане. Абонаментът ще продължи докато не [освободите номера](/api-reference/phone-numbers/release-phone-number).
</Warning>