API
В системе "Курьерская служба 2008" имеется возможность интеграции средствами XML API, по протоколу HTTP POST.
Содержание
Общие понятия
На стороне курьерской службы имеется веб-сервис. Адрес уточняйте у представителей компании. Авторизационные данные так же уточняйте у представителей компании. Клиент отправляет запросы к сервису, сервис обрабатывает запросы и возвращает результат выполнения. Все запросы и ответы передаются в формате XML. Кодировка - UTF-8. Разделитель целой и дробной частей чисел - используется символ точки. Даты представляются в виде YYYY-MM-DD, время - HH:MM.
Оформление заказа
Пример оформления заказа
<?xml version="1.0" encoding="UTF-8"?>
<neworder>
<auth login="login" pass="pass"></auth>
<order orderno="111111">
<barcode>111111</barcode>
<sender>
<company>МВД</company>
<person>Иванов И.И.</person>
<phone>123-45-67</phone>
<town>Санкт-Петербург</town>
<address>Петровка 38 офис 35</address>
<date>2014-03-22</date>
<time_min>09:00</time_min>
<time_max>14:00</time_max>
</sender>
<receiver>
<company>МВД</company>
<person>Иванов И.И.</person>
<phone>123-45-67</phone>
<town>Санкт-Петербург</town>
<address>Петровка 38 офис 35</address>
<date>2014-03-22</date>
<time_min>09:00</time_min>
<time_max>14:00</time_max>
</receiver>
<weight>5.1</weight>
<quantity>2</quantity>
<paytype>CASH</paytype>
<price>387.5</price>
<inshprice>387.5</inshprice>
<enclosure>Детские игрушки</enclosure>
<instruction>Проверить при покупателе, подписать акт</instruction>
<items>
<item quantity="1" mass="0.2" retprice="37.5" barcode="2345625213125" article="1">Мяч</item>
<item quantity="2" mass="2" retprice="100" barcode="4645625213138" article="2">Обруч</item>
<item quantity="3" mass="0.3" retprice="50" barcode="2345625213126" article="3">Погремушка желтая</item>
</items>
</order>
</neworder>
Описание элементов для оформления заказа:
- neworder - Корневой контейнер, обязательный элемент.
- order - Контейнер для описания одного заказа, обязательный элемент.
- orderno - Номер заказа. Если присваивается клиентом - указывается здесь. Если не присваивается - можно оставить пустым, система сгенерирует свой номер, и вернет его в ответе.
- barcode - Штрих-код заказа. В случае, если клиент штрих-кодирует свои отправления, и штрих-код отличается от номера заказа, в этом поле указывается штрих-код. В случае наличия нескольких мест, и раздельной их маркировки, в этом поле допустимы маски в виде символов подчеркивания, говорящие о позициях штрих-кода, переменных для разных мест в рамках одного заказа.
Например: В заказе номер 123 имеется 20 товарных вложений, которые упакованы в 3 транспортных места. Клиент формирует 3 штрих-кода на транспортные места: CLNT0012301, CLNT0012302, CLNT0012303, где CLNT - префикс клиента, 00123 - номер заказа, 01-03 - номер транспортного места в заказе. В поле barcode нужно указать CLNT00123__ (система поймет, что 2 последних символа могут быть любыми, и будут отражать штрих-коды к одному заказу).
- sender - Информация о отправителе заказа. Не обязательный контейнер.
<sender>
<company>Название компании отправителя</company>
<person>Контактное лицо отправителя</person>
<phone>Телефон, Email отправителя</phone>
<town>Город отправителя в формате "Москва город"</town>
<address>Адрес отправителя</address>
<date>Дата доставки в формате "YYYY-MM-DD"</date>
<time_min>Желаемое время доставки в формате "HH:MM"</time_min>
<time_max>Желаемое время доставки в формате "HH:MM"</time_max>
</sender>
- receiver - Информация о получателе заказа. Обязательный контейнер.
<receiver>
<company>Название компании получателя</company>
<person>Контактное лицо получателя</person>
<phone>Телефон, Email получателя</phone>
<town>Город получателя в формате "Москва город"</town>
<address>Адрес получателя</address>
<date>Дата доставки в формате "YYYY-MM-DD"</date>
<time_min>Желаемое время доставки в формате "HH:MM"</time_min>
<time_max>Желаемое время доставки в формате "HH:MM"</time_max>
</receiver>
- company - Компания-получатель. Должно быть заполнено company ИЛИ person!
- person - Контактное лицо. Должно быть заполнено company ИЛИ person!
- phone - Телефон. Можно указывать несколько телефонов, E-mail в этом поле.
- town - Город. В системе города привязываются к справочнику, поэтому город должен иметь правильное написание.
- paytype - Тип оплаты заказа получателем. Принимает значения:
CASH | Наличными (по-умолчанию) |
CARD | Картой |
NO | Без оплаты |
- weight - Общий вес заказа.
- quantity - Количество мест.
- price - Сумма заказа.
- enclosure - Вложение.
- inshprice - Объявленная ценность.
- instruction - Поручение - Примечание.
items - Контейнер для описания вложенных товаров. Не обязательный контейнер.
- item - Название товара.
- quantity - Количество товара.
- mass - Масса товара.
- retprice - Цена товара.
- barcode - Штрих-код товара.
- article - Артикул товара.
Примеры ответов
Пример успешного ответа
<?xml version="1.0" encoding="UTF-8"?>
<neworder>
<createorder orderno="AB23541" error="0" errormsg="success"></createorder>
<createorder orderno="55_6542" error="0" errormsg="success"></createorder>
<createorder orderno="AB23542" error="0" errormsg="success"></createorder>
</neworder>
Пример ответа с ошибкой
<?xml version="1.0" encoding="UTF-8"?>
<neworder>
<createorder orderno="AB23541" error="17" errormsg="Such number exists"></createorder>
<createorder orderno="AB23542" error="13" errormsg="empty company"></createorder>
<createorder orderno="AB23542" error="14" errormsg="empty person"></createorder>
</neworder>
Пример ответа при ошибке синтаксиса
<?xml version="1.0" encoding="UTF-8"?>
<request>
<error>column:1 line:11 message:expected '>'</error>
</request>
Коды ошибок при оформлении заказа
0 - Ошибок нет.
1 - Ошибка авторизации. (отсутствуют теги <auth login="" pass=""></auth>, неверный логин или пароль).
2 - Отправлен пустой запрос (отсутствует контейнер <neworder></neworder> в XML документе).
3 - Некорректно указана сумма заказа.
4 - Некорректный общий вес заказа.
5 - Не найден город получатель.
6 - Не найден город отправитель.
7 - Не заполнен адрес получателя.
8 - Не заполнен телефон получателя.
9 - Не заполнено контактное имя получателя.
10 - Не заполнено название компании получателя.
11 - Некорректная сумма объявленной ценности.
12 - Артикул не найден.
13 - Не заполнено название компании отправителя.
14 - Не заполнено контактное имя отправителя.
15 - Не заполнен телефон отправителя.
16 - Не заполнен адрес отправителя.
17 - Заказ с таким номером уже существует.
Запрос статуса заказов
Пример запроса статуса заказа
<?xml version="1.0" encoding="UTF-8" ?>
<statusreq>
<auth login="login" pass="pass"></auth>
<order orderno="1234">
<datefrom>2014-04-03</datefrom>
<dateto>2014-04-03</dateto>
<done>ONLY_NOT_DONE</done>
</order>
</statusreq>
Описание полей запроса статуса
Пример ответа на запрос статуса
<?xml version="1.0" encoding="UTF-8"?>
<statusreq>
<order orderno="1111">
<city>Санкт-Петербург</city>
<target>Петровка 38 офис 35</target>
<name>САМАРИТЯНИН</name>
<status>в доставке</status>
<enclosure>Вложение</enclosure>
<dateorder>03.04.2014</dateorder>
<datedelivered> </datedelivered>
</order>
<order orderno="2222">
<city>Санкт-Петербург</city>
<target>Петровка 38 офис 35</target>
<name>САМАРИТЯНИН</name>
<status>в доставке</status>
<enclosure>Вложение</enclosure>
<dateorder>03.04.2014</dateorder>
<datedelivered> </datedelivered>
</order>
</statusreq>