API

Протокол обмена

API-сервер доступен по адресу http://api.glavdostavka.ru

Структура запроса

Структура ответа

Поле "error"

Если error.code = 0, то запрос завершился без ошибок.

Поле "result"

Структура поля result зависит от вызова. Все вызовы, кроме тестовых, возвращают в данном поле массив. Если в методе возникла обрабатываемая ошибка, массив result будет содержать поле error с текстом ошибки.

Список методом вместе с описанием параметров и структуры ответа приведён далее в документе.

Токен клиента

Все закрытые методы требуют авторизации клиента. Авторизация реализована через токен, который представляет из себя составную строку следующего вида:

user_id/user_hash

где user_id — идентификатор пользователя, а user_hash — это авторизационный хэш, который хранится в настройках клиента. Пример токена: '75743/433ca3e5068add011dcbf60dfbca84bb'

Токен должен передаваться в параметре auth, который добавляется к url-запросу (см. пример).

На период тестирования авторизационный токен выдаётся по запросу клиента. В дальнейшем информация о токене будет доступна в ЛК клиента.

Пример вызова

<?php
	$API_URL = 'http://api.glavdostavka.ru';
	$API_KEY = '75743/433ca3e5068add011dcbf60dfbca84bb'; // пример ключа (подставить свой!)

	$api_method = '/service/extra/';
	$get_params = [
		'id'      => uniqid(mt_rand(), true),
		'auth'    => $API_KEY,
		];
	$post_params = [];

	$url = $API_URL.$api_method;
	$url.= '?'.http_build_query($get_params);
	if (!empty($post_params))
		$post_params = http_build_query($post_params);

	$ch = curl_init();
	curl_setopt($ch, CURLOPT_URL, $url);
	curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
	curl_setopt($ch, CURLOPT_POST, true);
	curl_setopt($ch, CURLOPT_POSTFIELDS, $post_params);

	$response = curl_exec($ch);
	if ($response === false)
		throw new Exception(sprintf('Api connect error: "%s"', curl_error($ch)), 500);

	curl_close($ch);

	$response = json_decode($response, true);
	var_dump($response);

Открытые методы API

Список складов

Параметры

Чтобы получить склады по конкретному городу, укажите один из параметров — city_id или fias_id. Не передавайте сразу оба параметра.

Ответ

Массив складов, структура элементов представлена ниже.

Список городов, в которые и из которых возможна перевозка

Ответ

Массив городов, структура элементов представлена ниже.

Информация о накладной по номеру

Параметры

Ответ

Поле history

Содержит массив с историей статусов, отсортированный по времени. Структура каждого элемента описана ниже.

Закрытые методы API

Список дополнительных услуг

Параметры

-

Ответ

Массив дополнительных услуг, структура элементов представлена ниже.

Список городов

Параметры

Ответ

Массив населённых пунктов, структура элементов представлена ниже.

Список городов, из которых возможна перевозка

Параметры

Ответ

Массив городов в которые возможна перевозка, структура элементов представлена ниже.

Список городов, в которые возможна перевозка

Параметры

Ответ

Массив городов из которых возможна перевозка, структура элементов представлена ниже.

Список возможных статусов накладных

Параметры

-

Ответ

Массив статусов, структура элементов представлена ниже.

Дата прибытия и доставки

Параметры

Ответ

Информация о накладной по ID

Параметры

Ответ

Поле services

Содержит массив со списком услуг

Поле history

Содержит массив с историей статусов, отсортированный по времени. Структура каждого элемента описана ниже.

Поле documents

Содержит массив документов по накладной. Структура каждого элемента описана ниже.

Список накладных по фильтру

Параметры

Ответ

Массив накладных

Структура каждого элемента аналогична структуре ответа /order/{order_id}/.

Загрузка документа накладной

Параметры

Ответ

Запрошенный документ в формате PDF. Ответ выдаётся с заголовками, соответствующими загрузке файла.

Загрузка по типу документа накладной

Параметры

Ответ

Запрошенный документ в формате PDF. Ответ выдаётся с заголовками, соответствующими загрузке файла.

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

Параметры

Ответ

Загрузка консолидированной экспедиторской расписки

Параметры

Ответ

Запрошенный документ в формате PDF. Ответ выдаётся с заголовками, соответствующими загрузке файла.

Просчёт накладной

Параметры

Ответ

Создание новой накладной

Параметры

Если город отправления(from_city_id) и город назначения(to_city_id) привязаны к одному филиалу и указаны адрес забора (from_address) и адрес доставки (to_address), то будет создана накладная с типом "Доставка грузов по городу и области". Груз поедет одним днём, этот день можно указать в одном из параметров: delivery_date / pickup_date. Примечание: при данных условиях нельзя одновременно указывать разные delivery_date и pickup_date — накладная не будет создана!

Если город отправления (from_city_id) и город назначения (to_city_id) привязаны к одному филиалу, не указан адрес забора (т. е. будет самоподвоз на склад) и указан адрес доставки, будет создана накладная с типом "Доставка сборных грузов" с доставкой и выездами за пределы города без стоимости перевозки.

При добавлении доп. услуги для забора или доставки (например, погрузо-разгрузочных работ) необходимо указывать родительскую услугу в поле parent_service — забор ('pickup') или доставку ('delivery'). Чтобы заказать услугу и для забора, и для доставки, добавьте её дважды с разными parent_service. Пример:

{
    ...
    pickup_date: '2019-02-01',
    delivery_date: '2019-02-10',
    service: [
        {
            service_id: 8994057,
            note: 'Упаковка стреппинг лентой'
        },
        {
            service_id: 528,
            parent_service: 'pickup',
            note: 'ПРР для забора груза'
        },
        {
            service_id: 528,
            parent_service: 'delivery',
            note: 'ПРР для доставки груза'
        }
    ],
    ...
}

Обратите внимание, что если в накладной нет забора, то и добавить услугу для забора нельзя (вернётся ошибка, накладная не будет создана). Аналогично для доставки.

Ниже приведен код с несколькими примерами накладных.

<?php
	$API_URL = 'http://api.glavdostavka.ru';
	$API_KEY = '75743/433ca3e5068add011dcbf60dfbca84bb'; // пример ключа (подставить свой!)

	$api_method = '/service/extra/';
	$get_params = [
		'id'      => uniqid(mt_rand(), true),
		'auth'    => $API_KEY,
	];

	/*
		1. Пример с минимальным количеством параметров. Накладная Москва-Петербург без автоэкспедирования.
	*/
	$post_params = [
	   'from_client' => 'Имя клиента отправителя',
	   'to_client' => 'Имя клиента получателя',
	   'from_city_id' => 35,
	   'to_city_id' => 36,
	   'cargo' => [
		  0 => [
			 'amount' => 2,
			 'weight' => 100,
			 'length' => 2,
			 'width' => 1,
			 'height' => 3
		  ]
	   ]
	];

	/*
		2. Пример с автоэкспедированием.
	*/
	$post_params = [
	   'from_client' => 'Имя клиента отправителя',
	   'to_client' => 'Имя клиента получателя',
	   'from_city_id' => 35,
	   'to_city_id' => 36,
	   'cargo' => [
		  0 => [
			 'amount' => 2,
			 'weight' => 100,
			 'length' => 2,
			 'width' => 1,
			 'height' => 3
		  ]
	   ],
	   'pickup_date' => '2019-01-30',
	   'delivery_date' => '2019-01-31',
	   'cargo_max' => [
		  'length' => 2,
		  'width' => 1,
		  'height' => 3
	   ]
	];

	/*
		3. Пример с грузом или несколькими грузами.
		Параметр amount в cargo задаёт количество грузов. Если при этом указан флаг one_place = false,
		то вне зависимости от количества создастся одно место в накладной, и габариты, указанные в
		параметрах cargo, применятся к этому месту. Если же one_place = true, то создастся столько мест,
		сколько указано в amount, и каждому месту применятся габариты, указанные в cargo.
	*/
	$post_params = [
	   'from_client' => 'Имя клиента отправителя',
	   'to_client' => 'Имя клиента получателя',
	   'from_city_id' => 35,
	   'to_city_id' => 36,
	   'cargo' => [
		  0 => [
			 'amount' => 2,
			 'weight' => 100,
			 'length' => 2,
			 'width' => 1,
			 'height' => 3,
			 'one_place' => false // 1 место с габаритами 2,1,3
		  ],
		  1 => [
			 'amount' => 2,
			 'weight' => 100,
			 'length' => 2,
			 'width' => 1,
			 'height' => 3,
			 'one_place' => true // 2 места с габаритами 2,1,3
		  ]
	   ]
	];

	/*
		4. Также можно задать клиентский номер накладной, для последующего его использования.
	*/
	$post_params = [
	   'from_client' => 'Имя клиента отправителя',
	   'to_client' => 'Имя клиента получателя',
	   'from_city_id' => 35,
	   'to_city_id' => 36,
	   'client_order_num' => 'Мск-Спб/123.456', // Номер накладной согласно базе клиента
	   'cargo' => [
		  0 => [
			 'amount' => 2,
			 'weight' => 100,
			 'length' => 2,
			 'width' => 1,
			 'height' => 3
		  ]
	   ]
	];

	$url = $API_URL . $api_method;
	$url .= '?' . http_build_query($get_params);
	if (!empty($post_params))
		$post_params = http_build_query($post_params);

	$ch = curl_init();
	curl_setopt($ch, CURLOPT_URL, $url);
	curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
	curl_setopt($ch, CURLOPT_POST, true);
	curl_setopt($ch, CURLOPT_POSTFIELDS, $post_params);

	$response = curl_exec($ch);
	if ($response === false)
		throw new Exception(sprintf('Api connect error: "%s"', curl_error($ch)), 500);

	curl_close($ch);

	$response = json_decode($response, true);
	var_dump($response);

Ответ

Дополнительные примеры

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

<?php
	$API_URL = 'http://api.glavdostavka.ru';
	$API_KEY = '75743/433ca3e5068add011dcbf60dfbca84bb'; // пример ключа (подставить свой!)

	/*
	* Метод получения складов
	*/
	$api_method = '/service/storehouse/';
	/*
	* Ответ
	*/
	array (size=3)
	  'id' => string '17444090375d3aecb715a0a9.05181050' (length=33)
	  'error' =>
		array (size=2)
		  'code' => int 0
		  'message' => string '' (length=0)
	  'result' =>
		array (size=139)
		  0 =>
			array (size=11)
			  'storehouse_id' => int 23446742
			  'title' => string 'Офис и склад' (length=22)
			  'address' => string 'г Петропавловск-Камчатский, ул Тундровая 1/2' (length=79)
			  'phone' => string '+7 (415) 234-32-25' (length=18)
			  'email' => string '[email protected]' (length=24)
			  'latitude' => string '53.0437700' (length=10)
			  'longitude' => string '158.6632930' (length=11)
			  'city_id' => int 635
			  'city_title' => string 'Петропавловск-Камчатский' (length=47)
			  'take_in' => boolean true
			  'give_out' => boolean true
	...


	/*
	* Метод получения городов перевозок
	*/
	$api_method = '/service/shipping_city/';
	/*
	* Ответ
	*/
	array (size=3)
	  'id' => string '6447451445d3aed68080d73.29672152' (length=32)
	  'error' =>
		array (size=2)
		  'code' => int 0
		  'message' => string '' (length=0)
	  'result' =>
		array (size=1)
		  'cities' =>
			array (size=143)
			  35 =>
				array (size=5)
				  'city_id' => int 35
				  'title' => string 'Москва г' (length=15)
				  'fullname' => string 'г Москва' (length=15)
				  'kladr_id' => string '7700000000000' (length=13)
				  'fias_id' => string '0c5b2444-70a0-4932-980c-b4dc0d3f02b5' (length=36)
	...

	$get_params = [
		'id'      => uniqid(mt_rand(), true),
		'auth'    => $API_KEY,
	];



	$ch = curl_init();
	curl_setopt($ch, CURLOPT_URL, $url);
	curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
	curl_setopt($ch, CURLOPT_POST, true);
	curl_setopt($ch, CURLOPT_POSTFIELDS, $post_params);

	$response = curl_exec($ch);
	if ($response === false)
		throw new Exception(sprintf('Api connect error: "%s"', curl_error($ch)), 500);

	curl_close($ch);

	$response = json_decode($response, true);
	var_dump($response);

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

<?php
	$API_URL = 'http://api.glavdostavka.ru';
	$API_KEY = '75743/433ca3e5068add011dcbf60dfbca84bb'; // пример ключа (подставить свой!)

	$api_method = '/service/calc/';
	$get_params = [
		'id'      => uniqid(mt_rand(), true),
		'auth'    => $API_KEY,
	];

	/*
		1. Пример параметров просчёта накладной
	*/
	$post_params = [
	   'payer' => 'from_client',
	   'from_client' => 'Тестов Тест 1',
	   'from_city_id' => 21098012,
	   'from_name' => 'Тестов Тест',
	   'from_address' => 'Московская обл, Селятино рп, д. 15',
	   'to_client' => 'Тестов Тест 2',
	   'to_city_id' => 36,
	   'to_name' => 'Тестов Тест',
	   'to_address' => 'Санкт-Петербург, ул Писарева, д 29А',
	   'cargo' => [
		  [
			 'amount' => 1,
			 'weight' => 100,
			 'length' => 1,
			 'width' => 1,
			 'height' => 1,
			 'one_place' => false,
		  ],
	   ],
	   'cargo_max' => [
		  'length' => 5,
		  'width' => 2.5,
		  'height' => 2.7,
	   ],
	   'report_date' => '2019-07-10 0:0:0',
	   'pickup_date' => '2019-08-10',
	];
	$url = $API_URL . $api_method;
	$url .= '?' . http_build_query($get_params);
	if (!empty($post_params))
		$post_params = http_build_query($post_params);

	$ch = curl_init();
	curl_setopt($ch, CURLOPT_URL, $url);
	curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
	curl_setopt($ch, CURLOPT_POST, true);
	curl_setopt($ch, CURLOPT_POSTFIELDS, $post_params);

	$response = curl_exec($ch);
	if ($response === false)
		throw new Exception(sprintf('Api connect error: "%s"', curl_error($ch)), 500);

	curl_close($ch);

	$response = json_decode($response, true);
	var_dump($response);