API GERP Gorserv
Описание протокола взаимодействия
Протокол SOAP
В настоящее время мы предоставляем для взаимодействия протокол SOAP.
Точка входа:
https://gerp.gorserv.com/soap/services.php?wsdl
Точка входа:
https://gerp.gorserv.com/soap/services.php?wsdl
Для тестов можно отправлять запросы через SoapUI.
Это двухсторонний обмен данные. Вы делаете запрос, получаете ответ.
Вот пример для SoapUI
Создаете новый проект SOAP. В строке wsdl указываете адрес нашей точки https://gerp.gorserv.com/soap/services.php?wsdl
Загружаются доступные методы
Раскрываете CreateTicket двойным щелчком и заполняете поля. Если данных нет по каким-то полям, то просто удаляете их. Выполняете запрос и получаете ответ. (город указывать очень желательно, иначе адрес может распознаться очень далеко)
Если указать istest=1, то диспетчера будут видеть что заявка тестовая и трогать её не будут.
В результате создается заявка в нашей системе, которую видят диспетчера и начинают с ней работать.
Это двухсторонний обмен данные. Вы делаете запрос, получаете ответ.
Вот пример для SoapUI
Создаете новый проект SOAP. В строке wsdl указываете адрес нашей точки https://gerp.gorserv.com/soap/services.php?wsdl
Загружаются доступные методы
Раскрываете CreateTicket двойным щелчком и заполняете поля. Если данных нет по каким-то полям, то просто удаляете их. Выполняете запрос и получаете ответ. (город указывать очень желательно, иначе адрес может распознаться очень далеко)
Если указать istest=1, то диспетчера будут видеть что заявка тестовая и трогать её не будут.
В результате создается заявка в нашей системе, которую видят диспетчера и начинают с ней работать.
0 => 'OK',
1 => 'Неверный логин или пароль',
2 => 'Недопустимый пользователь',
10 => 'Ошибка БД',
20 => 'Ошибка создания тикета',
30 => 'Ошибка отмены заявки', (для интерфейса connections)
40 => 'Недопустимый ID заявки или отсутствует комментарий',
50 => 'Указанный ID заявки не принадлежит Вашему контрагенту или не является заявкой типа Сервис',
60 => 'Указанная заявка уже отменена', (для интерфейса connections)
70 => 'Заявка с указанным идентификатором контрагента уже создана'
1 => 'Неверный логин или пароль',
2 => 'Недопустимый пользователь',
10 => 'Ошибка БД',
20 => 'Ошибка создания тикета',
30 => 'Ошибка отмены заявки', (для интерфейса connections)
40 => 'Недопустимый ID заявки или отсутствует комментарий',
50 => 'Указанный ID заявки не принадлежит Вашему контрагенту или не является заявкой типа Сервис',
60 => 'Указанная заявка уже отменена', (для интерфейса connections)
70 => 'Заявка с указанным идентификатором контрагента уже создана'
{
"code": 0,
"message": "ok",
"ticket_id": "1127748",
"source": "Заявка по интеграции от контрагента",
"status_id": null,
"status_name": "wait_partner, closed, papers_received",
"status_date": "2020-02-21T15:16:37+03:00",
"status_reason": "Документы сданы на сервисный центр",
"status_text": "Ожидание партнера, Закрыта, Бумаги получены",
"order": {
"items": [
{
"name": "Установка и подключение душевой кабины",
"price": {
"amount": 100000,
"currency": "RUB"
},
"quantity": 2,
"unit": "шт.",
"id": "60927ced-20ac-4196-8f93-bd1b94353f5e",
"ext_id": "30"
},
{
"name": "Установка и подключение унитаза напольного\/биде\/писсуара",
"price": {
"amount": 300000,
"currency": "RUB"
},
"quantity": 1,
"unit": "шт.",
"id": "ce7079a7-63be-4efd-8b8f-ee0a7ae7fb72",
"ext_id": "24"
}
],
"total": {
"amount": 500000,
"currency": "RUB"
}
},
"schedule": {
"start": "2020-02-21T17:30:00+03:00",
"end": "2020-02-21T19:30:00+03:00"
},
"status_history": {
"items": [
{
"date": "2020-02-21T15:14:32+03:00",
"old_status_name": "new",
"old_status_text": "Новая",
"new_status_name": "scheduled",
"new_status_text": "В графике"
},
....иные смены статусов.....
{
"date": "2020-02-21T15:16:37+03:00",
"old_status_name": "wait_papers",
"old_status_text": "Ожидание бумаг",
"new_status_name": "papers_received",
"new_status_text": "Бумаги получены"
}
]
},
"phone_calls": {
"first_at": "2020-02-21T15:14:04+03:00",
"first_successful_at": ""
}
"code": 0,
"message": "ok",
"ticket_id": "1127748",
"source": "Заявка по интеграции от контрагента",
"status_id": null,
"status_name": "wait_partner, closed, papers_received",
"status_date": "2020-02-21T15:16:37+03:00",
"status_reason": "Документы сданы на сервисный центр",
"status_text": "Ожидание партнера, Закрыта, Бумаги получены",
"order": {
"items": [
{
"name": "Установка и подключение душевой кабины",
"price": {
"amount": 100000,
"currency": "RUB"
},
"quantity": 2,
"unit": "шт.",
"id": "60927ced-20ac-4196-8f93-bd1b94353f5e",
"ext_id": "30"
},
{
"name": "Установка и подключение унитаза напольного\/биде\/писсуара",
"price": {
"amount": 300000,
"currency": "RUB"
},
"quantity": 1,
"unit": "шт.",
"id": "ce7079a7-63be-4efd-8b8f-ee0a7ae7fb72",
"ext_id": "24"
}
],
"total": {
"amount": 500000,
"currency": "RUB"
}
},
"schedule": {
"start": "2020-02-21T17:30:00+03:00",
"end": "2020-02-21T19:30:00+03:00"
},
"status_history": {
"items": [
{
"date": "2020-02-21T15:14:32+03:00",
"old_status_name": "new",
"old_status_text": "Новая",
"new_status_name": "scheduled",
"new_status_text": "В графике"
},
....иные смены статусов.....
{
"date": "2020-02-21T15:16:37+03:00",
"old_status_name": "wait_papers",
"old_status_text": "Ожидание бумаг",
"new_status_name": "papers_received",
"new_status_text": "Бумаги получены"
}
]
},
"phone_calls": {
"first_at": "2020-02-21T15:14:04+03:00",
"first_successful_at": ""
}
<?php
$client = new SoapClient('https://gerp.gorserv.com/soap/services.php?wsdl');
// works - услуги в заявке - необязательно (может быть null)
// Можно указать либо ID услуги в вашей системе, либо в нашей
// У нас есть два вида услуг - с фиксированной ценой и с произвольной ценой (работы по смете)
// для услуги с фиксированной ценой нужно указать количество - quantity
// для услуги с произвольной ценой нужно указать цену в копейках - amount
$works = [
'items' => [
[
'ext_id' => 30, // ID услуги в вашей системе
'quantity' => 1, // Количество услуг
],
[
'ext_id' => 40, // ID услуги в вашей системе
'quantity' => 3, // Количество услуг
],
[
'id' => 'eee0a76a-f60f-40b4-bd44-70a740fbe848', // ID в нашей системе (Цены)
'quantity' => 2, // Количество услуг
],
]
];
//не обязательно (может быть null)
$partner_ticket_id = '12345';
$result1 = $client->__soapCall('CreateTicket', [
'login' => 'login ',
'password' => 'password',
'addr_gor' => 'Москва',
'addr_ul' => 'Рязанский проспект',
'address_code' => null, // устарело (не используется)
'addr_dom' => '30',
'addr_pod' => '3',
'addr_etazh' => '4',
'addr_kv' => '145',
'domofon' => '145В',
'client_type' => 1, // 1 - частное лицо, 2 - компания
'org_name' => null, // название компании, если заказчик - компания
'fio' => 'Иванов Иван Иванович', // ФИО заказчика, если заказчик - частное лицо
'phones' => '+79635123456, 8 (915) 345-67-89', // телефоны в формате +79635123456 или 89635123456
'comment' => 'Описание заявки',
'lsnum' => $partner_ticket_id, // Номер заявки в вашей системе (не обязательно)
'req_type' => null, // устарело (не используется)
'start_date' => '15.01.2020 10:00', // start_date и end_date - рекомендуемое время посещения (с - по, в любом формате, будет добавлено в описание заявки, не обязательно)
'end_date' => '20.01.2020',
'task_type_id' => null, // устарело (не используется)
'operator_agreement' => null, // номер договора заказчика с провайдером (не обязательно)
'istest' => 0, // 1, если тестовая заявка
'works' => $works,
'agreement' => '123/250', // номер договора с нами, который нужно использовать в заявке (не обязательно)
]);
print_r($result1);
// Пример получения информации по заявке:
// по номеру заявки
$result2 = $client->CheckStatus('login', 'password', null, $result1['ticket_id']);
// либо по номеру заявки в вашей системе
//$result2 = $client->__soapCall('CheckStatus', ['login ', 'password', $partner_ticket_id]);
print_r($result2);
$client = new SoapClient('https://gerp.gorserv.com/soap/services.php?wsdl');
// works - услуги в заявке - необязательно (может быть null)
// Можно указать либо ID услуги в вашей системе, либо в нашей
// У нас есть два вида услуг - с фиксированной ценой и с произвольной ценой (работы по смете)
// для услуги с фиксированной ценой нужно указать количество - quantity
// для услуги с произвольной ценой нужно указать цену в копейках - amount
$works = [
'items' => [
[
'ext_id' => 30, // ID услуги в вашей системе
'quantity' => 1, // Количество услуг
],
[
'ext_id' => 40, // ID услуги в вашей системе
'quantity' => 3, // Количество услуг
],
[
'id' => 'eee0a76a-f60f-40b4-bd44-70a740fbe848', // ID в нашей системе (Цены)
'quantity' => 2, // Количество услуг
],
]
];
//не обязательно (может быть null)
$partner_ticket_id = '12345';
$result1 = $client->__soapCall('CreateTicket', [
'login' => 'login ',
'password' => 'password',
'addr_gor' => 'Москва',
'addr_ul' => 'Рязанский проспект',
'address_code' => null, // устарело (не используется)
'addr_dom' => '30',
'addr_pod' => '3',
'addr_etazh' => '4',
'addr_kv' => '145',
'domofon' => '145В',
'client_type' => 1, // 1 - частное лицо, 2 - компания
'org_name' => null, // название компании, если заказчик - компания
'fio' => 'Иванов Иван Иванович', // ФИО заказчика, если заказчик - частное лицо
'phones' => '+79635123456, 8 (915) 345-67-89', // телефоны в формате +79635123456 или 89635123456
'comment' => 'Описание заявки',
'lsnum' => $partner_ticket_id, // Номер заявки в вашей системе (не обязательно)
'req_type' => null, // устарело (не используется)
'start_date' => '15.01.2020 10:00', // start_date и end_date - рекомендуемое время посещения (с - по, в любом формате, будет добавлено в описание заявки, не обязательно)
'end_date' => '20.01.2020',
'task_type_id' => null, // устарело (не используется)
'operator_agreement' => null, // номер договора заказчика с провайдером (не обязательно)
'istest' => 0, // 1, если тестовая заявка
'works' => $works,
'agreement' => '123/250', // номер договора с нами, который нужно использовать в заявке (не обязательно)
]);
print_r($result1);
// Пример получения информации по заявке:
// по номеру заявки
$result2 = $client->CheckStatus('login', 'password', null, $result1['ticket_id']);
// либо по номеру заявки в вашей системе
//$result2 = $client->__soapCall('CheckStatus', ['login ', 'password', $partner_ticket_id]);
print_r($result2);
Статусы могут собираться в любые комбинации.
- new (Новая)
- delayed (Отложена)
- restored (Возобновлена)
- canceled (Отменена)
- rejected (Отклонена)
- took_to_work (Принял в работу)
- on_my_way (Мастер в пути)
- scheduled (В графике)
- in_work (В работе)
- took_by_patner (Обработана партнёром)
- wait_partner (Ожидает обработки партнёром)
- wait_ring (Ожидает обзвона)
- wait_papers (Ожидание бумаг)
- ringed (Обзвонена)
- reported (Отчёт получен)
- checked (Проверена)
- papers_recieved (Документы получены)
- closed (Закрыта)
- check_required (Требуется проверка)
Пример ответа на запрос статуса заявки в формате XML
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="https://gerp.gorserv.com/soap/services.php?wsdl">
<SOAP-ENV:Body>
<ns1:CheckStatusResponse>
<code>0</code>
<message>ok</message>
<ticket_id>1127748</ticket_id>
<source>Заявка по интеграции от контрагента</source>
<status_name>wait_partner, closed, papers_received</status_name>
<status_date>2020-02-21T15:16:37+03:00</status_date>
<status_text>Ожидание партнера, Закрыта, Бумаги получены</status_text>
<order>
<ns1:items>
<ns1:name>Установка и подключение душевой кабины</ns1:name>
<ns1:price>
<ns1:amount>100000</ns1:amount>
<ns1:currency>RUB</ns1:currency>
</ns1:price>
<ns1:quantity>2</ns1:quantity>
<ns1:unit>шт.</ns1:unit>
<ns1:id>60927ced-20ac-4196-8f93-bd1b94353f5e</ns1:id>
<ns1:ext_id>30</ns1:ext_id>
</ns1:items>
<ns1:items>
<ns1:name>Установка и подключение унитаза напольного/биде/писсуара</ns1:name>
<ns1:price>
<ns1:amount>300000</ns1:amount>
<ns1:currency>RUB</ns1:currency>
</ns1:price>
<ns1:quantity>1</ns1:quantity>
<ns1:unit>шт.</ns1:unit>
<ns1:id>ce7079a7-63be-4efd-8b8f-ee0a7ae7fb72</ns1:id>
<ns1:ext_id>24</ns1:ext_id>
</ns1:items>
<ns1:total>
<ns1:amount>500000</ns1:amount>
<ns1:currency>RUB</ns1:currency>
</ns1:total>
</order>
<schedule>
<ns1:start>2020-02-21T17:30:00+03:00</ns1:start>
<ns1:end>2020-02-21T19:30:00+03:00</ns1:end>
</schedule>
<status_history>
<ns1:items>
<ns1:date>2020-02-21T15:14:32+03:00</ns1:date>
<ns1:old_status_name>new</ns1:old_status_name>
<ns1:old_status_text>Новая</ns1:old_status_text>
<ns1:new_status_name>scheduled</ns1:new_status_name>
<ns1:new_status_text>В графике</ns1:new_status_text>
</ns1:items>
<ns1:items>
<ns1:date>2020-02-21T15:14:54+03:00</ns1:date>
<ns1:old_status_name>scheduled</ns1:old_status_name>
<ns1:old_status_text>В графике</ns1:old_status_text>
<ns1:new_status_name>took_to_work</ns1:new_status_name>
<ns1:new_status_text>Принял в работу</ns1:new_status_text>
</ns1:items>
<ns1:items>
<ns1:date>2020-02-21T15:15:11+03:00</ns1:date>
<ns1:old_status_name>took_to_work</ns1:old_status_name>
<ns1:old_status_text>Принял в работу</ns1:old_status_text>
<ns1:new_status_name>on_my_way</ns1:new_status_name>
<ns1:new_status_text>Мастер в пути</ns1:new_status_text>
</ns1:items>
<ns1:items>
<ns1:date>2020-02-21T15:15:18+03:00</ns1:date>
<ns1:old_status_name>on_my_way</ns1:old_status_name>
<ns1:old_status_text>Мастер в пути</ns1:old_status_text>
<ns1:new_status_name>in_work</ns1:new_status_name>
<ns1:new_status_text>В работе</ns1:new_status_text>
</ns1:items>
<ns1:items>
<ns1:date>2020-02-21T15:16:01+03:00</ns1:date>
<ns1:old_status_name>wait_ring</ns1:old_status_name>
<ns1:old_status_text>Ожидает обзвона</ns1:old_status_text>
<ns1:new_status_name>ringed</ns1:new_status_name>
<ns1:new_status_text>Обзвонена</ns1:new_status_text>
</ns1:items>
<ns1:items>
<ns1:date>2020-02-21T15:16:01+03:00</ns1:date>
<ns1:old_status_name>in_work</ns1:old_status_name>
<ns1:old_status_text>В работе</ns1:old_status_text>
<ns1:new_status_name>reported</ns1:new_status_name>
<ns1:new_status_text>Отчёт получен</ns1:new_status_text>
</ns1:items>
<ns1:items>
<ns1:date>2020-02-21T15:16:01+03:00</ns1:date>
<ns1:old_status_name>reported</ns1:old_status_name>
<ns1:old_status_text>Отчёт получен</ns1:old_status_text>
<ns1:new_status_name>wait_ring, check_required</ns1:new_status_name>
<ns1:new_status_text>Ожидает обзвона, check_required</ns1:new_status_text>
</ns1:items>
<ns1:items>
<ns1:date>2020-02-21T15:16:21+03:00</ns1:date>
<ns1:old_status_name>check_required</ns1:old_status_name>
<ns1:old_status_text>check_required</ns1:old_status_text>
<ns1:new_status_name>checked, wait_partner, wait_papers</ns1:new_status_name>
<ns1:new_status_text>Проверена, Ожидание партнера, Ожидание бумаг</ns1:new_status_text>
</ns1:items>
<ns1:items>
<ns1:date>2020-02-21T15:16:21+03:00</ns1:date>
<ns1:old_status_name>checked, ringed</ns1:old_status_name>
<ns1:old_status_text>Проверена, Обзвонена</ns1:old_status_text>
<ns1:new_status_name>closed</ns1:new_status_name>
<ns1:new_status_text>Закрыта</ns1:new_status_text>
</ns1:items>
<ns1:items>
<ns1:date>2020-02-21T15:16:37+03:00</ns1:date>
<ns1:old_status_name>wait_papers</ns1:old_status_name>
<ns1:old_status_text>Ожидание бумаг</ns1:old_status_text>
<ns1:new_status_name>papers_received</ns1:new_status_name>
<ns1:new_status_text>Бумаги получены</ns1:new_status_text>
</ns1:items>
</status_history>
<phone_calls>
<ns1:first_at>2020-02-21T15:14:04+03:00</ns1:first_at>
<ns1:first_successful_at/>
</phone_calls>
</ns1:CheckStatusResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Пример запроса списка заявок за период
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="https://gerp.gorserv.com/soap/services.php?wsdl">
<SOAP-ENV:Body>
<ns1:GetTickets>
<login>login</login><password>123</password>
<created_after>2020-03-25</created_after>
<created_before>2020-03-26</created_before>
</ns1:GetTickets>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
-----
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="https://gerp.gorserv.com/soap/services.php?wsdl">
<SOAP-ENV:Body>
<ns1:GetTickets>
<login>login</login><password>123</password>
<created_after>2020-03-26</created_after>
<created_before/>
</ns1:GetTickets>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>