Разработка:sync/soap

Материал из DOF
Версия от 17:10, 22 сентября 2014; Konovalov (обсуждение | вклад) (Коды ошибок)
Перейти к: навигация, поиск
Плагин
Название soap
Тип sync


Описание

Веб-сервис для интеграции с другими системами по протоколу SOAP. Плагин использует инфраструктуру storages/sync для хранения соответствия внутренних и внешних id объектов и storages/synclog для логирования всех операций синхронизации.

Плагин объявляет SOAP-сервис, который располагается по адресам:

  • /sync/soap/soap.php?do=wsdl - wsdl-файл
  • /sync/soap/soap.php?do=service - сам сервис

У каждого метода присутствуют следующие обязательные служебные параметры:

  • requestime - время генерации запроса, используется для устаревания запроса с целью защиты от атаки на "повторение перехваченного запроса"
  • requestlogin - идентифицирует систему-отправитель запроса (задается в sync/soap/cfg/clients.php, вместе с паролем requestpassword и необязательными параметрами)
  • requesthash - sha1-хеш от всех полей запроса в алфавитном порядке, включая предыдущие два, а так же поля requestpassword (в самом запросе не участвует). Используется для подтверждения подлинности запроса.

Имена полей soap-запросов должны совпадать с именами полей в справочниках: storages/metacontracts , storages/persons , storages/contracts

Во всех запросах используются только внешние id. Например, при создании персоны новая система передает свой уникальный id, которым она её обозначает. Этот id сохраняется в storages/sync . При создании контракта на обучение, внешняя система передает свой собственный id персоны (которая была создана ранее), плагин sync/soap конвертирует этот id во внутренний через справочник storages/sync и создает запись в storages/contracts . Если внешний id объекта не передан, запрос возвращает ошибку (объект не создается и не обновляется).

Служебные, специальные и автоматически-вычисляемые поля справочников не доступны для редактирования через SOAP-запросы (например adddate, status). Действия, которые запрещены пользователям системы через интерфейс, запрещены и через SOAP-запросы (например, нельзя сменить персону в уже созданном контракте).

Все запросы обрабатывают вложенный массив cov. Все поля внутри массива cov сохраняются (обновляются) в справочнике storages/cov . Не упомянутые в запросе поля (ранее сохраненные в cov) игнорируются. Все имена полей, присутствующие в соответствующем справочнике зарезервированы и не могут быть переданы через массив cov (например, нельзя сохранить поле cov/status для объекта persons, потому что в нем уже есть поле status).

Подразделение для размещения объекта передается в SOAP-запросах через его код (code), а не id. Успешная операция для методов типа 'set_' возвращает следующую структуру данных:

  • id - переданный в запросе id объекта
  • dofid - внутренний id объекта
  • modified - время изменения объекта
  • hash - контрольная сумма из storages/sync
  • errorcode - код ошибки, помогающий идентифицировать проблему при исполнении запроса

Для проверки SOAP-запросов используется хеширование по следующему алгоритму:

  • requesthash == sha1(requestpassword + requesttime + requestlogin + json(vars) + json(cvars)), где
    • vars формируется следующим образом:
      • Из полей объекта для SOAP-запроса исключаются служебные данные — requesthash, requestlogin, requesttime и дополнительный массив cov
      • Поля сортируются в алфавитном порядке;
    • cvars — вложенный массив cov, поля которого так же сортируются в алфавитном порядке;
    • json() - функция для преобразования массива/объекта в json-строку.
    • Знаком "+" указана конкатенация строк.

API

set_meta_contract($input)

Аргументы:

  • input(object) - данные метаконтракта, переданные по SOAP. Содержит следующие поля
    • requestlogin - Идентификатор системы-отправителя запроса
    • requesttime - Время генерации запроса
    • requesthash - sha1-хеш
    • id - Внешний id метаконтракта
    • num - Номер метаконтракта
    • departmentcode - Код подразделения
    • cov - Дополнительный массив cov, содержащий дополнительные поля к объекту

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

  • (object) - объект со следующими полями
    • id - Внешний id объекта (переданный в запросе id)
    • dofid - Внутренний id объекта
    • modified - Дата модификации созданного или обновлённого объекта
    • hash - Хеш операции в storage/sync
    • errorcode - Код ошибки, если таковые возникли


set_person($input)

Аргументы:

  • input(object) - данные персоны, переданные по SOAP. Содержит следующие поля
    • requestlogin - Идентификатор системы-отправителя запроса
    • requesttime - Время генерации запроса
    • requesthash - sha1-хеш
    • id - Внешний id метаконтракта
    • firstname - Имя
    • middlename - Отчество
    • lastname - Фамилия
    • preferredname - Префикс для имения (Mr. Dr. Г-н, Г-а)
    • dateofbirth - Дата рождения в UTS
    • gender - Пол (male, female, unknown)
    • email - Основной адрес электронной почты
    • phonehome - Домашний телефон
    • phonework - Рабочий телефон
    • phonecell - Сотовый телефон
    • passtypeid - Тип удостоверения личности (1 - свидетельство о рождении, 2 - паспорт гражданина РФ, 3 - загранпасспорт, 4 - разрешение на временное проживание лица без гражданства, 5 - вид на жительство, 6 - военный билет, 7 - водительсткое удостоверение пластиковое, 8 - вод. удостоверение форма 1, 9 - вод. удостоверение международное)
    • passportserial - Серия удостоверения личности (если предусмотрена типом документа)
    • passportnum - Номер удостоверения личности
    • passportdate - Дата выдачи удостоверения личности в UTS
    • passportem - Название организации, выдавшей удостоверение личности
    • citizenship - Гражданство
    • departmentcode - Основной отдел, к которому приписан человек (может редактировать его данные в persons)
    • about - Характеристика личности
    • skype - Уникальный идентификатор в Skype
    • phoneadd1 - Дополнительный телефон 1
    • phoneadd2 - Дополнительный телефон 2
    • phoneadd3 - Дополнительный телефон 3
    • emailadd1 - Дополнительная электронная почта 1
    • emailadd2 - Дополнительная электронная почта 2
    • emailadd3 - Дополнительная электронная почта 3
    • cov - Дополнительный массив cov, содержащий дополнительные поля к объекту

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

  • (object) - объект со следующими полями
    • id - Внешний id объекта (переданный в запросе id)
    • dofid - Внутренний id объекта
    • modified - Дата модификации созданного или обновлённого объекта
    • hash - Хеш операции в storage/sync
    • errorcode - Код ошибки, если таковые возникли


set_contract($input)

Аргументы:

  • input(object) - данные договора, переданные по SOAP. Содержит следующие поля
    • requestlogin - Идентификатор системы-отправителя запроса
    • requesttime - Время генерации запроса
    • requesthash - sha1-хеш
    • id - Внешний id договора
    • typeid - Тип договора, если у учебного заведения предусмотрено несколько разных типов договоров
    • num - Номер договора
    • numpass - Номер пропуска, студенческого билета и т.п.
    • date - Дата заключения
    • sellerid - Менеджер по работе с клиентами (приемная комиссия, партнер) - добавляет договор, меняет статус до "подписан клиентом", отслеживает статус договора и ход обучения (id по таблице persons)
    • clientid - Клиент, оплачивающий обучение (законный представитель, сам совершеннолетний ученик или куратор от организации, может принимать значение 0 или null, если клиент создается, а контракт имеет черновой вариант) (по таблице persons)
    • studentid - Ученик (может принимать значение 0, если ученик создается, а контракт имеет черновой вариант) (по таблице persons)
    • notes - Заметки
    • departmentcode - Подразделение в таблице departments, к которому приписан контракт на обучение (например, принявшее ученика)
    • contractform - Форма договора (шаблон)
    • organizationid - Юридическое лицо в таблице organizations, оплачивающее договор, если ученик платит за себя сам - то не указывается.
    • curatorid - Куратор или классный руководитель данного ученика (по таблице persons или не указан), отслеживает учебный процесс, держит связь с учеником, является посредником между учеником и системой, может быть внешней персоной.
    • enddate - Дата окончания договора
    • metacontractid - id метаконтракта, к которому привязан договор, в таблице metacontracts
    • cov - Дополнительный массив cov, содержащий дополнительные поля к объекту

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

  • (object) - объект со следующими полями
    • id - Внешний id объекта (переданный в запросе id)
    • dofid - Внутренний id объекта
    • modified - Дата модификации созданного или обновлённого объекта
    • hash - Хеш операции в storage/sync
    • errorcode - Код ошибки, если таковые возникли


Дополнительные методы

check_email($email)

Проверяет, можно ли использовать переданный e-mail в системе

Аргументы:

  • email(string) - электронная почта.

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

  • (bool) - true если ошибок не нашли,
  • (string) - или код ошибки: [SI2], [PI4]


check_hash($input)

Проверяет входящий запрос по sha1-хешу, сверяя наличие требуемых полей и выдаёт код ошибки при её наличии

Аргументы:

  • $input(object) - содержит поля запроса, а так же обязательные поля - id, requesttime, requestlogin, requesthash.

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

  • (bool) - true в случае успеха,
  • (string) - иначе - код ошибки: [PR0-PR4], [PI3]


get_key($requestlogin)

Получить ключ идентификатора системы, используя логин.

Аргументы:

  • $requestlogin(string) - идентификатор системы (логин)

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

  • (bool) - false, если ключ не найден,
  • (string) - ключ


get_response($type, $errorcode = 'OK')

Получить каркас объекта ответа для разных типов методов.

Аргументы:

  • $type(string) - тип запроса ('set', 'get', ...)
  • $errorcode(string) - код ошибки

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

  • (bool) - false, если произошла ошибка
  • (object) - объект для передачи ответа в SOAP-сообщениях


hash_object($input, $requestpassword)

Получить sha1-хеш пришедшего SOAP-запроса по описанному ранее алгоритму

Аргументы:

  • input(object) - SOAP-запрос с обязательными полями id, requesttime, requestlogin, requesthash, массивом cov.
  • requestpassword(string) - ключ идентификатора системы.

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

  • (bool) - false в случае ошибки
  • (string) - sha1-хеш


Коды ошибок

При успешном выполнении операции синхронизации возвращается код ошибки 'OK'. В ином случае, возвращается одна из следующих ошибок:

  • Ошибки параметров запроса [P]:
  • Обязательные [PR]
    • PR0 - Данные запроса пришли в некорректном формате
    • PR1 - Отсутствует идентификатор системы [requestlogin]
    • PR2 - Отсутствует время запроса [requesttime]
    • PR3 - Отсутствует контрольная сумма [requesthash]
    • PR4 - Отсутствует идентификатор объекта [id]
  • Некорректные [PI]
    • PI3 - Контрольная сумма запроса не совпадает
    • PI4 - Недопустимые символы в e-mail
    • PI5 - Тип переменной подразделения должен быть строковый
    • PI6 - Тип переменной cov должен быть массивом
    • PI7 - Поля внутри переменной cov не должны быть массивами или объектами
    • PI8 - Поля внутри переменной cov не должны совпадать с полями справочника (например, status, adddate)
  • Ошибки внутренние [S]:
  • Некорректные параметры [SI]
    • SI1 - Контрольная сумма запроса не совпадает
    • SI2 - Данный e-mail не допустим в системе
    • SI3 - Данный e-mail уже зарегистрирован в системе
    • SI4 - Название подразделения не может быть пустым
    • SI5 - Подразделения с таким кодом не существует
    • SI6 - Подразделение не актуально
    • SI7 - Код подразделения должен быть строкового типа
  • Ошибки кодирования [SC]
    • SC1 - Не зарегистрирована функция проверки параметров запроса для данного метода
    • SC2 - Не зарегистрирована функция исполнения запроса для данного метода
    • SC3 - Не верно передан формат проверки полей вложенного массива cov

Замечания, возможные проблемы

  • Не совпадает контрольная сумма, ошибка [PI3]
    • Необходимо обязательно проверять наличие всех полей, описанных в параметрах функций. Все типы параметров должны соответствовать описанным в wsdl-файле. К примеру, если в PHP попытаться передать массив в параметр, принимающий только строки, произойдёт конвертация массива в строку.
  • Ошибки при выполнении запроса, если не передан какой-либо параметр, либо передан лишний параметр
    • Желательно создавать класс (объект), в котором определены все поля и типы запроса, указанные в wsdl. От него создаётся экземпляр класса и поверх этих полей записываются значения. Таким образом, если поля не указаны, они автоматически должны заполняться значением null. Это позволит упростить процедуру хеширования и взаимодействия с сервером.