Общие сведения

Для интерактивной регистрации можно использовать HTTP-сервис внешней регистрации - ExternalRegistration

В интерактивном режиме сервис внешней регистрации работает совместно с сервисом быстрой регистрации -  FastExternalRegistration

Метод register сервиса ExternalRegistration — регистрация пользователей

Для регистрации в сервисе новых пользователей (владельцев новых абонентов) применяется метод  register  HTTP-сервиса внешней регистрации (ExternalRegistration ).

Для вызова этого метода выполняется POST-запрос следующего вида:

Запрос

POST {baseURL}/a/extreg/hs/ExternalRegistration/register/
Content-Type: application/x-www-form-urlencoded
Accept: text/html

Здесь предполагается, что HTTP-сервис внешней регистрации ExternalRegistration опубликован с относительным адресом  /a/extreg

Параметры запроса

ИмяТипОбязательныйОписание
nameСтрокаДаИмя пользователя и абонента
emailСтрокаДаАдрес электронной почты пользователя
phoneСтрокаДаНомер телефона пользователя для отправки SMS
promouserСтрокаДаИдентификатор настройки внешней регистрации (используется для определения обслуживающей организации, вида создаваемого приложения, параметров подписки на тариф сервиса, назначаемой созданному абоненту сервиса и др.)
publicidСтрока
Публичный идентификатор. Может использоваться для заполнения свойств абонента (например, для автоматического заполнения свойств организации по ИНН)
scidСтрока
Идентификатор обслуживающей организации.
unknownErrorRedirectUrlСтрока
Адрес редиректа при ошибке регистрации
userExistsErrorRedirectUrlСтрока
Адрес редиректа при указании не уникального адреса регистрации
userExistsErrorRedirectMethodPostБулево
Выполнять метод POST при перенаправлении на страницу ошибки при не уникальном адресе регистрации. При этом все параметры, полученные в запросе /register также будут переданы в POST-запрос по указанному адресу.
timezoneСтрока

Часовой пояс. Желательно указывать для корректных рассылок писем.
Значение можно получать на клиенте с помощью JavaScript:

Intl.DateTimeFormat().resolvedOptions().timeZone;

Если параметр не будет заполнен, и запрос будет выполнен из браузера, то будет возвращена страница с попыткой заполнения параметра автоматически.

promoЧисло
Идентификатор сайта
adsrcЧисло
Идентификатор источника интереса
sendemailБулево
Признак отправки уведомления о регистрации по электронной почте.
ssoСтрока
Служебный JWT-токен SSO провайдера аутентификации сервиса. Токен заполняется из входящих параметров при регистрации с использованием стороннего провайдера аутентификации.
userinfoСтруктура
Информация о пользователе, аналогичная выдаваемой провайдером аутентификации. Используется для заполнения свойств абонента.
access_tokenСтрока
Токен доступа стороннего провайдера аутентификации. Может запоминаться в свойствах приглашения при регистрации через стороннего провайдера. Используется для заполнения свойств абонента.


Замечание

Если параметр  scid указан, то обслуживающая организация для регистрируемого абонента назначается по следующим правилам.

Если идентификатор, указанный в значении параметра  scid

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

Замечание

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

Если идентификатор, указанный в значении параметра  scid

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

Дополнительные параметры при использовании промокодов

ИмяТипОбязательныйОписание
promocode Строка
Промокод
subidСтрока
Дополнительная информация о промокоде (например, метод его распространения)
promocodeNotFoundRedirectUrlСтрокаДаАдрес редиректа при ошибке отсутствия промокода.
promocodeBlockedRediretUrlСтрокаДаАдрес редиректа при ошибке блокировки промокода.
promocodeExpiredRedirectUrlСтрокаДаАдрес редиректа при ошибке истечения срока использования промокода.
promocodeActivationNumberIsExhaustedUrlСтрокаДаАдрес редиректа при ошибке исчерпания количества активаций промокода.

Дополнительные параметры при использовании защиты от автоматических действий

При использовании в сервисе защиты от автоматических действий среди параметров запроса к HTTP-сервису внешней регистрации может быть необходимо указывать параметр, значение которого возвращается сервисом проверки CAPTCHA (различения людей и роботов). Для сервиса Google reCAPTHA имя этого параметра  g-recaptcha-response . Без указания этого параметра в запросе к HTTP-сервису внешней регистрации в регистрации пользователя может быть отказано.

Также в запросе к HTTP-сервису внешней регистрации указывается адрес редиректа при определении что пользователь это робот.

ИмяТипОбязательныйОписание
g-recaptcha-responseСтрока
Строка, возвращенная сервисом проверки CAPTCHA
userIsRobotRedirectUrlСтрока
Адрес редиректа при определении что пользователь это робот

Пример страницы для выполнения запроса

<form action="https://1cfresh.com/a/httpextreg/hs/ExternalRegistration/register" method="post" onsubmit="document.getElementById('timezone').value = Intl.DateTimeFormat().resolvedOptions().timeZone; return true;" novalidate="novalidate">
    <label>Ваше имя:</label> <input name="name"/>
    <label>Ваш e-mail:</label> <input name="email"/>
    <label>Ваш телефон:</label> <input name="phone"/>
    <input type="hidden" name="promouser" value="ExternalRegistration"/>
    <input type="hidden" name="publicid"/> <!-- Можно использовать для указания ИНН -->
    <input type="hidden" name="scid"/> <!-- Можно использовать для указания идентификатора обслуживающей организации -->
    <input type="hidden" name="timezone" id="timezone"/>
    <input type="hidden" name="unknownErrorRedirectUrl" value="https://1cfresh.com/a/httpextreg/hs/ExternalRegistration/register#msgUnknownError"/>
    <input type="hidden" name="userExistsErrorRedirectUrl" value="https://1cfresh.com/a/httpextreg/hs/ExternalRegistration/register#msgEmailExists"/>
    <input type="submit" value="Начать работу"/>
</form>

Возвращаемое значение

  • Если для сайта доступна быстрая регистрация, то производится редирект 302 на сервис быстрой регистрации:
     {baseURL}/a/httpextreg/hs/FastExternalRegistration/CompleteRegistration/{id}, где id – идентификатор приглашения
    • В случае, если приложение не готово, выполняется перезагрузка страницы.
    • Если приложение готово, производится редирект на адрес приложения.
  • Если для сайта не доступна быстрая регистрация, то производится редирект 302 на адрес активации через сервис внешней регистрации
  • Если адрес активации через сервис внешней регистрации не используется, то осуществляется редирект на адрес активации по приглашению

Если сервисом поддерживается быстрая регистрация, можно завершить регистрацию с помощью сервиса  FastExternalRegistration.

Обработка ошибок

Если указаны параметры редиректов, то производится редирект с кодом 302 на указанный адрес. Если адрес этого редиректа не указан, возвращается исключение с кодом 500 и текстом ошибки.

Возможные адреса редиректов:

СитуацияАдрес редиректа
Не указан адрес электронной почтыunknownErrorRedirectUrl
Указанный адрес электронной почты уже используетсяuserExistsErrorRedirectUrl
В сервисе используется защита от автоматических действия и сервер CAPTCHA определил, что пользователь это роботuserIsRobotRedirectUrl
Прочие ошибкиunknownErrorRedirectUrl

Метод bind сервиса ExternalRegistration — привязка пользователей 

Для сопоставления (привязки) пользователя стороннего провайдера аутентификации и учетной записи существующего пользователя сервиса применяется метод bind HTTP-сервиса внешней регистрации ExternalRegistration.

Для вызова этого метода выполняется POST-запрос следующего вида:

Запрос

POST {baseURL}/a/extreg/hs/ExternalRegistration/bind/
Content-Type: application/x-www-form-urlencoded
Accept: text/html

Здесь предполагается, что HTTP-сервис внешней регистрации ExternalRegistration опубликован с относительным адресом  /a/extreg

Параметры запроса

ИмяТипОбязательныйОписание
loginСтрока
Имя (логин) пользователя
passwordСтрока
Пароль пользователя
ssoСтрокаДаСлужебный JWT-токен SSO с параметрами привязки, передаваемый провайдером аутентификации сервиса.
return_toСтрока
Адрес возврата
cmdСтрока
Команда выполнения перехода на адрес возврата. В случае, если для параметра return_to нужно выполнить метод POST c передачей полученных в форму привязки параметров, нужно указать значение параметра cmd=form.

Если параметры  return_to и/или  cmd не заданы в параметрах запроса, используются значения из соответствующих полей JWT-токена SSO OpenID-провайдера аутентификации сервиса. 

Параметр return_to должен содержать адрес, с разрешенным для перехода именем сайта. Разрешенные имена сайта задаются администратором сервиса.

Обработка ошибок

В следующих случаях возвращается ответ с HTTP-кодом состояния 400 и текстом ошибки:

  • не указан параметр sso
  • если для стороннего провайдера аутентификации не разрешена привязка
  • если в поле scope  JWT-токена SSO провайдера аутентификации не найдена строка bind
  • не указано корректное значение адреса возврата ( return_to ).

Вывод окна привязки

Если при вызове не был указан параметр  login , выводится окно привязки (по шаблону текстов Страница привязки).

Результат выполнения

После успешного выполнения привязки существующий пользователь сервиса сможет входить в приложения сервиса, используя аутентификацию стороннего провайдера аутентификации. Сразу после привязки пользователь переходит по адресу возврата, указанному в параметре привязки  return_to JWT-токена SSO, или параметра запроса, если он указан

Сервис FastExternalRegistration

Сервис позволяет быстро зарегистрировать приложение пользователя.

Запрос

GET {baseURL}/a/fastreg/hs/FastExternalRegistration/ComleteRegistration/{registration_code}
Content-Type: application/x-www-form-urlencoded
Accept: text/html

Здесь предполагается, что HTTP-сервис FastExternalRegistration опубликован с относительным адресом /a/fastreg

Параметры запроса

ИмяОписаниеТип
registration_codeИдентификатор приглашения для регистрацииСтрока

В процессе подготовки производится редирект на страницу подготовки приложения. 

После завершения подготовки приложения производится редирект на страницу с приложением и осуществляется вход пользователя в приложение без ввода данных регистрации.

В случае ошибок возвращается ответ с HTTP-кодом состояния  500 .