Учебное пособие по веб-сервису Simply CRM

Просто предоставляет простой, мощный и безопасный интерфейс прикладного программирования (API) для работы с сущностями, хранящимися внутри. Чтобы использовать этот документ, вы должны иметь базовые знания о разработке программного обеспечения, веб-сервисах и Simply CRM .

Веб-служба предоставляет более простой способ простой интеграции с другими вашими программными системами.

Характеристики вызова API

REST — API основан на REST, что означает, что вся связь между клиентом и сервером может происходить через HTTP в форме запросов GET или POST.

JSON — JSON используется для кодирования ответа и запроса.

Запросы и ответы — ваше клиентское приложение подготавливает и отправляет сервисный запрос в API. API обрабатывает запрос и возвращает ответ, а затем клиентское приложение обрабатывает ответ.

Фиксируется автоматически — каждая операция, которая записывает в объект Simply, фиксируется автоматически. Это аналогично настройке AUTOCOMMIT в SQL.

Ответ API

Объект ответа

Все ответы будут иметь один из следующих двух форматов.

Если запрос обработан успешно:

 <code> Response { 
успех: Boolean = true
result: Object // Объект результата операции
}
</code>

Если при обработке запроса произошел сбой:

 <code> Reponse { 
успех: Boolean = false
ошибка: ErrorObject
}
</code>

Объект ошибки

 <code> ErrorObject { 
errorCode: String // Строковое представление типа ошибки
errorMessage: String // Сообщение об ошибке из api.
}
</code>

errorCode — это строковое представление типа ошибки.

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

Ответ на любой запрос веб-службы — это объект JSON. У объекта есть поле success, которое будет иметь значение true, если операция прошла успешно, и false в противном случае. Если успех равен false, объект ответа будет содержать ошибку поля, которая будет содержать объект JSON. Объект ошибки будет содержать два поля errorType, однословное описание ошибки, и errorMsg, строку, содержащую описание ошибки.

Код примера написан на Php и имеет две зависимости: библиотеку Zend JSON и Http_Client.

Требования к запуску примеров, приведенные в руководстве

  1. Установка Simply с веб-службой;
  2. Php для запуска примера кода;
  3. HTTP_Client, который можно установить, выполнив pear install HTTP_Client ;
  4. Zend JSON, для которого вам нужно будет загрузить минимальный фреймворк zend .

Происходит вход в систему

API не использует пароль для входа в систему. Вместо этого просто предоставляет уникальный ключ доступа для каждого пользователя. Чтобы получить ключ пользователя, перейдите на панель «Мои настройки» конкретного пользователя. Там вы найдете поле Access Key.

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

Вход в систему — это двухэтапный процесс. На первом этапе клиент получает от сервера токен вызова, который используется вместе с ключом доступа пользователя для входа в систему.

GetChallenge

Получите жетон вызова с сервера. Это должен быть запрос GET.

Формат URL

 <code> Тип запроса: GET 

http: //Simply_url/webservice.php? operation = getchallenge

& username = [имя пользователя]
</code>

Пример GetChallenge

Чтобы получить токен вызова, вам необходимо выполнить следующий код.

 <code> // например // путь URL к Simply / webservice.php, например http: //Simply_url/webservice.php 
$ endpointUrl = "http: //localhost/ws/webservice.php";
// имя пользователя, который должен войти в систему.
$ userName = "админ";

$ httpc = новый HTTP_CLIENT ();
// Запрос getchallenge должен быть запросом GET.
$ httpc-> get ("$ endpointUrl? operation = getchallenge & username = $ userName"); $ response = $ httpc-> currentResponse ();
// декодируем ответ json-кодирования от сервера.
$ jsonResponse = Zend_JSON :: decode ($ response ['body']);

// проверяем, была ли запрошенная операция успешной или нет.
если ($ jsonResponse ['успех'] == false)
// обрабатываем случай сбоя.
die ('getchallenge failed:'. $ jsonResponse ['error'] ['errorMsg']);

// операция прошла успешно получить токен из ответа. $ challengeToken = $ jsonResponse ['результат'] ['токен'];
</code>

Результат GetChallenge

Объект, представляющий результат ответа операции getchallenge.

 <code> GetChallengeResult { 
token: String // Жетон вызова с сервера.
serverTime: TimeStamp // Текущее время сервера.
expireTime: TimeStamp // Время истечения срока действия токена.
}
</code>

Теперь, когда у вас есть жетон испытания, вы можете войти в систему. Поле ключа доступа в операции входа в систему — это контрольная сумма md5 конкатенации маркера вызова и собственного ключа доступа пользователя. Операция входа в систему, в отличие от getchallenge, представляет собой почтовый запрос.

Авторизоваться

Войдите на сервер, используя токен вызова, полученный в операции getchallenge.

Формат URL

 <code> Тип запроса: POST 
http: //Simply_url/webservice.php? operation = войти

& username = [имя пользователя]
& accessKey = [accessKey]
</code>

Для accessKey создайте строку md5 после объединения ключа доступа пользователя со страницы «Мои предпочтения» и токена запроса, полученного из результата getchallenge.

Пример входа

 <code> // например 
// ключ доступа администратора пользователя, который находится на моей странице настроек.
$ userAccessKey = 'dsf923rksdf3';

// создаем строку md5, объединяющую пользовательский ключ доступа со страницы моих предпочтений
// и токен вызова, полученный в результате получения результата.
$ createdKey = md5 ($ challengeToken. $ userAccessKey);
// запрос входа должен быть запросом POST.
$ httpc-> post ("$ endpointUrl",
array ('operation' => 'login', 'username' => $ userName,
'accessKey' => $ generatedKey), true);
$ response = $ httpc-> currentResponse ();
// декодируем ответ json-кодирования от сервера.
$ jsonResponse = Zend_JSON :: decode ($ response ['body']);

// операция прошла успешно получить токен из ответа.
если ($ jsonResponse ['успех'] == false)
// обрабатываем случай сбоя.
die ('ошибка входа:'. $ jsonResponse ['error'] ['errorMsg']);

// Успешный вход в систему извлечь sessionId и userId из LoginResult, чтобы его можно было использовать для дальнейших вызовов.
$ sessionId = $ jsonResponse ['результат'] ['имя_сеанса'];
$ userId = $ jsonResponse ['результат'] ['userId'];

</code>

Идентификатор сеанса используется для идентификации текущего сеанса и будет общим параметром во всех последующих запросах.

Результат входа

Объект, представляющий результат ответа операции входа в систему.

Получение информации

API предоставляет две операции для получения информации о доступных объектах Simply.

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

Типы списков

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

Формат URL

 <code> Тип запроса: GET 

http: //Simply_url/webservice.php? operation = listtypes

& sessionName = [идентификатор сеанса]
</code>

Возвращает карту, содержащую ключевые «типы» со значением, являющимся списком имен объектов Simply.

Пример типов списков

 <code> // запрос типа списка должен быть запросом GET. 
$ httpc-> get ("$ endpointUrl? sessionName = $ sessionId & operation = listtypes");
$ response = $ httpc-> currentResponse ();
// декодируем ответ json-кодирования от сервера.
$ jsonResponse = Zend_JSON :: decode ($ response ['body']);

// операция прошла успешно получить токен из ответа.
если ($ jsonResponse ['успех'] == false)
// обрабатываем случай сбоя.
die ('не удалось создать список типов:'. $ jsonResponse ['error'] ['errorMsg']);
// Получить список всех доступных модулей.
$ modules = $ jsonResponse ['результат'] ['типы'];
</code>

Вторая операция — это описание, которое предоставляет подробную информацию о типе объекта Simply.

Опишите

Получить информацию о типе данного объекта Simply.

Формат URL

 <code> Тип запроса: GET 

http: //Simply_url/webservice.php? operation = описать

& sessionName = [идентификатор сеанса]
& elementType = [elementType]
</code>

Опишите пример

 <code> // например 
// Просто имя объекта, который необходимо описать или информация о котором запрашивается.
$ moduleName = 'Контакты';

// использовать sessionId, созданный во время входа в систему.
$ params = "sessionName = $ sessionId & operation = описать & elementType = $ moduleName";
// запрос описания должен быть запросом GET.
$ httpc-> get ("$ endpointUrl? $ params");
$ response = $ httpc-> currentResponse ();
// декодируем ответ json-кодирования от сервера.
$ jsonResponse = Zend_JSON :: decode ($ response ['body']);

// операция прошла успешно получить токен из ответа.
если ($ jsonResponse ['успех'] == false)
// обрабатываем случай сбоя.
die ('описать объект не удалось:'. $ jsonResponse ['error'] ['errorMsg']);
// получить описание объекта результата. $ description = $ jsonResponse ['результат'];

</code>

Описание состоит из следующих полей:

название Описание
метка Метка, используемая для имени модуля.
название Имя модуля.
Создаваемый Логическое значение, определяющее, можно ли создать объект.
Обновляемый Логическое значение, определяющее, можно ли обновить объект.
Удаляемый Логическое значение, определяющее, можно ли удалить объект.
Извлекаемый Логическое значение, определяющее, можно ли получить объект.
Поля Массив, содержащий имена полей и информацию об их типе.

Каждый элемент в массиве fields описывает конкретное поле в объекте.

Поле типа особенно важно, поскольку оно описывает, какой тип поля. Это карта, которая будет содержать по крайней мере один элемент с именем name, который определяет имя типа.

название Описание
Строка Однострочное текстовое поле.
Текст Многострочное текстовое поле.
Целое число Многострочное текстовое поле.
Двойной Поле для чисел с плавающей запятой.
Булево Логическое поле, которое может принимать значения true или false.
Время Строка в формате чч: мм, основанная на настройках формата времени пользователя.
Дата Строка, представляющая дату, карта типов будет содержать другой элемент, называемый форматом, который является форматом, в котором ожидается значение этого поля, на основе формата даты в настройках пользователя.
Дата и время Строка, представляющая дату и время, которая основана на настройках формата даты пользователя.
Автогенерируемая Поля, значения для которых автоматически генерируются программой Simply. Обычно это поле идентификатора объекта.
Ссылка Поле, показывающее отношение к другому объекту. Карта типов будет содержать еще один элемент с именем referTo, который представляет собой массив, содержащий модули, на которые может указывать поле.
Список выбора Поле, которое может содержать одно из списка значений. Карта будет содержать два элемента: picklistValues, который представляет собой список возможных значений, и defaultValue, который является значением по умолчанию для раскрывающегося списка.
Мультипиклист Поле раскрывающегося списка, в котором можно выбрать несколько значений.
Телефон Поле, используемое для хранения телефонных номеров.
Эл. адрес Поле, используемое для хранения идентификаторов электронной почты.
URL Поле, используемое для хранения URL-адресов.
Skype Поле, используемое для хранения идентификаторов Skype или номеров телефонов.
пароль Поле, используемое для хранения паролей.
Владелец Поле, определяющее владельца поля, которым может быть группа или отдельный пользователь.

Опишите результат

 <code> DescribeResult { 
label: String // метка модуля.
name: String // имя модуля, как указано в запросе.
createable: Boolean // true, если вошедшему в систему пользователю разрешено создавать записи типа, и false в противном случае.
updateable: Boolean // true, если вошедшему в систему пользователю разрешено обновлять записи типа, и false в противном случае.
deleteable: Boolean // true, если вошедшему в систему пользователю разрешено удалять записи типа и false в противном случае.
retrieveable: Boolean // true, если вошедшему в систему пользователю разрешены извлекаемые записи типа, и false в противном случае.
fields: Array // массив типа Field.
}
</code>

Поле

 <code> Поле { 

<pre class = "_ fck_mw_lspace"> name: String // имя поля.


label: String // метка поля.
обязательный: Boolean // true, если необходимо предоставить значение при выполнении запроса на создание, и false в противном случае.
type: FieldType // экземпляр FieldType.
default: anyType // значение по умолчанию для поля.
nillable: Boolean // true, если null может предоставить значение для поля, и false в противном случае.
editable: Boolean // true, если поле может содержать значение во время операции создания или обновления.
}
</code>

FieldType

Error 400 (Bad Request)!!1

400. That’s an error.

Your client has issued a malformed or illegal request. That’s all we know.

Пример 3

Создайте контакт и свяжите его с новой учетной записью.

 <code> // например 3 
<p> // Создаем контакт и связываемся с новой учетной записью.
</p> <p> // заполняем детали Аккаунтов. userId получается из loginResult.
$ accountData = array ('accountname' => 'Просто', 'assign_user_id' => $ userId);
// кодируем объект в формате JSON для связи с сервером.
$ objectJson = Zend_JSON :: encode ($ accountData);
// имя модуля, для которого должна быть создана запись.
$ moduleName = 'Аккаунты';
</p> <p> // sessionId получается из loginResult.
$ params = array ("sessionName" => $ sessionId, "operation" => 'create',
</p>
<pre class = "_ fck_mw_lspace"> "element" => $ objectJson, "elementType" => $ moduleName);

// Создание должно быть POST-запросом. $ httpc-> post («$ endpointUrl», $ params, true); $ response = $ httpc-> currentResponse (); // декодируем ответ json-кодирования от сервера. $ jsonResponse = Zend_JSON :: decode ($ response ['body']);

// операция прошла успешно получить токен из ответа.
если ($ jsonResponse ['успех'] == false)

// обрабатываем случай сбоя.
die ('ошибка создания:'. $ jsonResponse ['error'] ['errorMsg']);

$ account = $ jsonResponse ['результат']; $ accountId = $ account ['id'];

$ contactData = array ('lastname' => 'Valiant', 'assign_user_id' => $ userId, 'account_id' => $ accountId);

// кодируем объект в формате JSON для связи с сервером. $ objectJson = Zend_JSON :: encode ($ contactData); // имя модуля, для которого должна быть создана запись. $ moduleName = 'Контакты';

// sessionId получается из loginResult.
$ params = array («sessionName» => $ sessionId, «operation» => 'create',

"element" => $ objectJson, "elementType" => $ moduleName);

// Создание должно быть POST-запросом. $ httpc-> post («$ endpointUrl», $ params, true); $ response = $ httpc-> currentResponse (); // декодируем ответ json-кодирования от сервера. $ jsonResponse = Zend_JSON :: decode ($ response ['body']);

// операция прошла успешно получить токен из ответа.
если ($ jsonResponse ['успех'] == false)

// обрабатываем случай сбоя.
die ('ошибка создания:'. $ jsonResponse ['error'] ['errorMsg']);
$ savedObject = $ jsonResponse ['результат']; $ id = $ savedObject ['идентификатор'];

</code> </pre>

CreateResult

Карта, представляющая содержимое объекта на основе сущности CRM. Все справочные поля представлены с использованием типа ID . Ключ ID типа Id представляет уникальный ID объекта. Это поле присутствует для любого объекта, полученного из базы данных.

Получить

Получить существующую запись с сервера.

Формат URL

 <code> Тип запроса: GET 

http: //Simply_url/webservice.php? operation = получить
& session_name = [идентификатор сеанса]
& id = [идентификатор объекта

</code>

Получить пример

Чтобы получить объект по его идентификатору, используйте операцию получения. Вы можете получить контакт, созданный в примере создания.

 <code> // sessionId получается из loginResult. 
$ params = "sessionName = $ sessionId & operation = получить & id = $ id";
// Получение должно быть запросом GET.
$ httpc-> get ("$ endpointUrl? $ params");
$ response = $ httpc-> currentResponse ();
// декодируем ответ json-кодирования от сервера.
$ jsonResponse = Zend_JSON :: decode ($ response ['body']);
// операция прошла успешно получить токен из ответа.

если ($ jsonResponse ['успех'] == false)
// обрабатываем случай сбоя.
die ('ошибка извлечения:'. $ jsonResponse ['ошибка'] ['errorMsg']);

$ retrievedObject = $ jsonResponse ['результат'];
</code>

RetrieveResult

Error 400 (Bad Request)!!1

400. That’s an error.

Your client has issued a malformed or illegal request. That’s all we know.

Пример 2

Укажите столбцы, которые нужно выбрать для каждой записи.

 <code> // запрос на выбор данных с сервера. 
$ query = "выберите lastname, firstname, account_id, assign_user_id из контактов, где lastname = 'Valiant';";
// urlencode, который был отправлен по http.
$ queryParam = urlencode ($ query);
// sessionId получается из результата входа в систему.
$ params = "sessionName = $ sessionId & operation = query & query = $ queryParam";
// запрос должен быть запросом GET.
$ httpc-> get ("$ endpointUrl? $ params");
$ response = $ httpc-> currentResponse ();
// декодируем ответ json-кодирования от сервера.
$ jsonResponse = Zend_JSON :: decode ($ response ['body']);

// операция прошла успешно получить токен из ответа.
если ($ jsonResponse ['успех'] == false)
// обрабатываем случай сбоя.
die ('сбой запроса:'. $ jsonResponse ['errorMsg']);

// Массив SimplyObjects
$ retrievedObjects = $ jsonResponse ['результат'];
</code>

Это вернет массив, содержащий массивы, которые представляют поля каждого объекта, соответствующего запросу.

QueryResult

QueryResult — это массив SimplyObjects.

SimplyObject

Карта, представляющая содержимое объекта на основе качества. Все справочные поля представлены с использованием типа Id . Ключ ID типа Id представляет уникальный ID объекта. Это поле присутствует для любого объекта, полученного из базы данных.

Формат запроса

 <код> выберите * | <column_list> | <количество (*)> 
из <объект> [где <условия>]
[порядок по <column_list>] [предел [<m>,] <n>];

</code>

Список столбцов в предложении order by может иметь не более двух имен столбцов.

название Описание
column_list Список имен полей, разделенных запятыми.
объект Имя типа объекта.
условные Условные операции или предложения in или подобные предложения, разделенные операциями "и" или "или", обрабатываются слева направо. Нет группировки, то есть скобочных операторов.
условные операторы <,>, <=,> =, =,! =
в статьях <имя столбца> в (<список значений>).
подобные статьи <имя столбца> в (<шаблон значения>).
список значений Список значений, разделенных запятыми.
м, н Целочисленные значения для указания смещения и предела соответственно.

Синхронизировать

Sync вернет объект SyncResult, содержащий подробную информацию об изменениях после modifiedTime.

Формат URL

 <code> Тип запроса: GET 

http: //Simply_url/webservice.php? operation = sync

& sessionName = [идентификатор сеанса]
& modifiedTime = [отметка времени]
& elementType = [elementType]
</code>

elementType — необязательный параметр. Если указано, возвращаются только изменения для этого модуля по истечении заданного времени. В противном случае возвращаются изменения всех доступных пользователю модулей по истечении заданного времени.

TimeStamp — длинное представление количества секунд, прошедших с эпохи Unix.

Пример 1

Создайте учетную запись и запишите ее в API синхронизации.

Ответ содержит созданную учетную запись.

Пример 2

Создайте учетную запись и контакт, используйте API синхронизации только для модуля «Учетные записи», возвращаются только изменения в модуле «Учетные записи».

 <code> // время, по истечении которого необходимы все изменения на сервере. 
$ stime = время ();
// Создаем данные сейчас, чтобы они были захвачены ответом sync api.

// заполните данные Accounts.userId, полученные из loginResult.
$ accountData = array ('accountname' => 'Просто', 'assign_user_id' => $ userId);
// кодируем объект в формате JSON для связи с сервером.
$ objectJson = Zend_JSON :: encode ($ accountData);
// имя модуля, для которого должна быть создана запись.
$ moduleName = 'Аккаунты';

// sessionId получается из loginResult.
$ params = array ("sessionName" => $ sessionId, "operation" => 'create',
"element" => $ objectJson, "elementType" => $ moduleName);
// Создание должно быть POST-запросом.
$ httpc-> post ("$ endpointUrl", $ params, true);
$ response = $ httpc-> currentResponse ();
// декодируем ответ json-кодирования от сервера.
$ jsonResponse = Zend_JSON :: decode ($ response ['body']);

// операция прошла успешно получить токен из ответа.
если ($ jsonResponse ['успех'] == false)
// обрабатываем случай сбоя.
die ('ошибка создания:'. $ jsonResponse ['error'] ['errorMsg']);
$ createResult = $ jsonResponse ['результат'];

// Создаем контакт.
// заполняем детали контактов. userId получен из loginResult.
$ contactData = array ('lastname' => 'Valiant', 'assign_user_id' => $ userId);
// кодируем объект в формате JSON для связи с сервером.
$ objectJson = Zend_JSON :: encode ($ contactData);
// имя модуля, для которого должна быть создана запись.
$ moduleName = 'Контакты';

// sessionId получается из loginResult.
$ params = array ("sessionName" => $ sessionId, "operation" => 'create',
"element" => $ objectJson, "elementType" => $ moduleName);
// Создание должно быть POST-запросом.
httpc-> post ("$ endpointUrl", $ params, true);
$ response = $ httpc-> currentResponse ();
// декодируем ответ json-кодирования от сервера.
$ jsonResponse = Zend_JSON :: decode ($ response ['body']);

// операция прошла успешно получить токен из ответа.
если ($ jsonResponse ['успех'] == false)
// обрабатываем случай сбоя.
die ('ошибка создания:'. $ jsonResponse ['error'] ['errorMsg']);
$ savedObject = $ jsonResponse ['результат'];
$ id = $ savedObject ['идентификатор'];

$ params = "операция = синхронизация & modifiedTime = $ stime & sessionName = $ sessionId";

// синхронизация должна быть запросом GET.
$ httpc-> get ("$ endpointUrl? $ params");
$ response = $ httpc-> currentResponse ();
// декодируем ответ json-кодирования от сервера.
$ jsonResponse = Zend_JSON :: decode ($ response ['body']);

// операция прошла успешно получить токен из ответа.
если ($ jsonResponse ['успех'] == false)
// обрабатываем случай сбоя.
die ('сбой запроса:'. $ jsonResponse ['errorMsg']);
// Массив SimplyObjects
$ retrievedObjects = $ jsonResponse ['результат'];

</code>

SyncResult

Объект, представляющий ответ операции синхронизации.

 <code> SyncResult { 
updated: [Object] // Список созданных или измененных объектов.
удалено: [Id] // Список * Id * удаленных объектов.
lastModifiedTime: Timstamp // время последнего изменения. который можно использовать при следующем вызове Sync api, чтобы получить все последние изменения, которые клиент не получил.
}
</code>

Выход из системы

Выйти

Выйдите из сеанса веб-службы, в результате чего сеанс веб-службы станет недействительным для дальнейшего использования.

Формат URL

 <code> Тип запроса: GET 

http: //Simply_url/webservice.php? operation = logout

& sessionName = [идентификатор сеанса]
</code>

пример

Расширение веб-клиента Simply с помощью веб-службы

Продлить сеанс

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

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

Формат URL

 <code> Тип запроса: POST 

http: //Simply_url/webservice.php? operation = extensionsession

</code>

пример

 <код> 
</code>

Этот пример написан на Javascript, так как Extend Session действителен только из веб-клиента Simply.

Требования для запуска примера

  • Библиотека JQUERY — для выполнения HTTP-запроса ajax.
  • Библиотека JSON — файл json2.js доступен в Simply на json.org.

Пример 1

 <код> 
// параметры операции.
var params = "операция = расширение";
// конечная точка сервисов.
var endPointUrl = "http: //Simply_url/webservice.php";

// extendSession - это почтовый запрос, вызывающий почтовый запрос jquery http.
$ .post (endPointUrl, params, function (result) {
// декодируем ответ json-кодирования от сервера.
var jsonResponse = json.parse (результат);

// операция прошла успешно получить токен из ответа.
если (jsonResponse ['успех'] == ложь)
// обрабатываем случай сбоя.
die ('ошибка входа:' + jsonResponse ['error'] ['errorMsg']);

// Успешный вход в систему извлечь sessionId и userId из LoginResult, чтобы их можно было использовать для дальнейших вызовов.
var sessionId = jsonResponse ['результат'] ['sessionName'];
var userId = jsonResponse ['результат'] ['userId'];
});
</code>

Обновлено 24/09/2020

Была ли эта статья полезной?

Статьи по теме