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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

1
2
3
4
5
6
<?xml version="1.0" encoding="utf8" ?>
 <request>
   <action type="edit" uid="80085">
     …
   </action>
 </request>

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

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

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

1
2
3
4
5
6
7
<?xml version="1.0" encoding="utf8" ?>
 <request>
   <action type="auth" uid="80085">
     <login>my_login</login>
     <password>my_password</password>
   </action>
 </request>

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

1
2
3
4
5
6
7
8
 <?xml version="1.0" encoding="utf8" ?>
 <response>
   <action type="auth" uid="80085">
     <sess_id>
        646C57622DA4C91D027624F0426CC18478795291E1574F1A6C20BDC185D8B749
     </sess_id>
   </action>
 </response>

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

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

Пример:

1
2
3
4
5
6
7
8
<?xml version="1.0" encoding="utf8" ?>
 <request>
   <action type="list" uid="80085">
     <structure name="references.companies">
       ...
     </structure>
   </action>
 </request>

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

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

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

1
2
3
4
5
6
7
8
9
10
11
12
<?xml version="1.0" encoding="utf8" ?>
 <request>
   <action type="list" uid="80085">
     <structure name="references.companies">
       <fields>
         <id />
         <name />
         <date />
       </fields>
     </structure>
   </action>
 </request>

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

1
2
3
4
5
6
7
8
9
10
11
12
13
<?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>

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

Пример:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
<?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 — по убыванию).

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
<?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 контрагентов, начиная с первого:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
<?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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<?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 на «генеральный директор»:

1
2
3
4
5
6
7
8
9
10
<?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>

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

1
2
3
4
5
6
 <?xml version="1.0" encoding="utf8" ?>
 <response>
   <action type="edit" uid="80085">
     <result>true</result>
   </action>
 </response>

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
<?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) изменить запрос так:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
<?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» из справочника «Страна»

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
<?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>

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
<?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

Добавление

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<?xml version="1.0" encoding="utf8" ?>
 <request>
   <action type="add">
     <structure name="documents.orders">
       <number>2</number>
       <fields>
         <products>
           <structure name="products">
		   <fields>
			<name>Капуста</name>
		   </fields>             
           </structure>
         </products>
       </fields>
     </structure>
   </action>
 </request>

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

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

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

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

1
2
3
4
5
6
7
<?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)

1
2
3
4
5
6
7
8
9
10
11
<?xml version="1.0" encoding="utf8" ?>
 <request>
   <action type="list" uid="80085">
     <structure name="references.employees">
       <fields>
         <name />
        <photo/>
       </fields>
     </structure>
   </action>
 </request>

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

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

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

1
2
3
4
5
6
7
8
9
<?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>

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

1
2
3
4
5
6
7
8
9
<?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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
<?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

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

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

1
2
3
4
5
6
7
8
<?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 «Склада»

Ответ:

1
2
3
4
5
<action type="getProductPriceStock" uid="80085">
<price>100</price>
<stock>0</stock>
</action>
</response>

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

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

Ссылка для скачивания готового примера и класса на PHP: rbs-api-xml.zip

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
<?
// подключаем класс
require_once("rbs_api_xml.php");  
$ip=$_SERVER['REMOTE_ADDR'];
$ip = $ip;
$gorod = "Москва";
$type = 1; //тип заявки (см. перечисления в СРМ)
$date=date("d.m.y");
$time=date("H:i:s");
 
// Вставляем в СРМ 
$message_to_crm = "Описание заявки!";	
 
// авторизация
$xml_instance = new Xml_api("http://домен-срм.ру/api/xml", "логин пользователя", "пароль пользователя");
 
// cоздание контрагента
$xrm_create_login = $xml_instance->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"=>"<![CDATA[$message_to_crm]]>", "visible"=>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 символов

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

Пример:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
<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. Класс можно скачать по адресу: rbs-api-xml.zip

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Последние правки: 24.05.2017 11:30:50