Разработка:sync/soap — различия между версиями
Konovalov (обсуждение | вклад) (→Коды ошибок) |
Konovalov (обсуждение | вклад) (→Коды ошибок) |
||
| (не показана 1 промежуточная версия этого же участника) | |||
| Строка 69: | Строка 69: | ||
Поэтому при проверке на сервере хэш не совпадёт. | Поэтому при проверке на сервере хэш не совпадёт. | ||
| − | =API= | + | =API (внешний) = |
==='''set_meta_contract($input)'''=== | ==='''set_meta_contract($input)'''=== | ||
| Строка 179: | Строка 179: | ||
| − | =Дополнительные методы= | + | =Дополнительные методы (внутренние)= |
===='''check_address($input)'''==== | ===='''check_address($input)'''==== | ||
| Строка 627: | Строка 627: | ||
** SP35 - Не найден студент, на которого заключён договор | ** SP35 - Не найден студент, на которого заключён договор | ||
** SP36 - Нельзя изменить студента, на которого заключён договор | ** SP36 - Нельзя изменить студента, на которого заключён договор | ||
| + | ** SP37 - Номер договора должен быть уникальным | ||
* Ошибки кодирования [SC] | * Ошибки кодирования [SC] | ||
** SC1 - Не зарегистрирована функция проверки параметров запроса для данного метода | ** SC1 - Не зарегистрирована функция проверки параметров запроса для данного метода | ||
Текущая версия на 13:14, 9 февраля 2015
| Плагин | |
| Название | soap |
| Тип | sync |
Содержание
- 1 Описание
- 2 API (внешний)
- 3 Дополнительные методы (внутренние)
- 3.1 check_address($input)
- 3.2 check_column_types_null($input, $table)
- 3.3 check_cov($cov, $fields = null)
- 3.4 check_department($code)
- 3.5 check_email($email)
- 3.6 check_fields_($input)
- 3.7 check_hash($input)
- 3.8 connect_sync($pcode, $provider, $substorage = null)
- 3.9 errorlog($input, $queryname=null)
- 3.10 execute_($input)
- 3.11 execute_additional_($input, $operation, $dofid = null)
- 3.12 execute_set_base($input, $method)
- 3.13 get_fields($input, $storage)
- 3.14 get_key($requestlogin)
- 3.15 get_response($type, $errorcode = 'OK')
- 3.16 get_storage_error($method, $storage)
- 3.17 get_sync_object($table, $provider, $id, $direct = 'down')
- 3.18 get_table($method)
- 3.19 hash_object($input, $requestpassword)
- 3.20 hash_uphash($input)
- 3.21 insert_address($input)
- 3.22 insert_object($input, $method, $table)
- 3.23 is_sync_object_exists($table, $provider, $id, $direct = 'down')
- 3.24 normalize_array($item)
- 3.25 set_method($input, $methodname)
- 3.26 set_status_route($table, $dofid, $departmentid)
- 3.27 update_address($input, $dofid)
- 3.28 update_cov($dofid, $inputcov, $plugincode)
- 3.29 update_object($input, $dofid, $method, $table)
- 4 Коды ошибок
- 5 Замечания, возможные проблемы
- 6 Расширение функционала
Описание
Веб-сервис для интеграции с другими системами по протоколу SOAP. Плагин использует инфраструктуру storages/sync для хранения соответствия внутренних и внешних id объектов и storages/synclog для логирования всех операций синхронизации.
Плагин объявляет SOAP-сервис, который располагается по адресам:
- /sync/soap/soap.php?do=wsdl - wsdl-файл
- /sync/soap/soap.php?do=service - сам сервис
У каждого метода присутствуют следующие обязательные служебные параметры:
- requesttime - (UNIX timestamp) время генерации запроса, используется для устаревания запроса с целью защиты от атаки на "повторение перехваченного запроса"
- requestlogin - идентифицирует систему-отправитель запроса (задается в sync/soap/cfg/clients.php, вместе с паролем requestpassword и необязательными параметрами)
- requesthash - sha1-хеш от всех полей запроса в алфавитном порядке, включая предыдущие два, а так же поля requestpassword (в самом запросе не участвует). Используется для подтверждения подлинности запроса.
Все параметры, в которых передаётся время, принимают UNIX timestamp, если в подписи к ним не написано иначе.
Имена полей 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 - время изменения объекта (UNIX timestamp)
- hash - контрольная сумма из storages/sync
- errorcode - код ошибки, помогающий идентифицировать проблему при исполнении запроса
Для проверки SOAP-запросов используется хеширование по следующему алгоритму:
- requesthash == sha1(requestpassword + requesttime + requestlogin + json(vars) + json(cvars)), где
- vars формируется следующим образом:
- Из полей объекта для SOAP-запроса исключаются служебные данные — requesthash, requestlogin, requesttime и дополнительный объект cov
- Поля сортируются в алфавитном порядке;
- cvars — вложенный объект cov, поля которого так же сортируются в алфавитном порядке;
- json() - функция для преобразования массива/объекта в json-строку.
- Знаком "+" указана конкатенация строк.
- vars формируется следующим образом:
Примечание: XML-структура SOAP-запроса для вложенных объектов, таких как cov, должна выглядеть следующим образом:
- <cov>
- <addfield>RU</addfield>
- <addfieldtwo>RU-MOS</addfieldtwo>
- <addfieldtthree>Москва</addfieldtthree>
- </cov>
При использовании ассоциативных массивов, например, на PHP, при попытке передать их SOAP-клиенту произойдёт искажение представления:
- <cov>
- <item>
- <key>addfield</key>
- <value>RU</value>
- </item>
- <item>
- <key>addfieldtwo</key>
- <value>RU-MOS</value>
- </item>
- <item>
- <key>addfieldthree</key>
- <value>Москва</value>
- </item>
- </cov>
Поэтому при проверке на сервере хэш не совпадёт.
API (внешний)
set_meta_contract($input)
Аргументы:
- input(object) - данные метаконтракта, переданные по SOAP. Содержит следующие поля
- requestlogin(string) - Идентификатор системы-отправителя запроса
- requesttime(int) - Время генерации запроса (UNIX timestamp)
- requesthash(string) - sha1-хеш
- id(int) - Внешний id метаконтракта
- num(string) - Номер метаконтракта
- departmentcode(string) - Код подразделения
- cov(object) - Дополнительный объект cov, содержащий дополнительные поля к объекту
Возвращаемые значения:
- (object) - объект со следующими полями
- id(int) - Внешний id объекта (переданный в запросе id)
- dofid(int) - Внутренний id объекта
- modified(int) - Дата модификации созданного или обновлённого объекта
- hash(string) - Хеш операции в storage/sync
- errorcode(string) - Код ошибки, если таковые возникли
set_person($input)
Аргументы:
- input(object) - данные персоны, переданные по SOAP. Содержит следующие поля
- requestlogin(string) - Идентификатор системы-отправителя запроса
- requesttime(int) - Время генерации запроса (UNIX timestamp)
- requesthash(string) - sha1-хеш
- id(int) - Внешний id метаконтракта
- firstname(string) - Имя
- middlename(string) - Отчество
- lastname(string) - Фамилия
- preferredname(string) - Префикс для имения (Mr. Dr. Г-н, Г-а)
- dateofbirth(int) - Дата рождения в UTS
- gender(string) - Пол (male, female, unknown)
- email(string) - Основной адрес электронной почты
- phonehome(string) - Домашний телефон
- phonework(string) - Рабочий телефон
- phonecell(string) - Сотовый телефон
- passtypeid(int) - Тип удостоверения личности (1 - свидетельство о рождении, 2 - паспорт гражданина РФ, 3 - загранпасспорт, 4 - разрешение на временное проживание лица без гражданства, 5 - вид на жительство, 6 - военный билет, 7 - водительсткое удостоверение пластиковое, 8 - вод. удостоверение форма 1, 9 - вод. удостоверение международное)
- passportserial(string) - Серия удостоверения личности (если предусмотрена типом документа)
- passportnum(string) - Номер удостоверения личности
- passportdate(int) - Дата выдачи удостоверения личности в UTS
- passportem(string) - Название организации, выдавшей удостоверение личности
- citizenship(string) - Гражданство
- departmentcode(string) - Основной отдел, к которому приписан человек (может редактировать его данные в persons)
- about(string) - Характеристика личности
- skype(string) - Уникальный идентификатор в Skype
- phoneadd1(string) - Дополнительный телефон 1
- phoneadd2(string) - Дополнительный телефон 2
- phoneadd3(string) - Дополнительный телефон 3
- emailadd1(string) - Дополнительная электронная почта 1
- emailadd2(string) - Дополнительная электронная почта 2
- emailadd3(string) - Дополнительная электронная почта 3
- passportaddr(object) - Адрес прописки по паспорту (для генерации документов)
- address(object) - Текущий адрес (почтовый адрес)
- birthaddress(object) - Адрес рождения персоны
- cov(object) - Дополнительный объект cov, содержащий дополнительные поля к объекту
Формат объектов: passportaddr, address, birthaddress
- postalcode(string) - Почтовый индекс
- country(string) - Код страны проживания (по предъявленному паспорту) в ICO 3166-1:1997 (RU)
- region(string) - Код региона по ISO 3166-2 (RU-NGR, RU-MOS)
- county(string) - Административный район
- city(string) - Город
- streetname(string) - Название улицы
- streettype(string) - Тип улицы
- number(string) - Номер дома
- gate(string) - Подъезд
- floor(string) - Этаж
- apartment(string) - Квартира
- latitude(float) - Широта в градусах
- longitude(float) - Долгота в градусах
Возвращаемые значения:
- (object) - объект со следующими полями
- id(int) - Внешний id объекта (переданный в запросе id)
- dofid(int) - Внутренний id объекта
- modified(int) - Дата модификации созданного или обновлённого объекта
- hash(string) - Хеш операции в storage/sync
- errorcode(string) - Код ошибки, если таковые возникли
set_contract($input)
Аргументы:
- input(object) - данные договора, переданные по SOAP. Содержит следующие поля
- requestlogin(string) - Идентификатор системы-отправителя запроса
- requesttime(int) - Время генерации запроса (UNIX timestamp)
- requesthash(string) - sha1-хеш
- id(int) - Внешний id договора
- typeid(int) - Тип договора, если у учебного заведения предусмотрено несколько разных типов договоров
- num(string) - Номер договора
- numpass(string) - Номер пропуска, студенческого билета и т.п.
- date(int) - Дата заключения
- sellerid(int) - Менеджер по работе с клиентами (приемная комиссия, партнер) - добавляет договор, меняет статус до "подписан клиентом", отслеживает статус договора и ход обучения (id по таблице persons)
- clientid(int) - Клиент, оплачивающий обучение (законный представитель, сам совершеннолетний ученик или куратор от организации, может принимать значение 0 или null, если клиент создается, а контракт имеет черновой вариант) (по таблице persons)
- studentid(int) - Ученик (может принимать значение 0, если ученик создается, а контракт имеет черновой вариант) (по таблице persons)
- notes(string) - Заметки
- departmentcode(string) - Подразделение в таблице departments, к которому приписан контракт на обучение (например, принявшее ученика)
- contractform(string) - Форма договора (шаблон)
- curatorid(int) - Куратор или классный руководитель данного ученика (по таблице persons или не указан), отслеживает учебный процесс, держит связь с учеником, является посредником между учеником и системой, может быть внешней персоной.
- enddate(int) - Дата окончания договора
- metacontractid(int) - id метаконтракта, к которому привязан договор, в таблице metacontracts
- cov(object) - Дополнительный объект cov, содержащий дополнительные поля к объекту
Возвращаемые значения:
- (object) - объект со следующими полями
- id(int) - Внешний id объекта (переданный в запросе id)
- dofid(int) - Внутренний id объекта
- modified(int) - Дата модификации созданного или обновлённого объекта
- hash(string) - Хеш операции в storage/sync
- errorcode(string) - Код ошибки, если таковые возникли
Дополнительные методы (внутренние)
check_address($input)
Проверить поля адреса
Аргументы:
- input(object) - объект с полями справочника addresses
Возвращаемые значения:
- (bool) - true если ошибок не нашли,
- (string) - или код ошибки: [SP19, SP21-SP23]
check_column_types_null($input, $table)
Проверить поля запроса на предмет ненулевых значений и корректности типов справочника
Аргументы:
- input(object) - объект SOAP-запроса
- table(string) - название справочника,
Возвращаемые значения:
- (bool) - true если ошибок не нашли,
- (string) - или код ошибки: [SC6-SC7], [PR5-PR6]
check_cov($cov, $fields = null)
Проверить дополнительный объект на предмет соответствия формату
Аргументы:
- cov(array) - дополнительный вложенный объект.
- fields(object) - поля объекта для проверки дублирующихся полей.
Возвращаемые значения:
- (bool) - true если ошибок не нашли,
- (string) - или код ошибки: [PI6-PI8], [SC3]
check_department($code)
Проверить, существует ли такое подразделение и актуальный ли у него статус
Аргументы:
- code(string) - код подразделения.
Возвращаемые значения:
- (bool) - true если ошибок не нашли,
- (string) - или код ошибки: [SP5-SP7]
check_email($email)
Проверяет, можно ли использовать переданный e-mail в системе
Аргументы:
- email(string) - электронная почта.
Возвращаемые значения:
- (bool) - true если ошибок не нашли,
- (string) - или код ошибки: [SP2], [PI4]
check_fields_($input)
Методы с таким префиксом проверяют объект SOAP-запроса на предмет некорректных значений полей
Аргументы: см. метод set_method()
- input(object) - содержит поля запроса
Возвращаемые значения:
- (bool) - true если ошибок не нашли,
- (string) - или код ошибки
check_hash($input)
Проверяет входящий запрос по sha1-хешу, сверяя наличие требуемых полей и выдаёт код ошибки при её наличии
Аргументы:
- input(object) - содержит поля запроса, а так же обязательные поля - id, requesttime, requestlogin, requesthash.
Возвращаемые значения:
- (bool) - true в случае успеха,
- (string) - иначе - код ошибки: [PR0-PR4], [PI3]
connect_sync($pcode, $provider, $substorage = null)
Создать соединение с объектом синхронизации по названию справочника и поставщику данных
Аргументы:
- pcode(string) - название плагина для синхронизации (metacontracts, persons, ...)
- provider(string) - название поставщика синхронизации
- substorage(string) - код внутреннего субсправочника
Возвращаемые значения:
- (bool) - false в случае ошибки, или
- (object) - объект подключения к синхронизации dof_storage_sync_connect
errorlog($input, $queryname=null)
Записывает переданный объект в файл ('/dat/errorlog.txt') для последующей отладки
Аргументы:
- input(mixed) - переменная для вывода в файл
- queryname(string) - название запроса (какя именно операция выполняется)
Возвращаемые значения:
- (void)
execute_($input)
Методы с таким префиксом исполняют действия, сопутствующие SOAP-запросу
Аргументы: см. метод set_method()
- input(object) - запрос, должен содержать поля справочника
Возвращаемые значения:
- (bool) - true если ошибок не нашли,
- (string) - или код ошибки
execute_additional_($input, $operation, $dofid = null)
Методы с таким префиксом исполняют дополнительные действия в SOAP-запросе
Аргументы: см. метод insert_object()
- input(object) - запрос, должен содержать поля справочника
- operation(string) - название операции: 'insert', 'update', ...
- dofid(int) - id объекта из справочника (если не null, то операция 'update', иначе - 'insert')
Возвращаемые значения:
- (bool) - операция прошла успешно
- (object) - возвращает дополнительные поля, которые надо присоединить к объекту в методе insert_object()
- (string) - или код ошибки
execute_set_base($input, $method)
Выполнить базовые действия метода set_:
- 1) Получить объект синхронизации
- 2) Получить объект для ответа
- 3) Просчитать хеш объекта (без служебных полей)
- 4) Есть ли объект синхронизации с таким id в базе?
- 4.1) Объект найден. Проверить, нужно ли производить синхронизацию
- 4.1.1) Синхронизация нужна
- 4.1.1.1) Обновить объект в базе (update_object()), объект синхронизации и сгенерировать ответ 'OK'
- 4.1.1.2) Логирование
- 4.1.1.3) Cгенерировать ответ 'OK', синхронизация успешна
- 4.1.2) Синхронизация не нужна, сгенерировать ответ 'ОК'
- 4.2) Объект не найден.
- 4.2.1) Добавить объект в базу (insert_object()), обрабатывая ошибки, объект синхронизации
- 4.2.2) Логирование
- 4.2.3) Cгенерировать ответ 'OK', синхронизация успешна
- 5) Вернуть ответ
Аргументы: см. метод insert_object() и update_object()
- input(object) - объект SOAP-запроса
- method(string) - метод API, который необходимо выполнить
Возвращаемые значения:
- (object) - объект $response (см. метод set_meta_contract())
- (string) - или код ошибки
get_fields($input, $storage)
Получить поля для вставки или обновления таблицы
Аргументы:
- input(object) - объект с определёнными полями одного из справочника
- storage(string) - название справочника: 'contracts', 'persons', ...
Возвращаемые значения:
- (bool) - false, в случае ошибки
- (object) - объект с полями для вставки/обновления записи в таблице
get_key($requestlogin)
Получить ключ идентификатора системы, используя логин.
Аргументы:
- requestlogin(string) - идентификатор системы (логин)
Возвращаемые значения:
- (bool) - false, если ключ не найден,
- (string) - ключ
get_response($type, $errorcode = 'OK')
Получить каркас объекта ответа для разных типов методов.
Аргументы:
- type(string) - тип запроса ('set', 'get', ...)
- errorcode(string) - код ошибки
Возвращаемые значения:
- (bool) - false, если произошла ошибка
- (object) - объект для передачи ответа в SOAP-сообщениях
get_storage_error($method, $storage)
Получить код ошибки справочника по названию метода и таблицы
Аргументы:
- method(string) - название операции со справочником: 'insert', 'update', ...
- storage(string) - название справочника: 'contracts', 'persons', ...
Возвращаемые значения:
- (bool) - false, если такого сочетания "метод-справочник" не найдено
- (string) - код ошибки
get_sync_object($table, $provider, $id, $direct = 'down')
Проверить, существует ли объект синхронизации в справочнике storage/sync
Аргументы:
- table(string) - справочник, по которому необходимо получить объект
- provider(string) - внешний провайдер (поле storage/sync.upsubsubstorage)
- id - id из таблицы storage/sync
- direct - направление синхронизации
Возвращаемые значения:
- (bool) - false, если объект не найден
- (string) - код ошибки
- (object) - объект table с записью
get_table($method)
Получить название таблицы (справочника), с которым работает переданный метод
Аргументы:
- method(string) - название метода
Возвращаемые значения:
- (bool) - false, если такого метода не найдено
- (string) - название справочника
hash_object($input, $requestpassword)
Получить sha1-хеш пришедшего SOAP-запроса по описанному ранее алгоритму
Аргументы:
- input(object) - SOAP-запрос с обязательными полями id, requesttime, requestlogin, requesthash, объектом cov.
- requestpassword(string) - ключ идентификатора системы.
Возвращаемые значения:
- (bool) - false в случае ошибки
- (string) - sha1-хеш
hash_uphash($input)
Выполнить хеширование объекта для сравнения с uphash в storage/sync
Аргументы:
- input(object) - SOAP-запрос с полями справочника, без специальных полей request*
Возвращаемые значения:
- (bool) - false в случае ошибки
- (string) - sha1-хеш
insert_address($input)
Добавить новый адрес
Аргументы:
- input(object) - объект с полями справочника
Возвращаемые значения:
- (int) - id добавленного объекта
- (string) - код ошибки
insert_object($input, $method, $table)
Добавить объект в базу:
- Получить из запроса поля для вставки в таблицу: get_fields()
- Выполнить дополнительные действия: execute_additional_(), в случае ошибок сгенерировать ответ
- Вставить объект в базу, обработать ошибки
- Обработать объект cov: update_cov(), добавить поля в базу, обработать ошибки
- В соответствии с настройками выставить статус через set_status_route(), ошибки только логировать
Аргументы:
- input(object) - объект с полями справочника и другими дополнительными полями
- method(string) - метод API, который необходимо выполнить
- table(string) - название справочника: 'contracts', 'persons', ...
Возвращаемые значения:
- (int) - id добавленного объекта
- (string) - код ошибки
is_sync_object_exists($table, $provider, $id, $direct = 'down')
Проверить, существует ли объект синхронизации в справочнике storage/sync
Аргументы:
- table(string) - название справочника
- provider(string) - название клиента, с которым выполняется синхронизация
- id(int) - id объекта, в зависимости от направления синхронизации
- direct(string) - направление синхронизации ('up', 'down')
Возвращаемые значения:
- (bool) - результат операции
- (string) - или код ошибки
normalize_array($item)
Нормализует ошибочно переданный ассоциативный массив в объект
Аргументы:
- item(object) - объект с вложенным массивом item[], в котором находятся объекты:
- item[0] = stdClass(),
- item[0]->key,
- item[0]->value,
Возвращаемые значения:
- (object) - объект, в котором поля {item[0]->key}, а значения: {item[0]->value}
set_method($input, $methodname)
Выполняет базовую проверку переданных параметров (контрольная сумма), проверяет, реализованы ли функции для проверки входных параметров и исполнения запроса, вызывает 'set' метод для переданного в качестве аргумента объекта запроса и метода. В случае возникновения ошибок составляет ответный запрос и выполняет логирование. Вызывает следующие методы:
Аргументы:
- input(object) - объект SOAP-запроса (должны присутствовать служебные поля request*)
- methodname(string) - название функции, которую необходимо исполнить
Возвращаемые значения:
- (object) - объект содерщаший поля:
- id - переданный в запросе id объекта
- dofid - внутренний id объекта
- modified - время изменения объекта
- hash - контрольная сумма из storages/sync
- errorcode - код ошибки
set_status_route($table, $dofid, $departmentid)
Установить статус согласно маршруту, заданному в конфиге
Аргументы:
- table(string) - название справочника: 'contracts', 'persons', ...
- dofid(int) - внутренний id объекта из таблицы $storage
- departmentid(int) - id из таблицы departments
Возвращаемые значения:
- (int) - id добавленного объекта
- (array) - код ошибки и описание: array('код_ошибки', 'описание ошибки')
update_address($input, $dofid)
Обновить адрес
Аргументы:
- input(object) - объект с полями справочника и другими дополнительными полями
- dofid(int) - внутренний id объекта в таблице addresses
Возвращаемые значения:
- (bool) - результат обновления
- (string) - код ошибки
update_cov($dofid, $inputcov, $plugincode)
Обновить вложенный объект cov для внутренних объектов
Аргументы:
- dofid(int) - внутренний id объекта в таблице $plugincode
- inputcov(object) - объект, по которому происходит перебор
- plugincode(string) - код плагина storage
Возвращаемые значения:
- (bool) - результат обновления
- (string) - код ошибки
update_object($input, $dofid, $method, $table)
Обновить объект в базе:
- Получить из запроса поля для вставки в таблицу: get_fields()
- Выполнить дополнительные действия: execute_additional_(), в случае ошибок сгенерировать ответ
- Обновить объект в базе, обработать ошибки
- Обработать объект cov: update_cov(), добавить поля в базу, обработать ошибки
Аргументы:
- input(object) - объект с полями справочника и другими дополнительными полями
- dofid(int) - внутренний id объекта в таблице $plugincode
- method(string) - метод API, который необходимо выполнить
- table(string) - название справочника: 'contracts', 'persons', ...
Возвращаемые значения:
- (int) - id добавленного объекта
- (string) - код ошибки
Коды ошибок
При успешном выполнении операции синхронизации возвращается код ошибки 'OK'. В ином случае, возвращается одна из следующих ошибок:
- Ошибки параметров запроса [P]:
- Обязательные [PR]
- PR0 - Данные запроса пришли в некорректном формате
- PR1 - Отсутствует идентификатор системы [requestlogin]
- PR2 - Отсутствует время запроса [requesttime]
- PR3 - Отсутствует контрольная сумма [requesthash]
- PR4 - Отсутствует идентификатор объекта [id]
- PR5 - Отсутствует значение в ненулевом поле
- PR6 - Некорректный тип переданного поля
- Некорректные [PI]
- PI3 - Контрольная сумма запроса не совпадает
- PI4 - Недопустимые символы в e-mail
- PI5 - Тип переменной подразделения должен быть строковый
- PI6 - Тип переменной cov должен быть массивом
- PI7 - Поля внутри переменной cov не должны быть массивами или объектами
- PI8 - Поля внутри переменной cov не должны совпадать с полями справочника (например, status, adddate)
- Ошибки внутренние [S]:
- Некорректные параметры [SP]
- SP1 - Контрольная сумма запроса не совпадает
- SP2 - Данный e-mail не допустим в системе
- SP3 - Данный e-mail уже зарегистрирован в системе
- SP4 - Название мета-контракта не может быть пустым
- SP5 - Подразделения с таким кодом не существует
- SP6 - Подразделение не актуально
- SP7 - Код подразделения должен быть строкового типа
- SP8 - Неверно передан параметр с запросом
- SP9 - Код подразделения не передан, и значения по-умолчанию не найдено
- persons
- SP9 - Имя не может быть пустым
- SP10 - Фамилия не может быть пустой
- SP11 - E-Mail не может быть пустым
- SP12 - Укажите дату рождения персоны
- SP13 - Укажите пол
- SP14 - Укажите корректный пол: Мужской (male) или Женский" (female)
- SP15 - Укажите правильный тип удостоверения личности
- SP16 - Укажите серию паспорта
- SP17 - Укажите номер паспорта
- SP18 - Укажите место выдачи паспорта
- SP19 - Укажите тип улицы
- SP20 - Логин Skype содержит недопустимые символы
- SP21 - В адресе некорректно указана страна
- SP22 - В адресе некорректно указан регион
- SP22 - Нельзя указать регион без страны
- SP23 - Предыдущее поле старого ФИО не заполнено
- contracts
- SP24 - Укажите ученика
- SP25 - Укажите законного представителя
- SP26 - Укажите менеджера по работе с клиентами
- SP27 - Укажите дату заключения договора
- SP28 - Переданный id персоны в поле [Ученик] не найден в базе
- SP29 - Переданный id персоны в поле [Законный представитель] не найден в базе
- SP30 - Переданный id персоны в поле [Менеджер] не найден в базе
- SP31 - Переданный id персоны в поле [Куратор] не найден в базе
- SP32 - Менеджер по-умолчанию не найден
- SP33 - Метаконтракт не найден
- SP34 - Дата заключения договора не в корректном формате
- SP35 - Не найден студент, на которого заключён договор
- SP36 - Нельзя изменить студента, на которого заключён договор
- SP37 - Номер договора должен быть уникальным
- Ошибки кодирования [SC]
- SC1 - Не зарегистрирована функция проверки параметров запроса для данного метода
- SC2 - Не зарегистрирована функция исполнения запроса для данного метода
- SC3 - Не верно передан формат проверки полей вложенного массива cov
- SC4 - Для этого метода не задана таблица, с которой он работает
- SC5 - Неверно указано название операции
- SC6 - Такого справочника не существует
- SC7 - Неизвестный тип переменной
- SC8 - Не удалось получить поля для добавления/обновления объекта в базе
- SC9 - Некорректные параметры в функции проверки объекта синхронизации справочника
- Ошибки целостности структуры (базы) [SI]
- SI1 - Не удалось добавить запись в справочник metacontracts
- SI2 - Не удалось обновить запись в справочнике metacontracts
- SI3 - Не удалось добавить запись в справочник persons
- SI4 - Не удалось обновить запись в справочнике persons
- SI5 - Не удалось добавить запись в справочник contracts
- SI6 - Не удалось обновить запись в справочнике contracts
- SI7 - Не удалось обновить запись в справочнике cov
- SI8 - Не удалось обновить запись в справочнике addresses
- SI9 - Не удалось найти запись в справочнике addresses для обновления
- SI10 - Не удалось найти запись в справочнике persons
- Ошибки рабочих процессов (при смене статусов, исполнении приказов, ...) (workflow) [SW]
- SW1 - Не удалось изменить статус на $a
- SW2 - Статуса с таким именем [$a] не обнаружено
Замечания, возможные проблемы
- Не совпадает контрольная сумма, ошибка [PI3]
- Необходимо обязательно проверять наличие всех полей, описанных в параметрах функций. Все типы параметров должны соответствовать описанным в wsdl-файле. К примеру, если в PHP попытаться передать массив в параметр, принимающий только строки, произойдёт конвертация массива в строку.
- Ошибки при выполнении запроса, если не передан какой-либо параметр, либо передан лишний параметр
- Желательно создавать класс (объект), в котором определены все поля и типы запроса, указанные в wsdl. От него создаётся экземпляр класса и поверх этих полей записываются значения. Таким образом, если поля не указаны, они автоматически должны заполняться значением null. Это позволит упростить процедуру хеширования и взаимодействия с сервером.
Расширение функционала
- Методы set
- Рассмотрим на примере создания метода set_department(). Необходимо выполнить следующие действия:
- 1) Добавить в blocks_dof_sync_soap_soapserver:
- * set_department() - в нём один единственный вызов: return $this->dof->sync('soap')->set_method($input, __FUNCTION__);
- * Задокументировать входные параметры, @return object для всех методов set_ пока одинаков
- 2) Добавить в dof_sync_soap:
- * check_fields_set_department($input) - проверки входных параметров, проверка возможности добавить объект в базу без ошибок
- * execute_set_department($input) - основное тело исполнения запроса. Основные действия выполняются в функции execute_set_base(), поэтому рекомендуется использовать вызов: return $this->execute_set_base($input, 'set_department');
- Если нужна более расширенная логика, метод можно написать самому (но желательно отталкиваться от общего алгоритма в execute_set_base().
- * execute_additional_set_department($input, $operation, $dofif) - метод, который выполняется при вызове insert_object()
- * При необходимости добавить смену статусов
