Интеграция API (XML)

Использование API

Универсальный модуль «Интеграции API XML» Системы позволяем проводить обмен данными в формате XML между Системой и любым сторонним приложением.

В частности с помощью данного модуля происходит обмен данными с мобильными приложениями РосБизнесСофт (iPhone, Android), c сайтами, интернет-магазинами, АТС, биллингом и т.д.

Для того, чтобы пользователь имел доступ по API, в т.ч. для подключения через мобильное приложение, ему нужно поставить соответствующую галочку в Настройках.

wwwww

 

При помощи API интерфейса можно проводить следующие операции с данными (Объектами Системы):

  • чтение
  • добавление
  • редактирование
  • удаление
  • стирание
  • и т. д.

У вас есть три возможности отправить XML запрос в систему:

  • Через POST запрос в переменной «xml» на адрес: АДРЕС_ВАШЕЙ_СИСТЕМЫ/api/xml/. Это самый распространенный вариант!
  • Загрузить как файл, форма загрузки находится на странице /api/xml/ (в целях безопасности может быть отключена)
  • Как xml-текст, также через форму на странице /api/xml/ (в целях безопасности может быть отключена)

Структура представления данных (архитектура) доступна в «Конфигураторе» (/configurator) CRM системы.

Для работы с API можно использовать вспомогательный класс на PHP. См. подробное описание класса ниже.

Общий синтаксис

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

Каждый запрос представлен тегом . Тег всегда должен иметь параметр type (list, edit и т. д.), в котором необходимо передать корректный тип запроса.

Также можно передать в качестве атрибута тега параметр uid, несущий в себе уникальный идентификатор запроса. В это случае, при ответе системы этот идентификатор будет возвращен (это удобно для внутреннего различения запросов внутри системы). Если идентификатор не передан, он будет сгенерирован автоматически.

Пример корректного запроса:

<?xml version="1.0" encoding="utf8" ?>
<request>
<action type="edit" uid="80085">

</action>
</request>

Сессия и авторизация

Авторизация в системе производится путем передачи тегов и в запрос типа «auth».
При этом, если указаны верные данные, система сгенерирует и вернет 64-символьный идентификатор сессии. Этот идентификатор необходимо в дальнейшем передавать системе в заголовках в виде cookie с названием sess_id.

Корректный запрос на авторизацию:

<?xml version="1.0" encoding="utf8" ?>
<request>
<action type="auth" uid="80085">
<login>my_login</login>
<password>my_password</password>
</action>
</request>

Ответ системы:

<?xml version="1.0" encoding="utf8" ?>
<response>
<action type="auth" uid="80085">
<sess_id>
646C57622DA4C91D027624F0426CC18478795291E1574F1A6C20BDC185D8B749
</sess_id>
</action>
</response>

Запрос данных

Запрос данных имеет тип list. Каждая запрашиваемая структура должна быть обернута в тег с параметром name (названием структуры) и id (необязательно) — уникальный идентификатор запрашиваемой структуры (указание равносильно фильтрации по ключевому полю, см. ниже).

Пример:

<?xml version="1.0" encoding="utf8" ?>
<request>
<action type="list" uid="80085">
<structure name="references.companies">
...
</structure>
</action>
</request>

Ниже указано, как модифицировать запрос, чтобы получить только необходимые данные.

Выборка полей

Чтобы выбрать конкретные поля, добавьте в запрос тег и оберните в него теги с названиями полей (в том количестве и порядке, в котором они вам необходимы).

<?xml version="1.0" encoding="utf8" ?>
<request>
<action type="list" uid="80085">
<structure name="references.companies">
<fields>
<id />
<name />
<date />
</fields>
</structure>
</action>
</request>

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

<?xml version="1.0" encoding="utf8" ?>
<response>
<action type="list" uid="80085">
<structure name="references.companies" id="1">
<fields>
<id>1</id>
<name>ООО "Apple"</name>
<date>01.04.1976</date>
</fields>
</structure>
...
</action>
</response>

Для выборки вложенных структур, передайте тег внутри тега с названием поля-указателя, затем примените правила из этого раздела. Количество уровней вложенности не ограничено. Указывать тип структуры на вложенных уровнях не требуется.

Пример:

<?xml version="1.0" encoding="utf8" ?>
<request>
<action type="list" uid="80085">
<structure name="documents.orders">
<fields>
<number />
<products>
<structure>
<fields>
<name />
<number />
</fields>
</structure>
</products>
</fields>
</structure>
</action>
</request>

Упорядочивание, ограничение и фильтрация

Чтобы упорядочить по некоторому полю, используйте тег внутри . Его «детьми» сделайте по одному тегу для каждого упорядочивания, затем в каждый из них вложите тег с названием поля и с указанием типа упорядочивания (ASC — по возрастанию, DESC — по убыванию).

Каждый тег рассматривается и обрабатывается в порядке указания.

Пример: Вывести контрагентов, упорядоченных по дате добавления, начиная с самого позднего:

<?xml version="1.0" encoding="utf8" ?>
<request>
<action type="list" uid="80085">
<structure name="references.companies">
<fields>
<name />
</fields>
<orders>
<order>
<field>date</field>
<type>DESC</type>
</order>
</orders>
</structure>
</action>
</request>

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

Пример: Вывести не более 100 контрагентов, начиная с первого:

<?xml version="1.0" encoding="utf8" ?>
<request>
<action type="list" uid="80085">
<structure name="references.companies">
<fields>
<name />
</fields>
<limit>
<first>0</first>
<number>100</number>
</limit>
</structure>
</action>
</request>

Фильтровать контрагентов можно с использованием иерархии . Внутри последнего тега необходимы следующие три: для указания поля, по которому происходит фильтрация, для указания фильтрующей операции (>, =, <, like и т. д.) и для указания правого операнда.

Пример: Вывести счета с профитом больше 10000:

<?xml version="1.0" encoding="utf8" ?>
<request>
<action type="list" uid="80085">
<structure name="documents.orders">
<fields>
<number />
</fields>
<filters>
<filter>
<field>date</field>
<operation>></operation>
<value>10000</value>
</filter>
</filters>
</structure>
</action>
</request>

Редактирование

Для редактирования, используйте синтаксис выборки (описанный ниже) и передавайте внутри наследников тега необходимые значения.

Пример: Поменять поле «Должность» сотрудника с «id» = 25 на «генеральный директор»:

<?xml version="1.0" encoding="utf8" ?>
<request>
<action type="edit" uid="80085">
<structure name="references.employees" id="25">
<fields>
<position>Генеральный директор</position>
</fields>
</structure>
</action>
</request>

Пример ответа системы:

<?xml version="1.0" encoding="utf8" ?>
<response>
<action type="edit" uid="80085">
<result>true</result>
</action>
</response>

Если result = true, то запрос выполнился успешно.

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

<?xml version="1.0" encoding="utf8" ?>
<request>
<action type="edit">
<structure name="references.products" id="100">
<fields>
<country>
<structure name="references.countries">
<filters>
<filter>
<field>name</field>
<operation>=</operation>
<value>Китай</value>
</filter>
</filters>
</structure>
</country>
</fields>
</structure>
</action>
</request>

Если необходимо взять из справочника другое поле (не id) изменить запрос так:

<?xml version="1.0" encoding="utf8" ?>
<request>
<action type="edit">
<structure name="references.products" id="100">
<fields>
<country>
<structure name="references.countries">
<field>code</field>
<filters>
<filter>
<field>name</field>
<operation>=</operation>
<value>Китай</value>
</filter>
</filters>
</structure>
</country>
</fields>
</structure>
</action>
</request>

В примере выше добавится поле «code» из справочника «Страна»

Редактирование табличных частей

<?xml version="1.0" encoding="utf8" ?>
<request>
<action type="edit">
<structure name="documents.orders" id="100">
<fields>
<products>
<structure name="products">
<fields>
<name>Хлеб</name>
</fields>
<filters>
<filter>
<field>name</field>
<operation>=</operation>
<value>Молоко</value>
</filter>
</filters>
</structure>
</products>
</fields>
</structure>
</action>
</request>

В примере выше все «Продукты» в табличной части «Счета» с названием «Молоко» изменят название на «Хлеб».

Добавление значения в табличную часть

<?xml version="1.0" encoding="utf8" ?>
<request>
<action type="edit">
<structure name="documents.orders" id="100">
<fields>
<products>
<structure name="products" type="add">
<fields>
<name>Морковь</name>
</fields>
</structure>
</products>
</fields>
</structure>
</action>
</request>

В табличную часть счета добавится позиция с названием «Морковь».

Для стирания табличной части используется метод WIPE

Добавление

Для добавления используется следующая конструкция:

<?xml version="1.0" encoding="utf8" ?>
<request>
<action type="add">
<structure name="documents.orders">
<fields>
<products>
<structure name="products">
<fields>
<name>Капуста</name>
</fields>
</structure>
</products>
</fields>
</structure>
</action>
</request>

Добавит счет с номером 2 и одной позицией с названием «Капуста»

Стирание (удаление)

Для стирания, используйте синтаксис ниже. Обязательно нужно указывать ID объекта

Пример: Стереть (удалить) сотрудника с id=25:

<?xml version="1.0" encoding="utf8" ?>
<request>
<action type="wipe" uid="80085">
<structure name="references.employees" id="25">
</structure>
</action>
</request>

Запросить картинку

Фотография приходит в base64. Для получения картинки, поле в структуре должно быть «Указателем» на объект references.images

Например, запросить имя и фотографию сотрудников (поле — photo)

<?xml version="1.0" encoding="utf8" ?>
<request>
<action type="list" uid="80085">
<structure name="references.employees">
<fields>
<name />
<photo/>
</fields>
</structure>
</action>
</request>

Запросить время на сервере

<?xml version='1.0' encoding='utf8' ?>
<request>
<action type='getDatetime' uid='80085'>
<format>d.m.Y H:i:s</format>
</action>
</request>

Отправка электронной почты из Системы

<?xml version='1.0' encoding='utf8' ?>
<request>
<action type='sendMail' uid='80085'>
<from>mail@mail.ru</from>
<to>proger@rbs-crm.ru</to>
<theme>theme</theme>
<text>Message text</text>
</action>
</request>

Прикрепление приложения

<?xml version='1.0' encoding='utf8' ?>
<request>
<action type='fileAdd' uid='80085'>
<structure name='documents.repair' id='1'>
<name>file.txt</name>
<content>Text file</content>
</structure>
</action>
</request>

Создание заказа в CRM из интернет-магазина

При отправке данного запроса, машина автоматически проверяет наличие «Контрагента» в базе по 100% совпадению «Телефона» или «E-mail». При наличие совпадения, она создает «Счет» («Заказ») в найденном «Контрагенте», в противном случае она создает нового «Контрагента» и уже в нем создает «Счет» («Заказ»). Эту логику можно поменять, изменив файл в «Ядре», ответственный за API.

<?xml version='1.0' encoding='utf8' ?>
<request>
<action type="addOrder" uid="80085">
<shop_id>3</shop_id>
<client_email> proger @rbs-crm.ru</client_email>
<client_name>Стас Иванов</client_name>
<client_phone>9151234567</client_phone>
<client_organization_name>123</client_organization_name>
<client_organization_inn>123</client_organization_inn>
<client_organization_kpp>123</client_organization_kpp>
<client_city_id>12</client_city_id>
<client_city>Москва</client_city>
<order_date>2015-04-23 14:34:36</order_date>
<order_id></order_id>
<order_delivery_address>г. Москва</order_delivery_address>
<order_delivery_type>1</order_delivery_type>
<order_delivery_time>12</order_delivery_time>
<order_coupon>123</order_coupon>
<order_pay_method>1</order_pay_method>
<order_total>200</order_total>
<order_pay_total>0</order_pay_total>
<order_cash>0</order_cash>
<order_comment>asda</order_comment>
<products>
<product>
<product_id>1</product_id>
<product_article>123</product_article>
<product_name>erfsd</product_name>
<product_discount>15</product_discount>
<product_unit>шт</product_unit>
<number>3</number>
<price>150</price>
</product>
<product>
<product_id>5</product_id>
<product_article>234</product_article>
<product_name>rty</product_name>
<product_discount>15</product_discount>
<product_unit>шт</product_unit>
<number>5</number>
<price>240</price>
</product>
</products>
</action>
</request>

Внимание: Для работы данного запроса необходимо провести синхронизацию справочника «Номенклатуры» (Товаров) по id

Запрос цены и остатка товара

Корректный запрос на получение цены и остатка товара на складе:

<?xml version="1.0" encoding="utf8" ?>
<request>
<action type="getProductPriceStock" uid="80085">
<prod_id>777</prod_id>
<prod_price_id>1</prod_price_id>
<prod_stock_id>2</prod_stock_id>
</action>
</request>

где:
prod_id — id «Номенклатуры» (товара)
prod_price_id — id «Типа цены»
prod_stock_id — id «Склада»

Ответ:

<action type="getProductPriceStock" uid="80085">
<price>100</price>
<stock>0</stock>
</action>
</response>

где:
price — цена «Номенклатуры» (товара) в рублях, соответствующая запрошенному «Типу цен»
stock — остаток «Номенклатуры» (товара) на запрошенном «Складе»

Создание «Заявки» с сайта в Системе

Готовый примера и класса на PHP доступен по ссылке.

add("references.companies", array(														"date"=>date("Y-m-d",time()),"email"=>$email, "name"=>$name, "phone"=>$phone, "city"=>$gorod, "visible"=>1, "manager"=>68, "property_type"=>1, "type"=>1, "client_type"=>1, "learned_company"=>3));
			
// Получаем ID нового контрагента
$xrm_company_id = $xrm_create_login->action->id;
if($xrm_company_id>0){

// cоздание контакного лица
$xrm_insert_contact = $xml_instance->add("references.contacts", array("owner"=>$xrm_company_id, "name"=>$name, "phone"=>$phone, "email"=>$email, "visible"=>1));

// Получаем ID нового контактного лица
$xrm_contact_id = $xrm_insert_contact->action->id;

// cоздание нового юр лица			
$xrm_insert_details = $xml_instance->add("references.companies_details", array("owner"=>$xrm_company_id, "name"=>$name, "visible"=>1));

// создание заявки	
$xrm_insert_relationship = $xml_instance->add("documents.tender_simple", array("owner"=>$xrm_company_id, "date"=>date("Y-m-d H:i:s",time()),"type"=>$type, "status"=>1, "description"=>"1, "responsible"=>68, "priority"=>3));

//отправляем уведомления в СРМ всем сотрудникам
$employees = $xml_instance->select("references.employees", array("id"), array(array("field"=>"visible", "operation"=>"=", "value"=>1)));
foreach($employees->action->structure as $employee)
 {
  $xml_instance->add("references.messages", array(	
  "addressee"=>$employee->fields->id,
  "text"=>"Поступила новая заявка c сайта!",
  "sent"=>date("Y-m-d H:i:s", time()),
  "visible"=>1));
 }
?>

Экранирование XML символов

Для экранирования специальных символов типа «<" и ">» необходимо обернуть вышеперечисленные символы в

Пример:

<request>
<action type="list" uid="80085">
<structure name="documents.orders">
<fields>
<number />
</fields>
<filters>
<filter>
<field>date</field>
<operation><![CDATA[<]]></operation>
<value>2012-12-01</value>
</filter>
</filters>
</structure>
</action>
</request>

Универсальный класс на PHP для доступа к API XML РосБизнесСофт XRM

Существует дополнительный класс для работы с XML API написанный на PHP. Класс доступен по ссылке.

Для начала работы с классом необходимо создать подключение к Системе (авторизация):

$api = new Xml_api(string $url, string $login, string $password);

$url — Полный путь к API. Например: «https://mycrm.ru/api/xml»
$login — логин пользователя в программе
$password — пароль пользователя в программе

Для выборки данных используется метод:

SimpleXMLElement select(string $structure [, array $fields = array()] [, array $filters = array()]);

$structure — название структуры
$fields — массив полей, для выборки полей используется следующий синтаксис:
array(“id”, “name”, “surname”)
$filters — массив фильтров, для фильтрации результатов, используется следующий синтаксис:
array(array(“field”=>”id”, “operation”=>”=”, “value”=>”1”))

Для добавления данных используется метод:

SimpleXMLElement add(string $structure [,array $fields]);

$structure — название структуры
$fields — массив полей, для добавления значения полей используется следующий синтаксис:
array(«name» => «Вася», «surname» => «Пупкин»)

*не рекомендуется задавать явно поле id, поскольку это первичный ключ, система поддерживает работу с этим поле самостоятельно.

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

SimpleXMLElement update(string $structure [, array $fields = array()] [, array $filters = array()]);

$structure — название структуры
$fields — массив полей, для добавления значения полей используется следующий синтаксис:
array(“name”=>”Вася”, “surname”=>”Пупкин”)
$filters — массив фильтров, для фильтрации изменяемых полей, используется следующий синтаксис:
array (array(«field» => «id», «operation» => «=», «value» => «1»))

Остальные методы подробно описаны в самом классе.

Последние правки: 30.07.2020 15:52:43