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

HTTP-cервис менеджера сервиса ПромоРегистрация предназначен для регистрации пользователя в сервисе 1cFresh и выполняет следующие операции:

  1. Создание нового абонента
  2. Создание нового пользователя абонента
  3. Создание приложения нового абонента и оформление подписки на тариф
  4. Оповещение пользователя о регистрации в сервисе и создании приложения.

Пример настройки сервиса для использования программной регистрации 

Общие параметры, используемые в запросах к сервису

Имя

Описание

Пример

server

Адрес сервера сервиса.https://1cfresh.com
regАдрес сервиса регистрации.a/adm/hs/promo_reg

authorization

Данные авторизации

Basic cG9ydGFsX3JlZzoxMjNRd2Vy


Обычно HTTP-cервис менеджера сервиса ПромоРегистрация публикуется во внешней публикации менеджера сервиса. Корневое имя HTTP-cервиса promo_reg. 

Общие параметры ответов всех методов

Параметр

Тип

Описание

errorБулевоУказывает, что во время выполнения метода возникла ошибка.
responseЧислоКод возврата. У каждого метода свой набор кодов возврата.
messageСтрокаКомментарий к выполненной операции (например, описание ошибки).

Пользователю менеджера сервиса, от имени которого вызывается какой-либо метод сервиса, должны быть назначены роли:

  • УдаленныйДоступБыстраяРегистрация
  • УдаленныйДоступВнешняяРегистрация

Также в информационной базе менеджера сервиса должны быть штатным образом настроены разрешения внешней регистрации.

Методы сервиса ПромоРегистрация

Сервис ПромоРегистрация поддерживает следующие методы:

Метод

Назначение

check_userПроверяет существование в сервисе пользователя с указанным логином
sign_upИнициирует регистрацию абонента в сервисе и создание нового приложения (тип приложения определяется настройками внутри сервиса)
get_user_idВозвращает идентификатор пользователя сервиса по его логину
get_app_urlВозвращает URL созданного приложения по указанному логину пользователя
send_notificationОтправляет пользователю оповещение о результатах регистрации

Метод check_user

Проверяет существование в сервисе пользователя с указанным логином.

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

Параметр

Тип

Обязательный

Значение

loginСтрокаДаЛогин пользователя в сервисе (адрес электронной почты).
validate_emailБулевоНетЕсли Истина, то проверяет адрес электронной почты на соответствие требованиям RFC 5321, RFC 5322, RFC 5335, RFC 5336 и RFC 3696. По умолчанию = Ложь.

Параметры ответа

Параметр

Тип

Значение

urlСтрокаURL приложения, созданного при регистрации (если приложение уже подготовлено).
accountЧислоКод абонента, созданного при регистрации.
tenantЧислоНомер области, адрес которой приведен в параметре url.

Пример запроса

POST {{server}}/{{reg}}/check_user
Authorization: {{authorization}}
 
{
  "login":"user@mail.com",
  "validate_email": true
}

Пример ответа для организации, регистрировавшей абонента

{
  "error": false,
  "response": 10201,
  "message": "Указанный адрес электронной почты уже используется.",
  "url": "https://1cfresh.com/a/smtl/20",
  "tenant": 20,
  "account": 11
}

Пример ответа для прочей обслуживающей организации

{
  "error": false,
  "response": 10403,
  "message": "Указанный адрес электронной почты уже используется.",
  "url": "",
  "tenant": 0,
  "account": 0
}

Пример запроса с некорректным адресом электронной почты

POST {{server}}/{{reg}}/check_user
Authorization: {{authorization}}
 
{
  "login":"user_mail.com",
  "validate_email": true
}

Пример ответа при некорректном адресе электронной почты

{
  "error": true,
  "response": 10400,
  "message": "Указан некорректный адрес электронной почты.",
  "url": "",
  "tenant": 0,
  "account": 0
}

Возможные коды ответа

Код

Значение

10200Пользователь существует
10400Обязательные параметры либо не указаны, либо некорректны

10403

Пользователь существует, информация по пользователю не доступна
10404Пользователь с указанным логином не найден
10500Внутренняя ошибка


Параметры ответа urlaccount и tenant метода check_user заполняются только в том случае, когда запрашивается информация о пользователях, которые были ранее зарегистрированы методом sign_up от имени того же самого служебного пользователя. Если запрашивается информация о пользователе, который был зарегистрирован в сервисе каким-то другим способом (или от имени другого служебного пользователя), параметры urlaccount и tenant не заполняются.

Метод sign_up

Инициирует регистрацию абонента в сервисе и, опционально, создание нового приложения. Тип создаваемого приложения определяется настройками внешней регистрации менеджера сервиса.

Перед регистрацией переданный адрес электронной почты проверяется на соответствие требованиям стандартов (RFC 5321, RFC 5322, RFC 5335, RFC 5336 и RFC 3696).

Если в настройках внешней регистрации для пользователя, от имени которого вызывается метод сервиса, указан провайдер аутентификации, то:

  • если в запросе передан идентификатор пользователя этого провайдера (параметр sso_user_id), то после регистрации становится доступен вход в приложения этого пользователя через указанного провайдера аутентификации;
  • если в запросе указан параметр user_info, то при регистрации будет выполнено заполнение свойств созданного абонента согласно правилу трансляции, заданному в свойствах указанного провайдера аутентификации в менеджере сервиса.

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

Параметр

Тип

Обязательный

Значение

nameСтрокаДаИмя пользователя (отображаемое имя, не логин)
emailСтрокаДаАдрес электронной почты. Также является логином пользователя в сервисе
phoneСтрока
Контактный телефон пользователя (не обязательный)
tariffСтрока
Код тарифа, на который нужно подписать абонента. Если не указан, будет использован тариф, заданный в настройках системы по умолчанию
validityЧисло
Продолжительность действия подписки в днях, если для выбранного тарифа не используются периоды действия. Если параметр не указан, будет использовано значение, заданное в настройках системы по умолчанию.
Если параметр tariff заполнен и для выбранного тарифа не используются периоды действия, то параметр validity также должен быть заполнен.
periodСтрока
Код периода действия подписки. Если параметр tariff заполнен и для выбранного тарифа используются периоды действия, то параметр period также должен быть заполнен

tenants_count

Число
Количество создаваемых приложений. Если не указано, создается одно приложение
fast_completionБулево
Указывает, что необходимо сразу же инициировать процесс подтверждения регистрации и начать подготовку приложения
send_notificationБулево
Указывает, что необходимо отправить уведомление на почту пользователя сразу же после регистрации (по умолчанию = Истина)
sso_user_idСтрока
Идентификатор пользователя провайдера аутентификации 
user_infoСтруктура
Информация о пользователе, аналогичная выдаваемой провайдером аутентификации. Используется для заполнения свойств абонента
promocodeСтрока
Промокод
subidСтрока
Дополнительная информация о промокоде (например, метод его распространения)

Если в настройках внешней регистрации для пользователя, от имени которого вызывается метод сервиса, указан провайдер аутентификации, то:

  • если в запросе передан идентификатор пользователя этого провайдера (параметр sso_user_id), то после регистрации становится доступен вход в приложения этого пользователя через указанного провайдера аутентификации;
  • если в запросе указан параметр user_info, то при регистрации будет выполнено заполнение свойств созданного абонента согласно правилу трансляции, заданному в свойствах указанного провайдера аутентификации в менеджере сервиса.

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

Параметры ответа

Параметр

Тип

Значение

registration_codeСтрокаРегистрационный код (код приглашения). Это справочная информация, для дальнейших действий она не требуется

Пример запроса с указанием непериодического тарифа

POST {{server}}/{{reg}}/sign_up
Authorization: {{authorization}}
 
{
  "email":"user@mail.com",
  "name": "User",
  "fast_completion": true,
  "send_notification": false,
  "tariff": "2",
  "validity": "30",
  "tenants_count": 1 
}

Пример ответа

{
  "error": false
  "response": 10202
  "message": " "
  "registration_code": "9fdb128e-bb3a-11e7-6381-08002798b77b"
}

Пример запроса с указанием периодического тарифа

POST {{server}}/{{reg}}/sign_up
Authorization: {{authorization}}
 
{
  "email":"user@mail.com",
  "name": "User",
  "fast_completion": true,
  "send_notification": false,
  "tariff": "4",
  "period": "6MN",
  "tenants_count": 1  
}

Пример ответа

{
  "error": false
  "response": 10202
  "message": " "
  "registration_code": "9fdb128e-bb3a-11e7-6381-08002798b77b"
}

Пример запроса с заполнением свойств абонента

POST {{server}}/{{reg}}/sign_up
Authorization: {{authorization}}
 
{
  "email":"pupkin@yopmail.com",
  "name": "Василий Пупкин",
  "sso_user_id": "portal_id",
  "user_info":
    {
      "ev_token": "1234-5678-9800"
    }
}

Пример ответа

{
  "error": false
  "response": 10202
  "message": " "
  "registration_code": "9fdb128e-bb3a-11e7-6381-08002798b77b"
}

Приведение к периодам продолжительности действия подписки, указанной в днях

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

Если в запросе был указан параметр validity, выбранный тариф периодический и было успешно выполнено приведение продолжительности действия подписки к допустимому значению, то метод sign_up вернет код ответа 10242, а в параметре ответа message будет содержаться сообщение об автоматическом приведении продолжительности действия подписки к допустимому значению.

Пример ответа при точном совпадении количества дней по периоду тарифа с переданным validity = 183

{"error": false,
"response": 10242,
"message": "Для периодического тарифа требуется указание кода периода параметром 'period' вместо указанного параметра 'validity'.",
"registration_code": "6c6df62a-b9ce-11e9-7f9e-0242ac160004"}


Пример ответа при неточном указании количества дней периодом validity = 180

{"error": false,
"response": 10242,
"message": "Для периодического тарифа требуется указание кода периода параметром 'period' вместо указанного параметра 'validity'. Количество дней скорректировано в соответствии с периодом '6MN'",
"registration_code": "19060faa-b9cd-11e9-7f9e-0242ac160004"}

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

Возможные коды ответа

Код

Значение

10202Запрос на регистрацию успешно принят к обработке, регистрационный код возвращен в параметре registration_code
10242Запрос на регистрацию успешно принят к обработке, однако параметры запроса были скорректированы. Регистрационный код возвращен в параметре registration_code
10400Обязательные параметры либо не указаны, либо некорректны
10400

Идентификатор пользователя не может быть привязан

10404Не найден тариф с указанным кодом.
10406Некорректное значение количества приложений. Ожидается положительное число
10406Указанный идентификатор пользователя уже используется
10412Количество приложений превышает доступный лимит по тарифу
10409Указанный адрес электронной почты уже используется в сервисе
10500Внутренняя ошибка

Сообщение "Идентификатор пользователя не может быть привязан" выводится, если не указан сторонний провайдер аутентификации или не разрешена регистрация для указанного провайдера.

Сообщение "Указанный идентификатор пользователя уже используется" выводится, если параметр sso_user_id передан и уже используется для текущего провайдера.

Сообщение "Не найден провайдер сторонней аутентификации" выводится, если в запросе указан параметр  sso_user_id, но в настройках внешней регистрации для пользователя, от имени которого вызывается метод сервиса, провайдер аутентификации не задан.

Метод get_user_id

Возвращает идентификатор пользователя сервиса по его логину.

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

Параметр

Тип

Обязательный

Значение

loginСтрокаДаЛогин пользователя в сервисе (адрес электронной почты).

Параметры ответа

Параметр

Тип

Значение

userid

СтрокаИдентификатор пользователя сервиса.

Пример запроса

POST {{server}}/{{reg}}/get_user_id
Authorization: {{authorization}}
 
{
  "login":"user@mail.com"
}

Пример ответа

{
  "error": false,
  "response": 10200,
  "message": "",
  "userid": "80f69852-eb3b-11e7-819b-0050568925e0"
}
Параметр ответа userid заполняется только в том случае, когда запрашивается информация о пользователях, которые были ранее зарегистрированы методом sign_up от имени того же самого служебного пользователя. Если запрашивается информация о пользователе, который был зарегистрирован в сервисе каким-то другим способом (или от имени другого служебного пользователя), параметр userid не заполняются.

Метод get_app_url

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

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

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

Параметр

Тип

Обязательный

Значение

loginСтрокаДаЛогин пользователя в сервисе (адрес электронной почты).
send_notificationБулевоНетУказывает, что необходимо отправить уведомление на почту пользователя сразу же после подготовки приложения.

Параметры ответа

Параметр

Тип

Значение

urlСтрока, Массив

Адрес перехода после регистрации:

  • если регистрация приложения завершена, возвращается постоянный адрес приложения. Если запрашивалось создание нескольких приложений, то возвращается массив.
  • если регистрация не завершена, возвращается адрес страницы завершения регистрации
accountЧислоКод абонента, созданного при регистрации
appСтрокаИмя приложения (код конфигурации приложения)
tenantЧисло, МассивНомер области, адрес которой приведен в параметре url. Если запрашивалось создание нескольких приложений, то возвращается массив
permanent_urlСтрока, МассивПостоянный адрес приложения (возвращается в любом случае, даже пока приложение не готово к использованию). Если запрашивалось создание нескольких приложений, то возвращается массив
subscription_idСтрокаНомер подписки созданной по приглашению для регистрации
subscription_completionДатаДата окончания подписки созданной по приглашению для регистрации

Пример запроса

POST {{server}}/{{reg}}/get_app_url
Authorization: {{authorization}}
 
{
  "login":"user@mail.com",
  "send_notification": false
}

Пример ответа

{
  "error": false,
  "response": 10201,
  "message": "",
  "url": "https://1cfresh.com/a/smtl/20",
  "tenant": 20,
  "account": 3,
  "app": "smtl",
  "permanent_url": "https://1cfresh.com/a/smtl/20",
  "subscription_id": "000000007",
  "subscription_completion": "2020-08-06T23:59:59"
}

Пример ответа при запросе нескольких приложений

{  
   "error":false,
   "response":10201,
   "message":"",
   "url":[  
      "https://1cfresh.com/a/smtl/20",
      "https://1cfresh.com/a/smtl/21",
      "https://1cfresh.com/a/smtl/22"
   ],
   "tenant":[  
      20,
      21,
      22
   ],
   "account":3,
   "app":"smtl",
   "permanent_url":[  
      "https://1cfresh.com/a/smtl/20",
      "https://1cfresh.com/a/smtl/21",
      "https://1cfresh.com/a/smtl/22"
   ],
  "subscription_id": "000000008",
  "subscription_completion": "2020-08-06T23:59:59"
}

Пример ответа при отсутствии завершенной регистрации

{
  "error": false,
  "response": 10500,
  "message": "По указанному логину пользователя не обнаружено завершенной регистрации.",
  "url": "",
  "tenant": 0,
  "account": 0,
  "app": "",
  "permanent_url": "",
  "subscription_id": "",
  "subscription_completion": ""
}

Возможные коды ответа

Код

Значение

10201Приложение успешно создано, адрес возвращен в параметре url.
10102Приложение в процессе создания, необходимо обратиться позже
10400Обязательные параметры либо не указаны, либо некорректны
10408Истекло допустимое время быстрой регистрации
10409Пользователь был зарегистрирован в сервисе другим партнером
10500Внутренняя ошибка

Метод send_notification

Отправляет пользователю оповещение о результатах регистрации.

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

Параметр

Тип

Обязательный

Значение

loginСтрокаДаЛогин пользователя в сервисе (адрес электронной почты)

Пример запроса

POST {{server}}/{{reg}}/send_notification
Authorization: {{authorization}}
 
{
  "login":"user@mail.com"
}

Пример ответа если оповещение отправлено

{
  "error": false,
  "response": 10200,
  "message": ""
}

Возможные коды ответа

Код

Значение

10200Оповещение успешно отправлено
10403У текущего пользователя нет доступа на отправку оповещения этому пользователю
Оповещение отправляется только в том случае, если запрос отправляется от имени того же пользователя, который ранее регистрировал клиента методом sign_up.