API GERP Gorserv
Описание протокола взаимодействия
Протокол REST
В настоящее время мы предоставляем для взаимодействия протокол REST.
Точка входа:
https://gerp.gorserv.com/api/v1/
Авторизация по токену. В заголовок Authorization вместо TOKEN подставить свой токен.
Основной контур предназначен только для реальной работы.
Все тесты необходимо проводить на тестовом контуре. Для получения тестового доступа к API нашей системы GERP напишите нам письмо на адрес почты support@gorserv.com с указанием Вашего официального названия, либо обратитесь к Вашему персональному менеджеру в нашей компании.
За проведение тестов на основном контуре оставляем за собой право отключения доступа к нему до окончания процесса тестирования.
Точка входа:
https://gerp.gorserv.com/api/v1/
Авторизация по токену. В заголовок Authorization вместо TOKEN подставить свой токен.
Основной контур предназначен только для реальной работы.
Все тесты необходимо проводить на тестовом контуре. Для получения тестового доступа к API нашей системы GERP напишите нам письмо на адрес почты support@gorserv.com с указанием Вашего официального названия, либо обратитесь к Вашему персональному менеджеру в нашей компании.
За проведение тестов на основном контуре оставляем за собой право отключения доступа к нему до окончания процесса тестирования.
Поля типа STRING.
addr_gor - Город
addr_ul - Улица
addr_dom - Дом
addr_pod - Подъезд
addr_etazh - Этаж
addr_kv - Квартира
domofon - Домофон
org_name - Название организации (если client_type = 2)
fio - ФИО клиента
promocode - Промокод на скидку
phones - Контактные телефоны
description - Описание заявки
start_date - Желательное время начала работ
end_date
operator_agreement - Договор с клиентом
agreement - Договор (официальный номер договора)
type - Тип заявки
client_type - integer тип клиента (1 - Физ. лица, 2 - Юр. лица)
is_test - boolean признак тестовой заявки
works - массив списка работ по заявке (из нашего прейскуранта)
#"is_test": true - заявка будет помечена как тестовая в нашей системе.
# Незаполненные поля можно не указывать.
Все поля - необязательные, но желательно указать улицу, дом, квартиру, телефон, имя клиента
# phones можно в виде строки или массивом
phones - список телефонов.
Если у вас нет возможности указать отдельно каждый телефон, то можно в виде строки все телефоны сразу/
["89635123456", "+79990369694", "(999) 036-96-95"]
# Для type возможные варианты:
service - сервисная заявка
connection - подключение Интернет
accident - Авария
claim - Обращение
Если не указано - будет автоопределение из услуг, переданных в works, либо из услуг в Вашем в договоре, либо service
для type = claim
"type": "claim",
"source_ticket_gerp_id": "1297410" - ID заявки в системе GERP
или
"type": "claim",
"source_ticket_ext_id": "1234" - ID заявки в Вашей системе (исходная заявка должна быть ранее загружена в нашу систему с Вашим EXT_ID)
addr_gor - Город
addr_ul - Улица
addr_dom - Дом
addr_pod - Подъезд
addr_etazh - Этаж
addr_kv - Квартира
domofon - Домофон
org_name - Название организации (если client_type = 2)
fio - ФИО клиента
promocode - Промокод на скидку
phones - Контактные телефоны
description - Описание заявки
start_date - Желательное время начала работ
end_date
operator_agreement - Договор с клиентом
agreement - Договор (официальный номер договора)
type - Тип заявки
client_type - integer тип клиента (1 - Физ. лица, 2 - Юр. лица)
is_test - boolean признак тестовой заявки
works - массив списка работ по заявке (из нашего прейскуранта)
#"is_test": true - заявка будет помечена как тестовая в нашей системе.
# Незаполненные поля можно не указывать.
Все поля - необязательные, но желательно указать улицу, дом, квартиру, телефон, имя клиента
# phones можно в виде строки или массивом
phones - список телефонов.
Если у вас нет возможности указать отдельно каждый телефон, то можно в виде строки все телефоны сразу/
["89635123456", "+79990369694", "(999) 036-96-95"]
# Для type возможные варианты:
service - сервисная заявка
connection - подключение Интернет
accident - Авария
claim - Обращение
Если не указано - будет автоопределение из услуг, переданных в works, либо из услуг в Вашем в договоре, либо service
для type = claim
"type": "claim",
"source_ticket_gerp_id": "1297410" - ID заявки в системе GERP
или
"type": "claim",
"source_ticket_ext_id": "1234" - ID заявки в Вашей системе (исходная заявка должна быть ранее загружена в нашу систему с Вашим EXT_ID)
Статусы могут собираться в любые комбинации.
- 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 (Требуется проверка)
- tech_selection (Подбор исполнителя)
Методы при использовании СВОИХ идентификаторов заявок (ext_id)
# {YOUR_TICKET_ID} - ваш идентификатор заявки, он же ext_id в ответе
# Незаполненные поля можно не указывать.
# phones можно в виде строки или массивом
# для возможности использования списка работ works (список услуг с ценами) его необходимо предварительно создать
PUT https://gerp.gorserv.com/api/v1/tickets/{YOUR_TICKET_ID}
Accept: application/json
Content-Type: application/json
Authorization: Bearer TOKEN
{
"addr_gor": "Москва",
"addr_ul": "Ул. Петра Романова",
"addr_dom": "10",
"addr_pod": "1",
"addr_etazh": "2",
"addr_kv": "555",
"domofon": "555В",
"promocode": "АФРМ",
"client_type": 1,
"org_name": null,
"fio": "Иванов Владимир Витальевич",
"phones": ["89635123456", "+79990369694", "+79990369695"],
"description": "Описание заявки",
"start_date": null,
"end_date": null,
"operator_agreement": null,
"is_test": true,
"works": [
{
"ext_id": 123,
"quantity": 1
},
{
"id": "00010dea-3ab3-4451-b0d8-a6b3902128f3",
"quantity": 2
}
],
"agreement": null,
"type": null
}
###
# Пример ответа:
HTTP/1.1 200 OK
Content-Type: application/json
{
"ticket_id": "1258308",
"ext_id": "2518"
}
# Незаполненные поля можно не указывать.
# phones можно в виде строки или массивом
# для возможности использования списка работ works (список услуг с ценами) его необходимо предварительно создать
PUT https://gerp.gorserv.com/api/v1/tickets/{YOUR_TICKET_ID}
Accept: application/json
Content-Type: application/json
Authorization: Bearer TOKEN
{
"addr_gor": "Москва",
"addr_ul": "Ул. Петра Романова",
"addr_dom": "10",
"addr_pod": "1",
"addr_etazh": "2",
"addr_kv": "555",
"domofon": "555В",
"promocode": "АФРМ",
"client_type": 1,
"org_name": null,
"fio": "Иванов Владимир Витальевич",
"phones": ["89635123456", "+79990369694", "+79990369695"],
"description": "Описание заявки",
"start_date": null,
"end_date": null,
"operator_agreement": null,
"is_test": true,
"works": [
{
"ext_id": 123,
"quantity": 1
},
{
"id": "00010dea-3ab3-4451-b0d8-a6b3902128f3",
"quantity": 2
}
],
"agreement": null,
"type": null
}
###
# Пример ответа:
HTTP/1.1 200 OK
Content-Type: application/json
{
"ticket_id": "1258308",
"ext_id": "2518"
}
# все поля необязательны
PATCH https://gerp.gorserv.com/api/v1/tickets/{YOUR_TICKET_ID}
Accept: application/json
Content-Type: application/json
Authorization: Bearer TOKEN
{
"addr_gor": "Москва",
"addr_ul": "Ул. Петра Романова",
"addr_dom": "11",
"addr_pod": "1",
"addr_etazh": "2",
"addr_kv": "555",
"domofon": "555В",
"client_type": 1,
"org_name": null,
"fio": "Иванов Владимир Витальевич2",
"phones": "89635123457, +79990369694, +79990369695",
"works": [
{
"ext_id": 123,
"quantity": 2
},
{
"id": "00010dea-3ab3-4451-b0d8-a6b3902128f3",
"quantity": 3
}
],
"agreement": null
}
PATCH https://gerp.gorserv.com/api/v1/tickets/{YOUR_TICKET_ID}
Accept: application/json
Content-Type: application/json
Authorization: Bearer TOKEN
{
"addr_gor": "Москва",
"addr_ul": "Ул. Петра Романова",
"addr_dom": "11",
"addr_pod": "1",
"addr_etazh": "2",
"addr_kv": "555",
"domofon": "555В",
"client_type": 1,
"org_name": null,
"fio": "Иванов Владимир Витальевич2",
"phones": "89635123457, +79990369694, +79990369695",
"works": [
{
"ext_id": 123,
"quantity": 2
},
{
"id": "00010dea-3ab3-4451-b0d8-a6b3902128f3",
"quantity": 3
}
],
"agreement": null
}
GET https://gerp.gorserv.com/api/v1/tickets/{YOUR_TICKET_ID}
Accept: application/json
Authorization: Bearer TOKEN
Accept: application/json
Authorization: Bearer TOKEN
POST https://gerp.gorserv.com/api/v1/tickets/{YOUR_TICKET_ID}/comment
Accept: application/json
Content-Type: application/json
Authorization: Bearer TOKEN
{
"comment": "Комментарий."
}
Accept: application/json
Content-Type: application/json
Authorization: Bearer TOKEN
{
"comment": "Комментарий."
}
# created_after <= дата_создания < created_before
#
# created_after - обязательно
# created_before - необязательно
GET https://gerp.gorserv.com/api/v1/tickets?created_after=2020-10-01
Accept: application/json
Authorization: Bearer TOKEN
#
# created_after - обязательно
# created_before - необязательно
GET https://gerp.gorserv.com/api/v1/tickets?created_after=2020-10-01
Accept: application/json
Authorization: Bearer TOKEN
Типы заявок
# Незаполненные поля можно не указывать.
# phones можно в виде строки или массивом
{
"addr_gor": "Москва",
"addr_ul": "Ул. Петра Романова",
"addr_dom": "10",
"addr_pod": "1",
"addr_etazh": "2",
"addr_kv": "555",
"domofon": "555В",
"client_type": 1,
"org_name": null,
"fio": "Иванов Владимир Витальевич",
"phones": ["89635123456", "+79990369694", "+79990369695"],
"description": "Описание заявки",
"start_date": null,
"end_date": null,
"operator_agreement": null,
"is_test": true,
"works": [
{
"ext_id": 123,
"quantity": 1
},
{
"id": "00010dea-3ab3-4451-b0d8-a6b3902128f3",
"quantity": 2
}
],
"agreement": null,
"type": null
}
###
# Пример ответа:
HTTP/1.1 200 OK
Content-Type: application/json
{
"ticket_id": "1258308",
"ext_id": "2518"
}
# phones можно в виде строки или массивом
{
"addr_gor": "Москва",
"addr_ul": "Ул. Петра Романова",
"addr_dom": "10",
"addr_pod": "1",
"addr_etazh": "2",
"addr_kv": "555",
"domofon": "555В",
"client_type": 1,
"org_name": null,
"fio": "Иванов Владимир Витальевич",
"phones": ["89635123456", "+79990369694", "+79990369695"],
"description": "Описание заявки",
"start_date": null,
"end_date": null,
"operator_agreement": null,
"is_test": true,
"works": [
{
"ext_id": 123,
"quantity": 1
},
{
"id": "00010dea-3ab3-4451-b0d8-a6b3902128f3",
"quantity": 2
}
],
"agreement": null,
"type": null
}
###
# Пример ответа:
HTTP/1.1 200 OK
Content-Type: application/json
{
"ticket_id": "1258308",
"ext_id": "2518"
}
# к полям заявки типа service добавить следующее
type="claim"
и source_ticket_gerp_id="ID исходной заявки в нашей системе"
или source_ticket_ext_id="ID исходной заявки в Вашей системе" (должна быть заведена у нас ранее именно с этим EXT_ID)
type="claim"
и source_ticket_gerp_id="ID исходной заявки в нашей системе"
или source_ticket_ext_id="ID исходной заявки в Вашей системе" (должна быть заведена у нас ранее именно с этим EXT_ID)
Методы при использовании НАШИХ идентификаторов заявок (ticket_id)
### Создать заявку.
# Незаполненные поля можно не указывать.
# phones можно в виде строки или массивом
# для возможности использования списка работ works (список услуг с ценами) его необходимо предварительно создать
PUT https://gerp.gorserv.com/api/v1/tickets
Accept: application/json
Content-Type: application/json
Authorization: Bearer TOKEN
{
"addr_gor": "Москва",
"addr_ul": "Ул. Петра Романова",
"addr_dom": "10",
"addr_pod": "1",
"addr_etazh": "2",
"addr_kv": "555",
"domofon": "555В",
"promocode": "АФРМ",
"client_type": 1,
"org_name": null,
"fio": "Иванов Владимир Витальевич",
"phones": ["89635123456", "+79990369694", "+79990369695"],
"description": "Описание заявки",
"start_date": null,
"end_date": null,
"operator_agreement": null,
"is_test": true,
"works": [
{
"ext_id": 123,
"quantity": 1
},
{
"id": "00010dea-3ab3-4451-b0d8-a6b3902128f3",
"quantity": 2
}
],
"agreement": null,
"type": ""
}
###
# Пример ответа:
HTTP/1.1 200 OK
Content-Type: application/json
{
"ticket_id": "1258308",
"ext_id": null
}
# Незаполненные поля можно не указывать.
# phones можно в виде строки или массивом
# для возможности использования списка работ works (список услуг с ценами) его необходимо предварительно создать
PUT https://gerp.gorserv.com/api/v1/tickets
Accept: application/json
Content-Type: application/json
Authorization: Bearer TOKEN
{
"addr_gor": "Москва",
"addr_ul": "Ул. Петра Романова",
"addr_dom": "10",
"addr_pod": "1",
"addr_etazh": "2",
"addr_kv": "555",
"domofon": "555В",
"promocode": "АФРМ",
"client_type": 1,
"org_name": null,
"fio": "Иванов Владимир Витальевич",
"phones": ["89635123456", "+79990369694", "+79990369695"],
"description": "Описание заявки",
"start_date": null,
"end_date": null,
"operator_agreement": null,
"is_test": true,
"works": [
{
"ext_id": 123,
"quantity": 1
},
{
"id": "00010dea-3ab3-4451-b0d8-a6b3902128f3",
"quantity": 2
}
],
"agreement": null,
"type": ""
}
###
# Пример ответа:
HTTP/1.1 200 OK
Content-Type: application/json
{
"ticket_id": "1258308",
"ext_id": null
}
# {TICKET_ID} - идентификатор заявки GERP
# все поля необязательны
PATCH https://gerp.gorserv.com/api/v1/tickets?ticket_id={TICKET_ID}
Accept: application/json
Content-Type: application/json
Authorization: Bearer TOKEN
{
"addr_gor": "Москва",
"addr_ul": "Ул. Петра Романова",
"addr_dom": "11",
"addr_pod": "1",
"addr_etazh": "2",
"addr_kv": "555",
"domofon": "555В",
"client_type": 1,
"org_name": null,
"fio": "Иванов Владимир Витальевич2",
"phones": "89635123457, +79990369694, +79990369695",
"works": [
{
"ext_id": 123,
"quantity": 2
},
{
"id": "00010dea-3ab3-4451-b0d8-a6b3902128f3",
"quantity": 3
}
],
"agreement": null
}
# все поля необязательны
PATCH https://gerp.gorserv.com/api/v1/tickets?ticket_id={TICKET_ID}
Accept: application/json
Content-Type: application/json
Authorization: Bearer TOKEN
{
"addr_gor": "Москва",
"addr_ul": "Ул. Петра Романова",
"addr_dom": "11",
"addr_pod": "1",
"addr_etazh": "2",
"addr_kv": "555",
"domofon": "555В",
"client_type": 1,
"org_name": null,
"fio": "Иванов Владимир Витальевич2",
"phones": "89635123457, +79990369694, +79990369695",
"works": [
{
"ext_id": 123,
"quantity": 2
},
{
"id": "00010dea-3ab3-4451-b0d8-a6b3902128f3",
"quantity": 3
}
],
"agreement": null
}
GET https://gerp.gorserv.com/api/v1/tickets?ticket_id={TICKET_ID}
Accept: application/json
Authorization: Bearer TOKEN
Accept: application/json
Authorization: Bearer TOKEN
POST https://gerp.gorserv.com/api/v1/tickets/-/comment?ticket_id={TICKET_ID}
Accept: application/json
Content-Type: application/json
Authorization: Bearer TOKEN
{
"comment": "Комментарий."
}
Accept: application/json
Content-Type: application/json
Authorization: Bearer TOKEN
{
"comment": "Комментарий."
}
# created_after <= дата_создания < created_before
#
# created_after - обязательно
# created_before - необязательно
GET https://gerp.gorserv.com/api/v1/tickets?created_after=2020-10-01
Accept: application/json
Authorization: Bearer TOKEN
#
# created_after - обязательно
# created_before - необязательно
GET https://gerp.gorserv.com/api/v1/tickets?created_after=2020-10-01
Accept: application/json
Authorization: Bearer TOKEN
Результаты запросов
Код HTTP - 200 - успех
Другой код - ошибка
Другой код - ошибка
В случае ошибки в ответе будет error_code и message с описанием.
{
"error_code": "TICKET_NOT_FOUND",
"message": "Ticket not found!",
"ext_id": "12345"
или
"ticket_id": "123456"
}
Ошибки:
UNAUTHORIZED
DUPLICATE_EXT_ID
TICKET_NOT_FOUND
INTERNAL_ERROR
PRICE_POSITION_NOT_FOUND
BAD_REQUEST
ext_id и ticket_id берутся из вашего запроса, если они там были.
{
"error_code": "TICKET_NOT_FOUND",
"message": "Ticket not found!",
"ext_id": "12345"
или
"ticket_id": "123456"
}
Ошибки:
UNAUTHORIZED
DUPLICATE_EXT_ID
TICKET_NOT_FOUND
INTERNAL_ERROR
PRICE_POSITION_NOT_FOUND
BAD_REQUEST
ext_id и ticket_id берутся из вашего запроса, если они там были.
Получение каталога доступных услуг
GET https://gerp.gorserv.com/api/v1/catalog/all
Ответ:
{
"data": [
{
"id": "0aafc713-9446-416a-8a7d-ba624a44c681",
"title": "Оптика",
"duration": null,
"path": "Каталог \/ Сервис \/ Компьютерная помощь \/ Оптика",
"works": [
{
"id": "0f1d9390-9153-4301-8313-21a3d194cba0",
"title": "Измерение уровня оптического сигнала (скидка 10%)",
"description": "Услуга включает в себя замер уровня затухания оптического сигнала посредством специализированного прибора.",
"duration": "00-00T00:15:00",
"minimal_order": 0,
"unit": null,
"prices": [
{
"id": "a991e951-42ba-47a0-bffa-cc18a8bbdb0e",
"cost": 27000,
"currency": "RUB",
"service_center": {
"id": 45,
"name": "Пенза"
},
"agreement": {
"id": 1092,
"number": "А 11\/20-015",
"note": null
}
}
]
},
Ответ:
{
"data": [
{
"id": "0aafc713-9446-416a-8a7d-ba624a44c681",
"title": "Оптика",
"duration": null,
"path": "Каталог \/ Сервис \/ Компьютерная помощь \/ Оптика",
"works": [
{
"id": "0f1d9390-9153-4301-8313-21a3d194cba0",
"title": "Измерение уровня оптического сигнала (скидка 10%)",
"description": "Услуга включает в себя замер уровня затухания оптического сигнала посредством специализированного прибора.",
"duration": "00-00T00:15:00",
"minimal_order": 0,
"unit": null,
"prices": [
{
"id": "a991e951-42ba-47a0-bffa-cc18a8bbdb0e",
"cost": 27000,
"currency": "RUB",
"service_center": {
"id": 45,
"name": "Пенза"
},
"agreement": {
"id": 1092,
"number": "А 11\/20-015",
"note": null
}
}
]
},
Промокоды
GET https://gerp.gorserv.com/api/promocodes/new
{
partner_id: required, integer
typeof: required, percent
amount: required, integer
active_till: datetime
service_center_id: required, integer or null
to_generate: required, integer
}
to_generate - сколько кодов сделать
partner_id - выдаётся техподдержкой
typeof - тип скидки - проценты
amount - величина скидки в процентах
service_center_id - ID города, выдаётся техподдержкой
active_till - срок действия промокода
В ответ Вы получите массив со сгенирированными промокодами.
{
"promocodes": [
{
"partner_id": "0001",
"typeof": "percent",
"amount": "10",
"active_till": "2022-02-08",
"code": "УЛБТ",
"updated_at": "2022-02-08T11:02:16.000000Z",
"created_at": "2022-02-08T11:02:16.000000Z",
"id": 152,
"enabled": true,
"onetime": true
},
{
"partner_id": "0001",
"typeof": "percent",
"amount": "10",
"active_till": "2022-02-08",
"code": "6ЖЫ8",
"updated_at": "2022-02-08T11:02:16.000000Z",
"created_at": "2022-02-08T11:02:16.000000Z",
"id": 153,
"enabled": true,
"onetime": true
}
]
}
{
partner_id: required, integer
typeof: required, percent
amount: required, integer
active_till: datetime
service_center_id: required, integer or null
to_generate: required, integer
}
to_generate - сколько кодов сделать
partner_id - выдаётся техподдержкой
typeof - тип скидки - проценты
amount - величина скидки в процентах
service_center_id - ID города, выдаётся техподдержкой
active_till - срок действия промокода
В ответ Вы получите массив со сгенирированными промокодами.
{
"promocodes": [
{
"partner_id": "0001",
"typeof": "percent",
"amount": "10",
"active_till": "2022-02-08",
"code": "УЛБТ",
"updated_at": "2022-02-08T11:02:16.000000Z",
"created_at": "2022-02-08T11:02:16.000000Z",
"id": 152,
"enabled": true,
"onetime": true
},
{
"partner_id": "0001",
"typeof": "percent",
"amount": "10",
"active_till": "2022-02-08",
"code": "6ЖЫ8",
"updated_at": "2022-02-08T11:02:16.000000Z",
"created_at": "2022-02-08T11:02:16.000000Z",
"id": 153,
"enabled": true,
"onetime": true
}
]
}
Расширение API