Подготовьте сохранённый профиль и номер
Используйте этот процесс, чтобы связать сохранённый регистрационный профиль с приобретённым номером и, для поддерживаемых номеров, обслуживаемых оператором, запросить проверку регистрации. Это не универсальный API активации для всех поставщиков номеров. Успешный запрос не подтверждает, что документы одобрены или номер активен.
Используйте включённую учётную запись API MultiTEL через HTTPS с настроенными для неё учётными данными и ограничениями по IP. Как неудалённый профиль, так и приобретённый, неаннулированный номер должны принадлежать вашей учётной записи.
- Создайте регистрационный профиль или выберите существующий. Сохраните uuid локального профиля из create_document; get_document возвращает тот же локальный идентификатор в поле id.
- Для отправки оператору в профиле должны быть сохранены ссылки на идентификационные данные и адрес. До отправки приложите необходимые подтверждения и сопроводительные документы с помощью соответствующих процессов.
- Убедитесь, что номер и профиль соответствуют применимым требованиям для страны и номера. Не считайте, что сохранённый профиль одобрен для любого номера.
Отправьте запрос на связывание
curl --silent --show-error --request POST \
--user "$API_USER:$API_PASSWORD" \
--form-string document_uuid="$PROFILE_UUID" \
--form-string service_description="Example customer support line" \
https://api.multitel.net/v3/number_identity/12125550123Путь содержит приобретённый телефонный номер, а не его UUID, внутренний номер АТС или идентификатор идентификационных данных. Обработчик удаляет из номера все символы, кроме цифр. Используйте полный международный номер с кодом страны. Пример вымышленный: замените его своим номером и сохранённым идентификатором локального профиля.
| Поле | Обязательное | Значение |
|---|---|---|
document_uuid | Да | Точное сохранённое значение uuid локального профиля. Не подставляйте вместо него маскированные удалённые identity_id, address_id, идентификатор загруженного файла или возвращённое значение registration_details_id. |
service_description | Нет | Описание предполагаемой услуги, передаваемое оператору для проверки. Пробелы в начале и конце удаляются. |
onetime_files | Зависит от процесса | Массив для документов разового использования, передаваемых оператору. Текущий обработчик удаляет пробелы по краям строк и передаёт их дальше, не преобразуя локальные ссылки на загруженные файлы. Совместимость с маскированными идентификаторами, возвращаемыми create_encrypt_files, не установлена; перед использованием этого поля ознакомьтесь с приведённым ниже ограничением для документов разового использования. |
В составных запросах массив передаётся повторяющимися полями onetime_files[]. Также принимается запрос JSON с Content-Type: application/json; его свойства объединяются с данными формы. Поле number можно передать в теле запроса, если номер отсутствует в пути. Чтобы избежать неоднозначности, используйте явно указанный путь, показанный выше.
Различайте связывание и одобрение
Проверяйте как результат HTTP, так и status.code в JSON. Ошибки в JSON могут приходить с HTTP 200. При успешной отправке оператору возвращается сообщение Address verification task created; awaiting carrier review. В этом примере используются вымышленные идентификаторы.
{
"status": {
"code": 200,
"msg": "Address verification task created; awaiting carrier review."
},
"response": {
"number": "+12125550123",
"did_id": "11111111111111111111111111111111",
"document_uuid": "0123456789abcdef0123456789abcdef",
"identity_id": "22222222222222222222222222222222",
"address_id": "33333333333333333333333333333333",
"address_verification_id": "44444444444444444444444444444444",
"verification_status": "pending",
"verification_reference": null,
"requirement_id": "55555555555555555555555555555555",
"registration_details_id": "8516ac99dc60603295de7bdb6a153530"
}
}Идентификаторы, связанные с поставщиком, являются маскированными ссылками, а не взаимозаменяемыми идентификаторами локального профиля. document_uuid остаётся переданным вами идентификатором локального профиля. В ветви этого обработчика, выполняющей отправку оператору, registration_details_id представляет собой дополнительный хеш этого локального идентификатора; не заменяйте им document_uuid в последующих запросах к профилю или запросах на отправку.
Для некоторых выделенных номеров вместо создания проверки у оператора выполняется локальное связывание идентификационных данных. При успехе возвращается сообщение Identity associated. с пустым массивом response. Это не создаёт задачу проверки оператором и не подтверждает одобрение. В портале используется более новый процесс связывания, в котором обработка поставщиков и проверки повторной отправки отличаются от этого метода API.
Обрабатывайте ошибки, не создавая дубликаты задач
Код API 400 означает отсутствие номера или ссылки на профиль. Код 404 означает, что профиль или номер недоступен для учётной записи либо номер отсутствует в реестре оператора. Код 422 может сообщать об отсутствии ссылок на идентификационные данные или адрес, требованиях продавца либо отклонении при проверке оператором. Отсутствие настройки обратного вызова может привести к коду 503, а транспортный сбой при создании — к коду 502. Читайте сообщение и имеющиеся requirement_diagnostics, а не обрабатывайте все сбои одинаково.
Ветвь отправки оператору может обновить локальные флаги ожидания регистрации до завершения проверки требований, проверки настройки обратного вызова или создания задачи. Поэтому ошибка не означает, что локальное состояние осталось неизменным, а сам по себе флаг ожидания не доказывает существование задачи. Не используйте эти флаги как подтверждение одобрения или доставки запроса.
Поставщик может принять задачу, даже если последующая операция с локальной базой данных завершится ошибкой, а эта вспомогательная функция проверяет не все результаты локальной записи, прежде чем сообщить об успехе. В этом обработчике нет параметра идемпотентности клиента или защиты от повторной отправки. После истечения времени ожидания, ошибки или неопределённого результата проверьте историю регистрации номера в портале или обратитесь в службу поддержки, прежде чем отправлять запрос повторно. Само по себе отсутствие локальной записи не доказывает, что поставщик ничего не получил.
Ограничение для документов разового использования
Обработчик принимает onetime_files и передаёт каждую непустую строку в связь с зашифрованными файлами у оператора. Он не ищет записи о загрузках учётной записи владельца и не преобразует внешние маскированные идентификаторы загрузок в идентификаторы файлов поставщика. Проверка без обращения к работающей системе подтвердила поведение при передаче, но не успешное прикрепление файлов у оператора.
Не считайте, что идентификатор файла из create_encrypt_files можно скопировать в это поле для завершения процесса оформления разового соглашения. Если для номера требуются такие документы, используйте портал или уточните у MultiTEL поддерживаемый порядок работы с идентификаторами. Эта часть проверки API остаётся нерешённой и не является проверенным сквозным примером.
Защищайте регистрационные сведения
Отправляйте только те сведения и документы, которые вы вправе использовать для этого номера. Сохраняйте привязку ссылок на профиль и проверки к правильной учётной записи и избегайте записи полных регистрационных данных запроса в журналы. Этот запрос не удаляет и не заменяет все предыдущие подтверждения или проверки. Проверка оператором, активация и хранение данных — отдельные процессы.