Добавление номеров в существующий проект переноса

Доступ к учётной записи и проекту

Используйте активную учётную запись API для подключения по HTTPS с разрешённого IP-адреса. Проект должен принадлежать этой учётной записи и не должен быть удалён. Используйте уникальный идентификатор проекта из процесса оформления заявки на перенос, а не его числовой идентификатор в базе данных или номер телефона. При формировании запроса применяйте URL-кодирование к идентификатору проекта.

Подготовка к добавлению

Эта операция изменяет существующий проект переноса номеров. Сначала подтвердите номера и разрешение клиента в рамках своего процесса оформления заявки на перенос. Указывайте каждый номер полностью в международном формате, только цифрами, самостоятельно удаляйте дубликаты и проверяйте уже имеющийся список номеров проекта. Не используйте эту конечную точку для проверки произвольных номеров.

Текущий портал проверяет и нормализует номера перед вызовом этого маршрута. При прямом обращении к устаревшей конечной точке такие же меры защиты не обеспечиваются: она удаляет пробелы по краям входных значений, но не проверяет формат телефонного номера, код страны, наличие дубликатов или статус проекта в рабочем процессе.

Запрос POST

Создайте локальный файл numbers.json со следующей структурой. Номера вымышлены; замените их номерами, разрешёнными для выбранного проекта.

{
  "numbers": [
    "12025550123",
    "12025550124"
  ],
  "isocode": "US"
}

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --header "Content-Type: application/json" \
  --data-binary @numbers.json \
  "https://api.multitel.net/v3/lnp/project/$PROJECT_ID/addnumbers"

Поля запроса на добавление номеров
Поле	Значение
numbers	Обязательный непустой массив строк с номерами либо строка, в которой каждый номер указан с новой строки. Пустые элементы отбрасываются, а пробелы в начале и конце удаляются. Текст с разделителями-запятыми не разбивается на отдельные номера.
isocode	Необязательный код страны для добавляемых записей. Если он не указан или пуст, используется местоположение проекта. Обработчик удаляет пробелы по краям переданного значения, но не переводит его в верхний регистр и не проверяет его. Самостоятельно укажите правильный код страны в верхнем регистре.

В этом примере используйте POST с application/json. Также считываются данные формы, переданные методом POST. Метод не предусматривает ключ идемпотентности и не устанавливает гарантированный безопасный размер пакета для этой конечной точки; обрабатывайте пакеты такого размера, чтобы можно было сверить результаты, вместо того чтобы полагаться на предполагаемый лимит.

Результат, сообщаемый в ответе

Вымышленный пример ответа.

{
  "status": {
    "code": 200,
    "msg": "Success add numbers"
  },
  "response": {
    "uniqueid": "PROJECT_EXAMPLE",
    "count": 2,
    "numbers": [
      {
        "id": 21,
        "number": "12025550123",
        "status": 0,
        "status_str": "Pending",
        "isocode": "US"
      },
      {
        "id": 22,
        "number": "12025550124",
        "status": 0,
        "status_str": "Pending",
        "isocode": "US"
      }
    ]
  }
}

В ответе попытки добавления помечаются статусом Pending. Перед включением результата в ответ результат каждой вставки в базу данных не проверяется. Поэтому одно лишь количество или возвращённый идентификатор не доказывает, что каждая запись была сохранена. Добавление со статусом Pending не означает принятия оператором, назначения даты переноса или завершения активации.

Сверка перед повторной попыткой

Перед добавлением номеров получите список номеров проекта и сохраните сведения о планируемом добавлении в собственном журнале запросов.
Отправьте запрос на добавление один раз.
Снова получите список номеров проекта и сверьте каждый номер, который планировалось добавить. Проверьте наличие дубликатов и статус каждого номера.
Если время ожидания запроса истекло, получена ошибка или результат неоднозначен, повторно получите данные перед новой попыткой. Некоторые добавляемые записи уже могут существовать.
Устраните проблему отсутствующих или дублирующихся записей через процесс оформления заявки на перенос или службу поддержки, вместо того чтобы вслепую повторять весь запрос.

Обработчик вставляет записи по одной, без транзакции и защиты от дубликатов. При прерывании ранее внесённые записи могут сохраниться; неудачная вставка, возвращающая false, всё равно может быть включена в сообщаемое количество. Повторный запрос может добавить дублирующиеся записи. Сам обработчик не записывает событие и не завершает перенос номера между операторами.

Ошибки устаревшего интерфейса

При использовании метода, отличного от POST, возвращается код API 403. Для отсутствующего, удалённого или не принадлежащего учётной записи проекта возвращается код API 404. При пустых входных данных номеров также возвращается код API 404. Действуют требования аутентификации и ограничения по исходному IP-адресу. Эти коды устаревшего интерфейса не доказывают, что после начала обработки ранее не было выполнено ни одной вставки.

Оплата и границы операции переноса

Проверенный обработчик вставляет записи номеров проекта и не выполняет прямого списания средств с учётной записи или отправки заявки оператору. Это не делает услугу переноса в целом бесплатной и не отменяет согласованные сборы за перенос. Прежде чем ожидать переноса, выполните требования проекта к разрешениям, документам и проверке.