API нашего сервиса предоставляет партнерам возможность прямой интеграции с нашей системой.
API дает возможность использовать приложения или сервисы, автоматизирующие процесс создания новых заказов, работу со складом, и пр.
Обмен данными происходит путем отправки XML-документов с помощью POST-запросов. Все запросы к API должны быть в кодировке UTF-8. Сервер возвращает ответ в виде XML-документа (или сгенерированного PDF-файла). В случае ошибки XML-документ содержит номер ошибки и её описание.
Обращения к сереверу происходят по адресу: http://gocarrylk.ru/api/v1/
Для отправки запроса вам необходимо знать свои userId и userApiKey (уточните у наших специалистов через тикеты).
Данный PHP-код является одним из возможных вариантов обращения к нашему API.
Обязательными элементами для всех запросов являются: method userId userApiKey
Все дополнительный параметры запроса передаются в элементе params
Для тестовых запросов добавьте в request элемент <apiTest>1</apiTest>
<?php
$user_id = "100";
$user_api_key = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";
$xml = "<?xml version=\"1.0\" encoding=\"utf-8\"?>
<request>
<method>get_api_info</method>
<userId>".$user_id."</userId>
<userApiKey>".$user_api_key."</userApiKey>
</request>";
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'http://gocarrylk.ru/api/v1/');
curl_setopt($curl, CURLOPT_POST, 1);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_POSTFIELDS, 'xml='.$xml);
curl_setopt($curl, CURLOPT_USERAGENT, 'Remote API user 1.00');
$result = curl_exec($curl);
curl_close($curl);
echo $result;
?>
Ответ сервера:
<?xml version="1.0" encoding="utf-8"?>
<response>
<status>200</status>
<method>get_api_info</method>
<api_version>1.0</api_version>
</response>
Обязательными элементами являются status — содержит числовой код статуса ответа, method — метод обращения к API.
Успешным ответом является код 200.
Ответ сервера содержащий ошибку:
<?xml version="1.0" encoding="utf-8"?>
<response>
<status>500</status>
<method>zakaz_add</method>
<error>Товара [tovar_id: 3800] нет в нужном колличестве [1] на складе [pvz_id: 32]</error>
</response>
Получение текущей версии API. Название используемого метода передается в элементе method
<?xml version="1.0" encoding="utf-8"?>
<request>
<method>get_api_info</method>
<userId>".$user_id."</userId>
<userApiKey>".$user_api_key."</userApiKey>
</request>
Ответ сервера:
<?xml version="1.0" encoding="utf-8"?>
<response>
<status>200</status>
<method>get_api_info</method>
<api_version>1.0</api_version>
<api_date>2016-12-31</api_date>
</response>
status — статуса ответа
method — метод обращения к API
api_version — текущая версия API
api_date — дата выпуска версии API
Получение списка доступных пунктов выдачи.
<?xml version="1.0" encoding="utf-8"?>
<request>
<method>get_pvz_list</method>
<userId>".$user_id."</userId>
<userApiKey>".$user_api_key."</userApiKey>
</request>
Ответ сервера:
<?xml version="1.0" encoding="utf-8"?>
<response>
<method>get_pvz_list</method>
<status>200</status>
<items>
<item>
<id>32</id>
<name>Ладожская</name>
<phone></phone>
<adress>Индустриальный 22</adress>
<city>Санкт-Петербург</city>
<city_id>78</city_id>
<url></url>
<time>Пн-Вс 10-21</time>
<desc></desc>
</item>
...
<item>
<id>33</id>
<name>Ломоносовская</name>
<phone>+7 (812) 677-14-19</phone>
<adress>Полярников д.6</adress>
<city>Санкт-Петербург</city>
<city_id>78</city_id>
<url></url>
<time>Пн-Вс 11-20</time>
<desc></desc>
</item>
</items>
</response>
status — статуса ответа
method — метод обращения к API
Успешный ответ содержит элемент items который в свою очередь может содержать некоторое количество элементов item с информацией о пунктах выдачи.
id — уникальный идентификатор ПВЗ, необходим для оформления заказов
name — название пункта выдачи
phone — контактный телефон
adress — адрес пункта выдачи
city — город в котором расположен пункт выдачи
city_id — идентификатор города ПВЗ
url — ссылка на сайт
time — время работы пункта выдачи
desc — текстовое описание (например, как найти ПВЗ)
Получение списка комиссий для партнера.
<?xml version="1.0" encoding="utf-8"?>
<request>
<method>get_tax</method>
<userId>".$user_id."</userId>
<userApiKey>".$user_api_key."</userApiKey>
</request>
Ответ сервера:
<?xml version="1.0" encoding="utf-8"?>
<response>
<method>get_tax</method>
<status>200</status>
<user_id>100</user_id>
<taxes user_id="100">
<tax value="0.00">Доставка по СПб</tax>
<tax value="0.00">Доставка по МСК</tax>
<tax value="100.00">Комиссия за выдачу заказа</tax>
<tax value="2.50">Комиссия за приём наличных</tax>
<tax value="2.50">Комиссия за приём безналичных</tax>
<tax value="0.00">Комиссия за аренду</tax>
<tax value="0.00">Комиссия за отправку по рф</tax>
<tax value="0.00">Комиссия за упаковку</tax>
<tax value="50.00">Комиссия за перемещение товара между ПВЗ</tax>
<tax value="0.00">Комиссия за сборку</tax>
<tax value="0.00">Комиссия за отправку смс</tax>
<tax value="0.00">Комиссия за уведомление звонком</tax>
<tax value="0.00">Комиссия за хранение, за сутки</tax>
<tax value="20">Количество дней бесплатного хранения</tax>
</taxes>
</response>
status — статуса ответа
method — метод обращения к API
user_id — ID пользователя для которого выводится информация
Успешный ответ содержит элемент taxes который в свою очередь может содержать некоторое количество элементов tax с информацией о тарифах.
tax — элемент с названием комиссии, значение передается в атрибуте value. Значение может быть в рублях, в процентах, в днях (в зависимости от типа комиссии). Для разных пользователей список может содержать разные типы комиссий.
Создание нового товара.
<?xml version="1.0" encoding="utf-8"?>
<request>
<method>tovar_add</method>
<userId>".$user_id."</userId>
<userApiKey>".$user_api_key."</userApiKey>
<params>
<sku_from_owner>724461</sku_from_owner>
<name>Название тестового товара</name>
<price>100</price>
<weight>0.5</weight>
<length>20</length>
<width>10</width>
<height>10</height>
</params>
</request>
sku_from_owner — внутренний SKU товара присвоенный магазином (varchar(100))
name — наименование товара (varchar(255))
price — цена товара в рублях (decimal(9,2))
weight — вес товара с упаковкой в килограммах (double(6,1))
length — длинна упакованного товара в сантиметрах (int(5))
width — ширина упакованного товара в сантиметрах (int(5))
height — высота упакованного товара в сантиметрах (int(5))
Ответ сервера:
<?xml version="1.0" encoding="utf-8"?>
<response>
<method>tovar_add</method>
<status>200</status>
<tovar_id>3800</tovar_id>
<sku_from_owner>724461</sku_from_owner>
</response>
status — статуса ответа
method — метод обращения к API
tovar_id — уникальный ID товара в нашей системе, автоматически присваивается при создании
sku_from_owner — внутренний SKU товара присвоенный магазином
Добавление товара на склад.
<?xml version="1.0" encoding="utf-8"?>
<request>
<method>stok_add</method>
<userId>".$user_id."</userId>
<userApiKey>".$user_api_key."</userApiKey>
<params>
<start_pvz>32</start_pvz>
<finish_pvz>33</finish_pvz>
<items>
<item>
<id>3800</id>
<quanity>1</quanity>
</item>
<item>
<id>3801</id>
<quanity>1</quanity>
</item>
</items>
</params>
</request>
start_pvz — ID пункта выдачи для поступления товара (int(11))
finish_pvz — ID пункта выдачи для назначения товара (int(11))
items может содержать некоторое количество элементов item с информацией о товаре
id — уникальный ID добавляемого товара в нашей системе (int(11))
quanity — количество товара (int(5))
Ответ сервера:
<?xml version="1.0" encoding="utf-8"?>
<response>
<method>stok_add</method>
<status>200</status>
<items_added>2</items_added>
</response>
status — статуса ответа
method — метод обращения к API
items_added — количество успешно добавленных товаров
Получение списка товаров и наличия на складе.
<?xml version="1.0" encoding="utf-8"?>
<request>
<method>get_stok</method>
<userId>".$user_id."</userId>
<userApiKey>".$user_api_key."</userApiKey>
<params>
<tovar_id>3481</tovar_id>
<sku>3481</sku>
</params>
</request>
tovar_id — ID товара в нашей системе (int(11))
sku — Артикул товара заданный партнером (varchar(20))
Вы можете использовать поиск товара по tovar_id или по sku
Если вы хотите получить полный список всех товаров пользователя, не передавайте эти элементы.
Ответ сервера:
<?xml version="1.0" encoding="utf-8"?>
<response>
<method>get_stok</method>
<status>200</status>
<items>
<item>
<id>3481</id>
<sku_from_owner>724461</sku_from_owner>
<name>Название тестового товара</name>
<price>100</price>
<quanity>2</quanity>
<stok>
<pvz quanity="1" pvz_id="33">Ломоносовская</pvz>
<pvz quanity="1" pvz_id="32">Ладожская</pvz>
</stok>
</item>
...
<item>
...
</item>
</items>
</response>
status — статуса ответа
method — метод обращения к API
Успешный ответ содержит элемент items который в свою очередь может содержать некоторое количество элементов item с информацией о товарах.
id — уникальный ID товара в нашей системе
sku_from_owner — внутренний SKU товара присвоенный магазином
name — наименование товара
price — цена товара в рублях
quanity — общее количество товара в различных пунктах выдачи
stok — наличие товара в разных пунктах выдачи
pvz — наличие товара в отдельном пункте выдачи, количество передается в атрибуте quanity, уникальный ID пункта выдачи в атрибуте pvz_id
Добавление заказа.
<?xml version="1.0" encoding="utf-8"?>
<request>
<method>zakaz_add</method>
<userId>".$user_id."</userId>
<userApiKey>".$user_api_key."</userApiKey>
<params>
<uid>724461</uid>
<zakaz_type>2</zakaz_type>
<zakaz_usluga>1</zakaz_usluga>
<start_pvz>33</start_pvz>
<finish_pvz>33</finish_pvz>
<finish_msk_pvz></finish_msk_pvz>
<name>Фамилия Имя Отчество</name>
<phone>+7 (777) 777-77-77</phone>
<payment_type>1</payment_type>
<fee_amount_needed>100.50</fee_amount_needed>
<insurance_amount></insurance_amount>
<packing></packing>
<weight></weight>
<need_sms>1</need_sms>
<need_call>0</need_call>
<adress>адрес доставки</adress>
<delivery_date></delivery_date>
<time_from></time_from>
<time_to></time_to>
<partial_redemption></partial_redemption>
<comment>комментарий к заказу</comment>
<delivery_fee></delivery_fee>
<items>
<item>
<id>3800</id>
<quanity>1</quanity>
</item>
<item>
<id>3801</id>
<quanity>1</quanity>
</item>
</items>
</params>
</request>
Количество и состав элементов запроса зависит от характеристик создаваемого заказа.
uid — внутренний номер заказа присвоенный магазином (varchar(15))
zakaz_type — тип поступления заказа, цифровое значение из справочника (int(1))
zakaz_usluga — тип услуги, цифровое значение из справочника (int(1))
payment_type — тип оплаты, цифровое значение из справочника (int(1))
start_pvz — ID пункта выдачи поступления заказа (int(11))
finish_pvz — ID пункта выдачи назначения заказа (int(11))
finish_msk_pvz — ID московского пункта выдачи назначения заказа (int(11))
name — ФИО покупателя (varchar(100))
phone — телефон покупателя (varchar(100))
fee_amount_needed — сумма к получению с покупателя в рублях (decimal(9,2))
insurance_amount — оценочная стоимость заказа в рублях (decimal(9,2))
packing — необходимость упаковки товара, (0:своя упаковка, 1:нужна упаковка) (int(1))
weight — общий вес заказа в килограммах (double(6,1))
need_sms — нужно ли смс уведомление по данному заказу (0:нет, 1:да) дефолтно 0 (int(1))
need_call — нужно ли телефонное уведомление по данному заказу (0:нет, 1:да) дефолтно 0 (int(1))
adress — адрес доставки (varchar(255))
delivery_date — дата предполагаемой доставки, не ранее завтрашней (date)
time_from — время доставки с XX часов (int(2))
time_to — время доставки до XX часов (int(2))
comment — комментарий к заказу (varchar(255))
Некоторые элементы обрабатываются только для заказов собираемых со склада (zakaz_type=2):
partial_redemption — возможен ли частичный выкуп (0:нет, 1:да) дефолтно 0 (int(1))
delivery_fee — стоимость доставки, учитывается в итоговой стоимости заказов собранных со склада (decimal(9,2))
items может содержать некоторое количество элементов item с информацией о товаре который необходимо добавить к заказу
id — уникальный ID добавляемого товара в нашей системе (int(11))
quanity — количество товара (int(5))
«Заказ со склада» можно выдать только в том ПВЗ где он собирался (start_pvz=finish_pvz).
Добавляемые товары должны быть в наличии в необходимом количестве на пункте выдачи start_pvz.
Ответ сервера:
<?xml version="1.0" encoding="utf-8"?>
<response>
<method>zakaz_add</method>
<status>200</status>
<zakaz_id>1493</zakaz_id>
<zakaz_uid>724461</zakaz_uid>
<items_added>2</items_added>
</response>
status — статуса ответа
method — метод обращения к API
zakaz_id — уникальный ID заказа в нашей системе, автоматически присваивается при создании
zakaz_uid — внутренний номер заказа присвоенный магазином
items_added — количество добавленных в заказ товаров со склада
Получение статуса заказа.
<?xml version="1.0" encoding="utf-8"?>
<request>
<method>get_barcode</method>
<userId>".$user_id."</userId>
<userApiKey>".$user_api_key."</userApiKey>
<params>
<zakazUid>111</zakazUid>
<zakazId>1169</zakazId>
</params>
</request>
zakazUid — внутренний номер заказа присвоенный магазином (varchar(15))
zakazId — ID заказа в нашей системе (int(11))
В запросе должен быть задан хотя бы один из элементов идентифицирующих заказ. Если заданы оба, приоритет у zakazId.
Ответ сервера может содержать информацию об одном или нескольких заказах:
<?xml version="1.0" encoding="utf-8"?>
<response>
<method>get_zakaz</method>
<status>200</status>
<items>
<item>
<id>1169</id>
<uid>111</uid>
<status>34</status>
<status_text>Заказ закрыт, расчет произведен</status_text>
<type>1</type>
<type_text>Привоз в ПВЗ</type_text>
<usluga>1</usluga>
<usluga_text>Выдача в СПб</usluga_text>
<start_pvz>32</start_pvz>
<finish_pvz>32</finish_pvz>
<payment_type>1</payment_type>
<fee_amount_needed>1000.00</fee_amount_needed>
<fee_amount_received>0.00</fee_amount_received>
<insurance_amount>0.00</insurance_amount>
<commission_amount>0.00</commission_amount>
<delivery_date>0000-00-00</delivery_date>
<time_from>10</time_from>
<time_to>18</time_to>
<name>тест</name>
<phone>+7 (777) 777-77-77</phone>
<adress></adress>
<packing>0</packing>
<weight>0.0</weight>
<comment></comment>
<fault_comment></fault_comment>
<issue_comment></issue_comment>
<partial_redemption>0</partial_redemption>
<need_sms>0</need_sms>
<sms_status>0</sms_status>
<need_call>0</need_call>
<call_status>0</call_status>
<free_storage_days>20</free_storage_days>
<autocancel>0</autocancel>
<cancel>1</cancel>
<tracking></tracking>
<calc_date>2016-12-16 23:11:12</calc_date>
<issue_date>0000-00-00 00:00:00</issue_date>
<received_date>2016-12-16 19:33:00</received_date>
<cancel_date>2016-12-16 19:33:27</cancel_date>
<add_date>2016-12-16 19:32:29</add_date>
</item>
...
<item>
...
</item>
</items>
</response>
Количество и состав элементов ответа зависит от характеристик заказа.
status — статуса ответа
method — метод обращения к API
items может содержать некоторое количество элементов item с информацией о заказах
id — ID заказа в нашей системе
uid — внутренний номер заказа присвоенный магазином
status_id — ID статуса заказа, цифровое значение из справочника (Статусы заказа)
status_text — статус заказа
type — тип поступления заказа, цифровое значение из справочника
type_text — тип поступления заказа
usluga — тип услуги, цифровое значение из справочника
usluga_text — тип услуги
start_pvz — ID пункта выдачи поступления заказа
finish_pvz — ID пункта выдачи назначения заказа
ppvz_id — ID партнерской сети
payment_type — тип оплаты, цифровое значение из справочника
fee_amount_needed — сумма к получению с покупателя в рублях
fee_amount_received — сумма фактически полученная с клиента в рублях
insurance_amount — оценочная стоимость заказа в рублях
commission_amount — сумма комиссии в рублях
delivery_date — дата предполагаемой доставки
time_from — время доставки с XX часов
time_to — время доставки до XX часов
name — ФИО покупателя
phone — телефон покупателя
adress — адрес доставки
packing — необходимость упаковки товара
weight — общий вес заказа в килограммах
comment — комментарий к заказу
fault_comment — комментарий по отказу или частичному возврату
issue_comment — комментарий к выдаче
partial_redemption — возможен ли частичный выкуп
need_sms — нужно ли смс уведомление по данному заказу
sms_status — статус sms сообщения
need_call — нужно ли телефонное уведомление по данному заказу
call_status — статус телефонного уведомления
free_storage_days — количество дней бесплатного хранения заказа
autocancel — автоматическая отмена заказа после окончания бесплатного срока хранения
cancel — отменен ли заказ
tracking — номер почтового отправления
calc_date — дата расчета вознаграждения
issue_date — дата выдачи заказа
received_date — дата поступления заказа в пункт выдачи
cancel_date — дата отмены заказа
add_date — дата создания заказа в нашей системе
Получение этикеток со штрих-кодами для заказов.
<?xml version="1.0" encoding="utf-8"?>
<request>
<method>get_barcode</method>
<userId>".$user_id."</userId>
<userApiKey>".$user_api_key."</userApiKey>
<params>
<items>
<item>1452</item>
<item>1451</item>
<item>1433</item>
</items>
</params>
</request>
items может содержать некоторое количество элементов item с номерами заказов
Ответ сервера содержит PDF-документ с одной или несколькими этикетками для наклеивания на упаковку заказа.
Отмена заказа.
<?xml version="1.0" encoding="utf-8"?>
<request>
<method>zakaz_del</method>
<userId>".$user_id."</userId>
<userApiKey>".$user_api_key."</userApiKey>
<params>
<zakaz_id>1452</zakaz_id>
</params>
</request>
zakaz_id должен содержать номер заказа
Заказы можно отменить только до их сборки или привоза на пункт выдачи.
Ответ сервера:
<?xml version="1.0" encoding="utf-8"?>
<response>
<method>zakaz_del</method>
<status>200</status>
<zakaz_id>1493</zakaz_id>
<result>deleted</result>
</response>
При прохождение различных этапов возможны следующие статусы заказов:
10 => "Ожидается привоз",
11 => "Ожидается сборка",
21 => "Ожидается транспортировка",
22 => "Транспортировка",
23 => "Ожидается транспортировка в МСК",
31 => "Готов к выдаче",
32 => "Выдан, ожидает расчета",
33 => "Частично выдан, ожидает расчета",
34 => "Заказ закрыт, расчет произведен",
42 => "Невостребован, ожидает возврат на склад",
43 => "Возвращен на склад, ожидает расчета",
51 => "Невостребован, возврат партнеру, ожидает транспортировки",
52 => "Невостребован, ожидает возврат партнеру",
54 => "Возвращен партнеру, ожидает расчета",
60 => "Ожидает доставку",
61 => "Передан курьеру для доставки",
62 => "Вручен курьером, ожидает расчета",
63 => "Частично вручен курьером, ожидает расчета",
81 => "Доставка EMS",
85 => "Доставлен, ожидает расчета",
99 => "Утерян при транспортировке"
1.0 в добрый путь!
1.1 обновлен метод get_stok
1.2 добавлен метод get_barcode
1.3 добавлен метод zakaz_del