Отправка записи о телефонном номере в справочник

Отправка записи в справочник оператора

Отправьте имя и адрес для записи в справочнике, связанной с подходящим телефонным номером, принадлежащим вам в MultiTEL. Это платное обновление у оператора, а не поиск имени звонящего, запись в личной адресной книге или обычное обновление поля LIDB в реестре номеров портала.

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

Требования к учётной записи и номеру

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

Запрос POST с данными формы

Задайте для NUMBER значение принадлежащего вам номера. Замените вымышленные данные примера согласованными сведениями для справочника. Этот маршрут считывает поля формы из POST; он не разбирает тело в формате application/json.

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --data-urlencode "lastname=EXAMPLE" \
  --data-urlencode "firstname=EXAMPLE" \
  --data-urlencode "streetnum=1" \
  --data-urlencode "streetname=Example" \
  --data-urlencode "streetpredir=N" \
  --data-urlencode "streetpostdir=W" \
  --data-urlencode "city=Example City" \
  --data-urlencode "state=NY" \
  --data-urlencode "postalcode=10001" \
  "https://api.multitel.net/v3/directory/$NUMBER"

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

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

Списание платы и повторные запросы

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

У операции нет ключа идемпотентности, защиты от повторных заказов или транзакции, объединяющей отправку оператору, локальное обновление и списание платы. Успешный повторный запрос может привести к повторной отправке оператору и ещё одному списанию. Истечение времени ожидания или ошибка API не доказывают, что оператор отклонил предыдущий запрос: поставщик услуги мог принять его до сбоя локального обновления.

Ответ

{
  "status": {
    "code": 200,
    "msg": "Success"
  },
  "response": ""
}

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

Ошибки устаревшего обработчика

Проверяйте как статус HTTP, так и поля JSON status.code/status.msg. Аутентификация и ограничения по исходному IP-адресу также могут помешать получению пригодного для использования ответа. Не используйте GET или параметры строки запроса для обновления лишь потому, что в устаревшем обработчике нет явной проверки метода HTTP.

Проверка перед повторным запросом

1. Перед отправкой запроса подтвердите принадлежность номера, возможность его обслуживания оператором, согласованные данные для справочника и размер платы.
2. Отправьте запрос один раз и сохраните результат со стороны учётной записи, не раскрывая адрес клиента в общедоступных журналах или аналитике.
3. Проверьте сохранённую запись в справочнике и историю транзакций через поддерживаемый процесс работы с учётной записью или службу поддержки. Дождитесь истечения подтверждённого оператором срока обработки; этот API не устанавливает гарантированный срок распространения изменений.
4. Если результат неясен, перед повторной попыткой попросите службу поддержки сверить заказ у оператора и локальные начисления. Повторный запрос не является идемпотентной проверкой статуса.