API – руководство по интеграции

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>



Поддерживаемые методы

get_api_info Получение текущей версии

get_pvz_list Получение списка пунктов выдачи

get_tax Получение размеров комиссии для партнера

tovar_add Создание нового товара

stok_add Добавление товара на склад

get_stok Получение списка товара и наличие его на складе

zakaz_add Добавление заказа

get_zakaz Получение статуса заказа

get_barcode Получение этикеток со штрих-кодами для заказов

zakaz_del Отмена заказа




Метод get_api_info

Получение текущей версии 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




Метод get_pvz_list

Получение списка доступных пунктов выдачи.

<?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 — текстовое описание (например, как найти ПВЗ)




Метод get_tax

Получение списка комиссий для партнера.

<?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. Значение может быть в рублях, в процентах, в днях (в зависимости от типа комиссии). Для разных пользователей список может содержать разные типы комиссий.




Метод tovar_add

Создание нового товара.

<?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 товара присвоенный магазином




Метод stok_add

Добавление товара на склад.

<?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 — количество успешно добавленных товаров




Метод get_stok

Получение списка товаров и наличия на складе.

<?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




Метод zakaz_add

Добавление заказа.

<?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))

1 => "Привоз в пвз", 2 => "Заказ со склада"

zakaz_usluga — тип услуги, цифровое значение из справочника (int(1))

1 => "Выдача в СПб", 2 => "Выдача в Мск", 3 => "Доставка по СПб", 4 => "Доставка по Мск", 5 => "Доставка EMS", 6 => "Доставка Почта РФ"

payment_type — тип оплаты, цифровое значение из справочника (int(1))

1 => "наличные", 2 => "карта", 3 => "предоплачен"

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 — количество добавленных в заказ товаров со склада




Метод get_zakaz

Получение статуса заказа.

<?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 — дата создания заказа в нашей системе




Метод get_barcode

Получение этикеток со штрих-кодами для заказов.

<?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-документ с одной или несколькими этикетками для наклеивания на упаковку заказа.




Метод zakaz_del

Отмена заказа.

<?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