Склад "Кунцево" переехал! Новый адрес: Москва, ул. Рябиновая, д. 32. Закрыть
МЕНЮ

API

Оглавление


Описание сервиса

Изменения версий

Ознакомьтесь с предыдущей версией API.

Подключение и авторизация

Для интеграции с компанией "ГлавДоставка" по API необходимо:

  • Заключить договор с компанией "ГлавДоставка"
  • Ознакомиться с последней версией документации, доступной по адресу https://glav-dostavka.ru/api/
  • Сделать запрос для получения тестового доступа на email: api.clients@glavdostavka.ru
  • Осуществить реализацию, настройку и тестирование с помощью полученного тестового доступа
  • Сделать запрос на переключение тестового доступа в режим "production" (или получение дополнительного "production"-доступа)

Взаимодействие с основным функционалом сервиса требует авторизации. Для обращения к открытым методам API авторизация НЕ требуется.

Авторизация на стороне сервиса осуществляется с помощью авторизационного токена (обязательный параметр, который передается в каждом запросе к сервису). Пример токена: '75743/433ca3e5068add011dcbf60dfbca84bb'. Токен должен передаваться в параметре auth, который добавляется к url-запросу (см. пример).

Все остальные параметры передаются в теле запроса.

<?php 
$API_URL = 'http://api.glavdostavka.ru/v2/';

$API_KEY = '75743/433ca3e5068add011dcbf60dfbca84bb'; // пример ключа (подставить свой!) 

$api_method = '/service/cities/'; 
$get_params = [
	'auth' => $API_KEY,
]; 
$post_params = [
	'fiasGuid' => '0c5b2444-70a0-4932-980c-b4dc0d3f02b5',
]; 

$url = $API_URL.$api_method; 
$url.= '?'.http_build_query($get_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_HTTPHEADER, ['Content-Type: application/json']); 
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($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 - 2. Описание в данном документе актуально для этой версии.

API-сервер текущей версии (для всех типов доступов) расположен по адресу https://api.glavdostavka.ru/v2/.

Информационный обмен с сервисом осуществляется с помощью пакетов в формате json.

Запрос к сервису

Любое обращение к сервису осуществляется с помощью POST-запросов.

Передача параметров происходит с помощью json-пакета, в котором содержится набор полей, индивидуальный для каждого метода.

Json-пакет передается непосредственно в теле http-запроса.

{ 
	... // набор полей метода 
}

Ответ от сервиса

Данные от сервиса возвращаются также в формате json (в теле http-ответа).

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

{
	// результат выполнения запроса 
	"result": {
		... // набор объектов и полей, возвращаемых методом
	},
	// одно или несколько предупреждений о некритичных ситуациях, которые возникли в результате выполнения метода
	// при наличии предупреждений вызванный метод отработал до конца 
	"warnings": {[
		{
			"code": (string), // код предупреждения
			"message": (string), // подробное сообщение предупреждения
			"details": {
				"fieldNames": [], // список полей, с которыми связана предупреждение
				"suggest": [] // варианты исправления
			}
		},
		...
	]},
	// одна или несколько ошибок о критичных ситуациях, которые возникли в результате выполнения метода
	// при наличии ошибок работа вызываемого метода была прервана
	"errors": {[
		{
			"code": (string), // код ошибки
			"message": (string), // подробное сообщение об ошибке
			"details": {
				"fieldNames": [], // список полей, с которыми связана ошибка
				"suggest": [] // варианты исправления
			},
		},
		...
	]},
	// мета-информация, относящаяся к результату запроса (пока не используется, зарезервировано)
	"meta": {
		"pagesAmount": (int), // общее количество страниц (для списка объектов)
		"pagesCurrent": (int), // текущая страница (для списка объектов)
		"pagesLimit": (int) // количество объектов на странице (для списка объектов)
	},
	// служебная информация для отладки (используется только на тестовом окружении. Пока не используется, зарезервировано)
	"debug": {
	    ...
	}
}

Базовые типы данных

В протоколе обмена используются следующие простые типы данных:

  • string(n) - текстовая строка, где n - максимальное количество символов
  • int - целочисленное значение
  • float - число с плавающей точкой (в качестве разделителя используется точка)
  • boolean - логическое значение (возможные значения: true или false)
  • datetime - дата и время (в формате ISO 8601:2004 с указанием часового пояса - YYYY-MM-DDThh:mm:ss±hh)
  • date - дата в формате ISO 8601:2004 (YYYY-MM-DD)
  • time - время в формате HH:MM
  • UUID - универсальный уникальный идентификатор, согласно RFC 4122 (например: 123e4567-e89b-12d3-a456-426655440000)

  • CountryCode - код страны в формате ISO 3166-1 alpha2 (например: RU, KZ)
  • CurrencyCode - международный код валюты в формате ISO 4217 (например: RUB, BYN)

Линейные размеры указываются в метрах, объём — в кубических метрах, а вес — в килограммах.

Кроме простых типов данных, используется следующие структуры данных:

Контрагент (Customer)

// организация, выступающая в роли: отправителя, получателя, плательщика
{
	"name": (string255), // название организации
	"countryCode": (CountryCode), // код страны регистрации (пока не используется, зарезервировано)
	"legalType": (enum['COMPANY', 'PERSONAL']), // Правовая форма (юр. лица/ИП - "COMPANY", физ. лица - "PERSONAL") (пока не используется, зарезервировано)
	"tin": (string255), // ИНН (обязательно для юр. лиц/ИП)
	"kpp": (string255), // КПП (обязательно для юр. лиц) (пока не используется, зарезервировано)
	"passport": (Passport), // паспортные данные (для физлиц и ИП) (пока не используется, зарезервировано)
	"phone": (Phone), // основной номер телефона организации (пока не используется, зарезервировано)
	"email": (string255), // адрес электронной почты (пока не используется, зарезервировано)
	"address": (string1024) // юридический адрес организации (пока не используется, зарезервировано)
}

Местоположение (Location)

// Обязательными для заполнения являются:
// - countryCode
// - либо fiasGuid, либо city
// Если указан адрес, он должен находиться в пределах города (населенного пункта)
{
	"countryCode": (CountryCode), // код страны
	"fiasGuid": (UUID), // идентификатор ФИАС
	"city": (string255), // название населённого пункта в формате DaData
	"address": (string255), // адрес
	"latitude": (float),	// широта
	"longitude": (float)	// долгота
}

Контактное лицо (Contact)

{
	"name": (string1024), // ФИО контактного лица
	"phones": (Phone[]), // список телефонов
	"email": (string255) // адрес электронной почты (пока не используется, зарезервировано)
}

Услуга (Service)

{
	"code": (const ServiceCode), // код дополнительной услуги
	"params": (string1024), // дополнительные опции услуги в формате json
	"additional": (string1024) // дополнительная информация
}

Услуга, добавленная в заказ (OrderService)

{
	"code": (const ServiceCode), // код дополнительной услуги
	"name": (string255), // название услуги
	"params": (string1024), // дополнительные опции услуги в формате json
	"sum": (Money) // стоимость услуги
}

Cтоимость услуги/товара (Money)

{
	"currency": (CurrencyCode), // код валюты
	"value": (float) // сумма в указанной валюте
}

Груз (Cargo)

{
	"dimensions": {
		"dimensionsItem": (Dimensions),  // вес и габариты грузоместа
		"amount": (int), // количество грузомест с данными габаритами (необязательно, по-умолчанию - 1). если > 1, то финальное значение габаритов/веса будут вычислены из количества 
	},
	"pack": (const Pack[]), // желаемый тип упаковки
	"itemNumber": (string255), // артикул позиции (только для наложенного платежа)
	"description": (string255), // наименование позиции (только для наложенного платежа)
	"payment": (Money), // сумма оплаты за товар при получении (только для наложенного платежа)
	"additional": (string1024) // дополнительная информация (пока не используется, зарезервировано)
}

Сводная информация о грузе (CargoSummary)

{
	"cargo": (Cargo[]), // список грузомест в заказе
	"totalAmount": (int), // общее количество мест
	"totalVolume": (float) // общий объём
	"totalWeight": (float) // общий вес
	"dimensionsMax": (Dimensions), // габариты и вес максимального места ("Вес максимального места" пока не используется, зарезервировано)
	"type": (string255) // характер груза
},

Весо-габаритные характеристики грузоместа (Dimensions)

{
	"length": (float), // длина
	"width": (float), // ширина
	"height": (float), // высота
	"weight": (float), // вес
}

Информация к заказу от клиента (OrderClientInfo)

{
	"orderNumber": (string255), // номер заказа из клиентской системы
	"tn": (string255), // номер товарной накладной
	"ttn": (string255), // номер товарно-транспортной накладной
	"trn": (string255), // номер транспортной накладной
	"sf": (string255), // номер счет-фактуры
	"additional": (string1024) // доп. информация для отображения в экспедиторской расписке
}

Телефон (Phone)

{ 
	"number": (string255), // номер телефона в международном формате
	"additional": (string255) // дополнительная информация (добавочный номер, время работы)
}

Паспорт (Passport)

// пока не используется, зарезервировано
{
	"countryCode": (CountryCode), // код страны выдачи
	"series": (string255), // серия
	"number": (string255), // номер
	"dateIssue": (date), // дата выдачи
	"organization": (string255), // орган выдачи
	"dateBirth": (date) // дата рождения
}

Константы

Коды дополнительных услуг, доступных для оформления (ServiceCode), опции (ServiceParams)

// Забор груза
PICKUP
params: {
	"date": (date), // дата забора
	"interval": { // желаемый интервал времени забора (доступные варианты: 10:00..16:00, 16:00..22:00, 10:00..22:00)
		"start": (time),
		"end": (time)
	},
	"person": (Contact) // контакты исполнителя услуги
}

// Доставка
DELIVERY
params: {
	"date": (date), // дата доставки
	"interval": { // желаемый интервал времени доставки (доступные варианты: 10:00..16:00, 16:00..22:00, 10:00..22:00)
		"start": (time),
		"end": (time)
	},
	"person": (Contact) // контакты исполнителя услуги
}

// Авизация (пока не используется, зарезервировано)
AVISO
params: {
	"service": enum('PICKUP', 'DELIVERY'), // код родительской услуги, обязательно (для 'PICKUP' пока не используется, зарезервировано)
	"time": (time) // время авизации, если не указано, то в течении дня 
}

// ПРР
UNLOAD
params: {
	"service": enum('PICKUP', 'DELIVERY'), // код родительской услуги
	"elevator": (boolean), // наличие грузового лифта (пока не используется, зарезервировано)
	"floor": (int) // подъем на этаж (по умолчанию 1)
}

// Растентовка
TENT-OPEN
params: {
	"service": enum('PICKUP', 'DELIVERY'), // код родительской услуги
	"side": enum('back', 'top', 'side') // тип растентовки (пока не используется, зарезервировано)
}

// Страхование груза
INSURANCE-CARGO
params: {
    "appraiseValue": (Money), // страховая сумма 
    "rate": (float), // страховой тариф
    "carrierInsurance": (bool), // страховка оплачивается перевозчиком true, оплачивается клиентом false
    "contractNumber": (string255), // номер договора страхования или акцептованного заявления
    "status": (enum('PENDING', 'CHANGED', 'DELETED', 'PROCESSING', 'ACCEPTED', 'REJECTED', 'CORRECTED')) // статус заявления
}

// Страхование опозданий
INSURANCE-DELAYS
params: {
	"limitValue": (Money), // лимит страхования
    "rate": (float), // страховой тариф (пока не используется, зарезервировано)
    "contractNumber": (string255), // номер договора страхования или акцептованного заявления
    "status": (enum('PENDING', 'CHANGED', 'DELETED', 'PROCESSING', 'ACCEPTED', 'REJECTED', 'CORRECTED')) // статус заявления
}

// Страхование штрафов
INSURANCE-PENALTIES
params: {
	"limitValue": (Money), // лимит страхования
    "rate": (float), // страховой тариф (пока не используется, зарезервировано)
    "contractNumber": (string255), // номер договора страхования или акцептованного заявления
    "status": (enum('PENDING', 'CHANGED', 'DELETED', 'PROCESSING', 'ACCEPTED', 'REJECTED', 'CORRECTED')) // статус заявления
}

// Оформление сопроводительных документов на международную перевозку
CMR
params: {}

// Возврат документов
RETURN-DOC
params: {
	"amount": (int) // количество копий документов (по умолчанию 1)
}

// Медкнижка
MEDICAL-CARD
params: {
	"service": enum('PICKUP', 'SHIPPING', 'DELIVERY'), // код родительской услуги
}

Виды упаковки (Pack)

// ЖУ - жёсткая упаковка (обрешётка груза) изготавливается из досок и гвоздей по точным размерам груза. Обязательна для хрупких, бьющихся и нестандартных грузов.
HARD

// Паллетный борт (Евро-тара) состоит из евро-паллета, деревянных бортов и крышки. Защищает груз от повреждений лучше, чем жёсткая упаковка. 
// Возможно заказать для грузов, габариты (ДхШхВ) которых не превышают 1,15 х 0,75 х 2 м. Услуга предоставляется не для всех городов.
PALLET


// HARD и PALLET взаимоисключают друг друга, можно выбрать только что-то одно.


// Воздушно-пузырьковая плёнка. Сохраняет груз от механических повреждений, царапин и влаги, придавая ему дополнительную амортизацию.
AIR-BUBBLE-FILM


// Упаковка стрейч-пленкой. Стрейч-плёнка фиксирует груз, состоящий из нескольких предметов. Сохраняет внешний вид груза во время транспортировки.
STRETCH-FILM


// Черный стрейч
BLACK-STRETCH-FILM


// Стреппинг лента. Стягивает и фиксирует между собой различные грузы, такие как коробки, металлоконструкции, трубы, профиля.
STREPPING-TYPE


// Картонная коробка. Имеет откидную крышку и отверстия-ручки для переноски.
// Вместительная, прочная и лёгкая коробка — отличный выбор для перевозки личных вещей, товаров и материалов.
// Размеры коробки — 480*325*295 мм.
CARDBOARD-BOX

// Мешок с пломбой маленький
// Полипропиленовый мешок с пломбой подходит для ценных грузов с повреждённой упаковкой или без собственной упаковки.
SEALED-BAG-SM

// Мешок с пломбой большой
SEALED-BAG-LG

// Сейф-пакет. Исключает негласный доступ к пересылаемой корреспонденции. Любая попытка проникновения к документам приводит к повреждениям пакета и легко обнаруживается.
SAFE-PACK

// Паллета до 1 м
PALLETIZING-1M

// Паллета до 2 м
PALLETIZING-2M

// Рёбра жесткости
STIFFENING-RIB

Коды статусов заказа (OrderStatus)

// ЧЕРНОВИК
DRAFT

// НАКЛАДНАЯ ОФОРМЛЕНА
NEW

// ЗАБОР ЗАПЛАНИРОВАН
PICKUP-PLAN

// ГРУЗ ЗАБРАН
PICKUP-DONE

// НАС СКЛАДЕ ОТПРАВЛЕНИЯ
STOREHOUSE-FROM

// В ПУТИ
ON-WAY

// НА СКЛАДЕ НАЗНАЧЕНИЯ
STOREHOUSE-TO

// ДОСТАВКА ЗАПЛАНИРОВАНА
DELIVERY-PLAN

// ВЫДАНО НА ДОСТАВКУ
DELIVERY-START

// ГРУЗ ДОСТАВЛЕН
DELIVERY-DONE

// ГРУЗ ВЫДАН
DONE

Типы документов (DocumentType)

// Заявка
REQUEST

// Опись
INVENTORY

// Международная товарно-транспортная накладная
CMR

// Накладная на выдачу
GIVEOUT

// Накладная на выдачу (с суммой по счету)
GIVEOUT-SUM

// Этикетка
CARGO-LABEL

// Талон на приёмку
ACCEPTANCE-TICKET

// Накладная на выдачу
WAYBILL

Типы возвращаемых ошибок и предупреждений

// Ошибка авторизации
ERR-AUTH

// Некорректный формат запроса
ERR-REQUEST-INCORRECT

// Отсутствует обязательное поле
ERR-FIELD-NEED

// Некорректный формат поля
ERR-FIELD-INCORRECT-DATA

// Конфликт заполненных полей
ERR-FIELD-CONFLICT

// Сервис временно недоступен
ERR-SERVICE-UNAVAILABLE

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

Список городов-филиалов

URL: /service/cities/

Параметры:

{
	"countryCode": (CountryCode), // код страны
	"fiasGuid": (UUID), // идентификатор ФИАС (только для городов России)
	"letter": (string255) // подстрока (1+ символов), с которой начинается название города
}

Ответ:

{
	(Location[])
}

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

URL: /service/storehouses/

Параметры:

{
	"fiasGuid": (UUID), // идентификатор ФИАС (только для городов России)
	"city": (string255) // название населённого пункта в формате DaData
}

Ответ:

{
	[
		{
			"uuid": (UUID), // идентификатор склада
			"title": (string255), // наименование склада
			"location": (Location), // метоположение, адрес
			"contact": (Contact), // контактные данные
			"operations": {'TAKEIN', 'GIVEOUT'} // операции (приемка, выдача)
		},
		...
	]
}

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

Просчет заказа

URL: /order/calc/

Параметры:

{
	"type": enum('standard', 'courier', 'city-province'), // тип заказа (стандартная перевозка, интернет-магазин, город и область)
	"payer": enum('sender', 'recipient', 'third'), // организация, выступающая в роли плательщика заказа (third не используется, зарезервировано). если поле не заполнено, в роли плательщика будет выступать владелец токена
	"sender": { // отправитель, обязательное
		"customer": (Customer), // обязательное name
		"contact": (Contact)
	},
	"recipient": { // получатель, обязательное поле
		"customer": (Customer), // обязательное name
		"contact": (Contact)
	},
	"third": { // организация - третье лицо (пока не используется, зарезервировано)
		"customer": (Customer),
		"contact": (Contact)
	},
	"locationFrom": (Location), // адрес отправления. Обязательное city/fiasGuid и address
	"locationTo": (Location), // адрес получения. Обязательное city/fiasGuid и address
	"storehouseFrom": { // пункт приема заказа
		"uuid": (UUID), // идентификатор
		"date": (date) // дата самоподвоза
	},
	"storehouseTo": { // пункт выдачи заказа
		"uuid": (UUID), // идентификатор
		"date": (date) // дата самовывоза (пока не используется, зарезервировано)
	},
	"services": (Service[]), // список дополнительных услуг
	"cargo": (Cargo[]),  // описание груза, обязательное dimensions
	"cargoType": (string255), // характер груза
	"dimensionsMax": (Dimensions) // габариты максимального места, обязательное (максимальный вес одного места пока не используется, зарезервировано)
}

Ответ:

{
	"order": {
		"services": (OrderService[]), // список дополнительных услуг
		"estimateDates": {
			"storehouseTo": (datetime), // дата прибытия на склад назначения
			"pickup": (datetime), // минимально возможная дата и время забора груза (если указана услуга забора)
			"delivery": (datetime) // минимально возможная дата и время доставки груза (если указана услуга доставки)
		},
		"sum": (Money) // общая сумма заказа
	}
}

Создание заказа

URL: /order/create/

Параметры:

{
	"type": enum('standard', 'courier', 'city-province'), // тип заказа (стандартная перевозка, интернет-магазин, город и область)
	"payer": enum('sender', 'recipient', 'third'), // организация, выступающая в роли плательщика заказа (third не используется, зарезервировано). если поле не заполнено, в роли плательщика будет выступать владелец токена
	"sender": { // грузоотправитель обязательное
		"customer": (Customer), // обязательное name
		"contact": (Contact) // обязательное
	},
	"recipient": { // получатель обязательное
		"customer": (Customer), // обязательное name
		"contact": (Contact) // обязательное
	},
	"third": { // организация - третье лицо (пока не используется, временно зарезервировано)
		"customer": (Customer),
		"contact": (Contact)
	},
	"clientInfo": (OrderClientInfo), // информация от клиента
	"locationFrom": (Location), // адрес отправления. Обязательное city/fiasGuid и address
	"locationTo": (Location), // адрес получения. Обязательное city/fiasGuid и address
	"storehouseFrom": { // пункт приема заказа
		"uuid": (UUID), // идентификатор
		"date": (date) // дата самоподвоза 
	},
	"storehouseTo": { // пункт выдачи заказа
		"uuid": (UUID), // идентификатор
		"date": (date) // дата самовывоза (пока не используется, зарезервировано)
	},
	"services": (Service[]), // список дополнительных услуг
	"cargo": (Cargo[]),  // описание груза, обязательное dimensions
	"cargoType": (string255), // характер груза
	"openAllowed": (boolean), // запрет/разрешение на вскрытие перед выдачей (только для наложенного платежа)
	"deliveryPayment": (Money), // стоимость доставки (только для наложенного платежа)
	"dimensionsMax": (Dimensions) // габариты максимального места, обязательное (максимальный вес одного места пока не используется, зарезервировано)
}

Ответ:

{
	"uuid": (UUID), // номер заказа (для информации о заказе)
	"title": (string255), // внутренний номер заказа
	"clientInfo": (OrderClientInfo), // информация от клиента
	"services": (OrderService[]), // список дополнительных услуг
	"cargoSummary": (CargoSummary), // сводная информация о грузе
	"sum": (Money), // общая сумма заказа
	"createdAt": (datetime) // дата/время создания заказа
}

Информация о заказе

URL: /order/info/

Параметры:

// Одно поле должно быть заполнено обязательно. Одновременное использование полей недопустимо
{
	"uuid": (UUID), // уникальный идентификатор заказа
	"title": (string255) // внутренний номер заказа
}

Ответ:

{
	"uuid": (UUID), // номер заказа (для информации о заказе)
	"title": (string255), // внутренний номер заказа
	"type": enum('standard', 'courier', 'city-province'), // тип заказа (стандартная перевозка, интернет-магазин, город и область)
	"status": (OrderStatus), // текущий статус заказа
	"clientInfo": (OrderClientInfo), // информация от клиента
	"locationFrom": (Location), // адрес отправления
	"locationTo": (Location), // адрес получения
	"storehouseFrom": { // пункт приема заказа
		"uuid": (UUID), // идентификатор
		"date": (date) // дата самоподвоза
	},
	"storehouseTo": { // пункт выдачи заказа
		"uuid": (UUID), // идентификатор
		"estimatedDate": (datetime), // дата прибытия на склад назначения (после приёма заказа на склад отправления)
		"date": (date) // дата самовывоза (пока не используется, зарезервировано)
	},
	"services": (OrderService[]), // список дополнительных услуг
	"cargoSummary": (CargoSummary), // сводная информация о грузе
	"sum": (Money), // общая сумма заказа
	"history": [ // история изменений заказа
		{
			"status": (OrderStatus), // статус заказа
			"updatedAt": (datetime) // дата/время перехода заказа в данный статус
		},
		...
	], 
	"linkedOrders": [ // список заказов, связанных с текущим (дооформленные услуги, возвраты и т.д.)
		{
			"uuid": (UUID), // номер заказа (для информации о заказе)
			"title": (string255), // внутренний номер заказа
			"type": (enum('main', 'additional')) // тип связи между заказами
		}
	],
	"documents": [ // список сопроводительных документов к заказу
		{
			"uuid": (UUID), // уникальный идентификатор документа
			"type": (string255), // тип документа
			"link": (string1024) // ссылка на скачивание
		},
		...
	]
}

Список заказов по фильтру

URL: /order/filter/

Параметры:

{
	"datesIntervalHandle": ['CREATE', 'TAKEIN' 'GIVEOUT'], // какие именно даты передаются в параметре интервал (создание заказа, принятие на склад, выдача)
	"datesInterval": { // интервал дат
		"from" (date),
		"to": (date)
	},
	"cityFrom": { // город-филиал отправления
		"fiasGuid": (UUID), // идентификатор ФИАС (только для городов России)
		"city": (string255) // название населённого пункта в формате DaData
	},
	"cityTo": { // город-филиал назначения
		"fiasGuid": (UUID), // идентификатор ФИАС (только для городов России)
		"city": (string255) // название населённого пункта в формате DaData
	},
	"clientInfo": {
		"orderNumber": (string255) // номер заказа из клиентской системы. Можно искать по части строки, используя спецсимвол "*" в качестве множества символов. Внимание! При поиске по части строки, минимальное количество символов, отличных от спецсимвола "*",  в начале строки должно составлять не менее 3. Например, "abc*" либо "abc*gh"
	},
	"status": (const OrderStatus[]) // массив статусов заказа
}

Ответ:

{ 
	[
	{
		"uuid": (UUID), // номер заказа (для информации о заказе)
		"title": (string255), // внутренний номер заказа
		"type": enum('standard', 'courier','city-province'), // тип заказа (стандартная перевозка, интернет-магазин, город и область)
		"status": (OrderStatus), // текущий статус заказа
		"clientInfo": (OrderClientInfo), // информация от клиента
		"locationFrom": (Location), // адрес отправления
		"locationTo": (Location), // адрес получения
		"storehouseFrom": { // пункт приема заказа
			"uuid": (UUID), // идентификатор
			"date": (date) // дата самоподвоза
		},
		"storehouseTo": { // пункт выдачи заказа
			"uuid": (UUID), // идентификатор
			"estimatedDate": "storehouseTo": (datetime), // дата прибытия на склад назначения (после приёма заказа на склад отправления)
			"date": (date) // дата самовывоза (пока не используется, зарезервировано)
		},
		"services": (OrderService[]), // список дополнительных услуг.
		"cargoSummary": (CargoSummary), // сводная информация о грузе
		"sum": (Money), // общая сумма заказа
		"history": [ // история изменений заказа
			{
				"status": (OrderStatus), // статус заказа
				"updatedAt": (datetime) // дата/время перехода заказа в данный статус
			},
			...
		], 
		"linkedOrders": [ // список заказов, связанных с текущим (дооформленные услуги, возвраты и т.д.)
			{
				"uuid": (UUID), // номер заказа (для информации о заказе)
				"title": (string255), // внутренний номер заказа
				"type": (enum('main', 'additional')) // тип связи между заказами
			}
		], 
		"documents": [ // список сопроводительных документов к заказу
			{
				"uuid": (UUID), // уникальный идентификатор документа
				"type": (string255), // тип документа
				"link": (string1024) // ссылка на скачивание
			},
			...
		]
	},
	... 
	]
}

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

URL: /document/order/

Параметры:

{
	"uuid": (UUID), // уникальный идентификатор заказа, обязательное
	"documentType": (const DocumentType) // тип документа накладной, обязательное
}

Ответ:

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

Формирование списка номеров ЭР на дату забора груза

Примечание: данный метод актуален только для накладных с типом "courier".

URL: /document/receipt-number/

Параметры:

{
	"pickupDate": (date) // дата забора груза, обязательное
}

Ответ:

{
	{
		"title": (string255), // Номер ЭР
		"uuid": (UUID[]) // Массив UUID заказов, относящихся к ЭР
	},
	...
}

Формирование ЭР по номеру

Примечание: данный метод актуален только для накладных с типом "courier".

URL: /document/receipt/

Параметры:

{
	"pickupDate": (date), // дата забора груза (нужна для формирования списка доступных номеров ЭР на указанную дату), обязательное
	"title": (string255) // номер ЭР, обязательное
}

Ответ:

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

Часто задаваемые вопросы

Что означает type(enum("standard", "courier"))? В чём разница между этими типами?

  • type="standard". Данный тип представляет собой услугу перевозки со всем спектром дополнительных услуг: забор груза от отправителя, упаковка, перевозка груза в город назначения, доставка груза со склада получателю и т.д. Это стандартная услуга, её используют в большинстве случаев.
  • type="courier". Данный тип описывает так называемую курьерскую доставку. Если вы являетесь Интернет-магазином, то скорее всего именно эта услуга вам и подойдёт. Взаимодействие в рамках данной услуги происходит следующим образом:
    • мы забираем у Интернет-магазина товар, предназначенный для покупателя Интернет-магазина;
    • далее мы осуществляем доставку груза клиенту Интернет-магазина наложенным платежом;
    • после осуществления доставки и получения денег с покупателя мы эти деньги за вычетом своей комиссии перечисляем Интернет-магазину.
    По сути это стандартная доставка плюс услуга наложенного платежа. 
    Для работы по такой схеме Интернет-магазин должен заключить с нами соответствующий договор. Также вы можете обсудить индивидуальные условия доставки с вашим менеджером.

В поле Customer для отправителя Sender есть наименование организации, ИНН, телефоны. Эти данные нужно указывать в каждом заказе?

Да, нужно указывать в каждом заказе. ИНН является обязательным и основным идентифицирующим полем, по нему определяется нужный вам клиент. Бывает такое, что у некоторых клиентов имеются скидки.

Наименование организации и телефон также нужно указывать. К тому же в рамках взаимодействия по API заполнение таких полей не должно составлять каким-то трудностей.

Обязательно ли мне заполнять у Contact поля name,  phone?

У Клиента (Customer) зачастую бывает несколько контактов (Contact). За отправку и приём каждого конкретного заказа отвечает тот или иной определённый сотрудник клиента. Причём за отправку и за приём в общем случае отвечают разные сотрудники. Особенно если речь идёт про доставку по межгороду. Экспедитор будет связываться именно с этим человеком, например, в случае необходимости уточнить детали забора груза.

Резюмируем. Если речь идёт про юр.лицо, то нужно указывать контакты именно того сотрудника, который сможет сориентировать водителя по забираемому грузу или доставляемому. Даже в случае физ.лица следует указать контакты клиента в месте отправления и месте получения, т.к. и адрес, и телефон, и даже личность отправителя и получателя может быть разная.

Как заполнять услуги Забор(PICKUP), Доставка(DELIVERY)?

Если есть услуга забор (PICKUP), то locationFrom.address обязательно для заполнения, если есть услуга доставка (DELIVERY), то locationTo.address обязательно для заполнения.

... "locationTo": {
 "fiasGuid": "7339e834-2cb4-4734-a4c7-1fca2c66e562",
 "city": "Уфа",
 "address": "г Уфа, ул Ленина д1"
 }
...

Как заполнять dimensionsMax?

Основной смысл в том, чтобы понять, какую машину подать для перевозки груза. Для этого по всем грузоместам берется максимальное значение каждого из параметров длина, ширина и высота.

Например, есть такие три места, длина, ширина и высота которых:

  • 2.4х0.3х0.3
  • 2.2х2х1
  • 1х1х2.5

В данном случае в dimensionsMax записываем максимальные значения 2.4х2х2.5. Вес для данной сущности можете оставить пустым или null.

Можно ли заполнить только объем как на сайте без ввода габаритов?

На данный момент такой возможности нет, возможно она появится в будущем. На сайте glavdostavka.ru можно просчитать по объему, но так же обязательным является ввод максимальных габаритов, другими словами у вас не получится создать заказ не указав габариты, габариты нужны для того что бы понять какую машину нужно подать.

Как мне вносить одинаковые позиции в cargo, если накладная type="standard"?

Для одинаковых грузомест можно для удобства указать параметр amount (количество) со значением больше 1. Это подходит для накладной типа "standard".

Например,

	// ...10 одинаковых мешков цемента
	"dimensions": {
		"dimensionsItem": {
			"length": 0.6,
			"width": 0.3,
			"height": 0.2,
			"weight": 40
		},
		"amount": 10
	},...

Как мне вносить одинаковые позиции в cargo, если накладная type="courier"?

Если у вас несколько одинаковых грузомест и тип накладной type="courier", вы можете добавлять каждую позицию как отдельный объект Cargo (Груз). В этом случае вы сможете для каждой позиции задать itemNumber (артикул).

В каком случае поле email обязательно, если накладная с типом "courier"?

Поле email обязательно для необходимости отправки электронного чека Получателю, то есть при передаче заказа и получении наложенного платежа.

Что такое маркировочный лист?

Маркировочный лист — это специфичный документ, который содержит информацию о грузовом месте и об отправлении в целом. Оформляется на каждое грузовое место и клеится на него. Маркировочный лист формируется клиентом. Компания ГлавДоставка формирует свою дополнительную маркировку, которая никак не зависит от клиентской.

Маркировочный лист используется клиентами зачастую при паллетной перевозке в сетевые магазины. На текущий момент данный вид перевозки недоступен при работе по API. Если вы являетесь представителем сетевого магазина и вам интересна данная услуга, свяжитесь со своим менеджером в ГлавДоставке и он вас сможет проконсультировать по условиям оказания данной услуги. 

Что такое экспедиторская расписка у накладной с типом "courier"?

Экспедиторская расписка (ЭР) —  это документ, который заполняется и передается от клиента водителю, по сути это доверенность на перевозку груза, который нам не принадлежит. В данном случае документ имеет отношение к услуге Забор и становится доступен только после того как услуга запланирована в работу. На тестовом контуре необходимо эмулировать это действие дополнительно сотрудниками ГлавДоставки.

Как пользоваться методами /document/receipt-number/ и /document/receipt/?

Данные методы нужны для заказов с type="courier", если есть услуга "Забор" и услуга взята в работу. На тестовом контуре данное действие может быть сэмулировано только сотрудниками ГлавДоставки.

Метод /document/receipt-number/ по дате "Забора" позволяет получить title (номер экспедиторская расписки - ЭР). Затем, имея номер ЭР и дату забора, формируется сама ЭР в методе /document/receipt/. Другими словами сперва необходимо получить номер ЭР, затем по номеру и дате "забора" вы можете сгенерировать саму ЭР.

Можно ли у заказа с type="courier" не указывать наложенный платеж?

Заказ с типом курьерская доставка (courier) задумывался таким образом, чтобы можно было фиксировать наложенный платеж через стоимость каждой позиции cargo.payment и через стоимость доставки deliveryPayment. Создание заказа с типом курьерская доставка с наложенным платежом равным 0 не имеет смысла. Если наложенный платеж равен 0, то указывать тип сборка (standard) будет правильнее.

Можно ли указать плательщиком за транспортно-экспедиторские услуги получателя в заказах с type="courier"?

Есть финансовые отношения между компанией ГлавДоставка и клиентом (плательщик в заказе), в рамках которых Плательщик должен оплатить транспортно-экспедиторские услуги (ТЭУ), которые ему оказала ГлавДоставка. А есть отношения между Плательщиком и Получателем заказа. ГлавДоставка взимает денежные средства за товар (Наложенный платеж) и перечисляет их Плательщику. И как раз стоимость доставки, которую Плательщик объявляет Получателю (deliveryPayment) и включает в стоимость своего заказа - это часть суммы, которую мы должны получить с Получателя и перечислить обратно Плательщику. Эта стоимость никак не пересекается с финальной стоимостью ТЭУ, которые мы оказываем в целом, там может быть много сопутствующих услуг. Таким образом, это означает, что мы должны получить информацию о дополнительной сумме, которую должны взять с Получателя и перечислить в рамках наложенного платежа. По нашим же ТЭУ Получатель не может никаким образом выступать платежным контрагентом.


Почему в service/cities нет города N

В документации метод service/cities называется "Список городов филиалов", другими словами он возвращает только те города(населенные пункты) где у ГлавДоставки есть филиалы.
Но вы можете создать/просчитать заказ указав fiasGuid этого города, его можно взять на официальном ресурсе fias.nalog.ru.

Можно ли просчитывать/создавать заказы без страховки?

Страховка является обязательной услугой, груз страхуется в любом случае. Cтраховка «подцепляется» автоматически при просчете/создании накладной. Нужно выбрать один из двух вариантов:

  • либо страхование Клиентом, то есть за страховку платит клиент (этот вариант идёт по умолчанию);
  • либо страхование Перевозчиком, то есть за страховку платит ГлавДоставка.

По страхованию перевозчиком обращайтесь к вашему менеджеру.

Почему меняется стоимость страховки?

Стоимость страховки рассчитывается в соответствии с тарифами исходя из параметров груза. С актуальными тарифами можно ознакомиться на странице https://glav-dostavka.ru/services/cargo-insurance/.

Как задать оценочную стоимость груза(страховую сумму) самостоятельно?

Если вы знаете оценочную стоимость груза, то этот параметр  можете самостоятельно заполнить, так же необходимо учесть что это сумма будет преобразована до ближайшей большей суммы страхования, т.е. указав 250 000 руб преобразуется в страховую сумму 300 000, 500 000 в 600 000, все что больше 600 000 будет записано без изменений (данные суммы актуальны на момент написания документации см. https://glav-dostavka.ru/services/cargo-insurance/.).


Для того что бы задать оценочную стоимость необходимо передать сервис CARGO-INSURANCE:

// Пример запроса

{
	"code": "INSURANCE-CARGO",
		"params": {
			"appraiseValue": {
			    	"currency": "RUB",
			    	"value": 650000
			    }
			}
}


Мои ранее созданные заказы на тестовом контуре куда-то пропали.

Обновление тестовой базы происходит примерно раз в неделю, все тестовые заказы исчезают после этого.

Как мне лучше получать информацию по заказам?

Лучше получать активные заказы по статусам через /order/filter/ за период дат и на своей стороне разбирать, чем запрашивать по одной.

// Пример запроса

{
	"datesInterval": {
		"from": "2020-09-01",
		"to": "2020-09-30"
	}
}

Также для точности можете использовать параметры которые предоставляет метод.

Через /order/info/ вы можете точечно забирать накладные.

Почему у меня различается стоимость Перевозки при просчете накладной с типом "courier" и с типом "standard" по одним и тем же параметрам?

Перевозка — это услуга перемещения груза со склада отправления на склад назначения. Для courier (Курьерская доставка) и standard (Сборка) по смыслу они ничем не отличаются. Однако сотрудники ГлавДоставки могут заливать разные тарифы для «Перевозки» standard и «Перевозки» courier.

Как создать/просчитать заказ Город и область?

Это возможно только для заказов с type="standard".

Рассмотрим на примере Москвы и Московской области. Если у вас город отправления Москва, а город назначения Раменское, то для данного случая подходит тип заказа "Город и область".
Чтобы создать или просчитать такой заказ, необходимо обязательно указать услугу "Забор" (PICKUP), адрес отправителя locationFrom.address и адрес получателя locationTo.address . Доставку (DELIVERY) при этом указывать не нужно. Другими словами у заказов с таким типом нет привоза на склад, машина едет от адреса до адреса. Услуга выполняется в один день (дата "забора").

Примеры использования

Рассмотрим типовые сценарии использования API.

Все приведённые ниже примеры составлены в виде коллекции запросов Postman, вы можете запросить их по email api.clients@glavdostavka.ru.
Перед использованием данной коллекции обязательно впишите свой ключ в переменную AUTH!

Получение географии присутствия

Скорее всего первым шагов по внедрению данного API будет получение списка доступных для перевозки городов и складов. Конечно, это можно делать "на лету", каждый раз при формировании заказа, но лучше это делать периодически, например, раз в месяц или раз в квартал.

Итак, получаем города.

Делаем запрос по адресу http://api.glavdostavka.ru/v2/service/cities/ с телом запроса

{
    "countryCode": "RU"
}

Получим ответ:

{
    "result": [
        {
            "countryCode": "RU",
            "fiasGuid": "0c5b2444-70a0-4932-980c-b4dc0d3f02b5",
            "city": "г  Москва",
            "address": null
        },
        {
            "countryCode": "RU",
            "fiasGuid": "c2deb16a-0330-4f05-821f-1d09c93331e6",
            "city": "г  Санкт-Петербург",
            "address": null
        },
        {
            "countryCode": "RU",
            "fiasGuid": "42a02e11-a337-4d50-8596-fc76dae7c62a",
            "city": "Респ Хакасия, г Абакан",
            "address": null
        },
		// ...
	],
    "errors": [],
    "warnings": [],
    "meta": {
        "pagesAmount": null,
        "pagesCurrent": null,
        "pagesLimit": null
    },
    "debug": []
}


Далее получаем список складов в каждом городе. Для этого делаем запрос по адресу http://api.glavdostavka.ru/v2/service/storehouses/ с таким телом (для Москвы)

{
    "fiasGuid": "0c5b2444-70a0-4932-980c-b4dc0d3f02b5"
}

И получаем список складов

{
    "result": [
        {
            "uuid": "615595f3-bbea-0a29-c5a2-22842428acf8",
            "title": "\"Северное Домодедово\"",
            "location": {
                "countryCode": "RU",
                "fiasGuid": "0c5b2444-70a0-4932-980c-b4dc0d3f02b5",
                "city": "Москва",
                "address": "МО, г. Домодедово, ул. Логистическая, д. 1/11"
            },
            "contact": {
				// ...
			},
			"operations": [
                "TAKEIN",
                "GIVEOUT"
            ]
        },
        {
            "uuid": "dfbff02f-628f-9b96-22ef-21110647a6fb",
            "title": "\"Дмитровка\"",
            "location": {
                "countryCode": "RU",
                "fiasGuid": "0c5b2444-70a0-4932-980c-b4dc0d3f02b5",
                "city": "Москва",
                "address": "г Москва, Дмитровское шоссе, д 116"
            },
            "contact": {
				// ...
			},
			"operations": [
                "TAKEIN",
                "GIVEOUT"
            ]
        },
		// ... другие склады
	],
    "errors": [],
    "warnings": [],
    "meta": {
        "pagesAmount": null,
        "pagesCurrent": null,
        "pagesLimit": null
    },
    "debug": []
}

В последнем запросе fiasGuid = 0c5b2444-70a0-4932-980c-b4dc0d3f02b5 мы взяли из первого запроса из элемента, описывающего город Москва.

Расчёт и создание заказов

Далее добавляем возможность предварительного расчёта и последующего создания заказа.

Для расчёт заказа посылаем запрос по адресу http://api.glavdostavka.ru/v2/order/calc/?auth={{AUTH}}, а для создания — http://api.glavdostavka.ru/v2/order/create/?auth={{AUTH}}.

{{AUTH}} — это ваш авторизационный токен. Тело запроса для расчёта и для создания заказа практически идентичны.

Стандартная перевозка

Рассмотрим следующую ситуацию. Компания "Рога и копыта" отправляет из своего московского офиса в свой питерский офис несколько веников. Предполагается, что сами веники на склад Домодедово и со склада Парнас будет транспортировать сама компания. Как это будет происходить, выходит за рамки нашей истории, пусть это будет некий служебный автомобиль.

Хотелось бы обратить внимание на другие вещи.

Во-первых, при стандартной отправке (type="standard") мы обязательно указываем плательщика payer, т.к. в общем случае перевозку может оплачивать как отправитель, так и получатель.

Во-вторых, стоит отметить, что в данном простом примере в качестве отправителя и получателя выступает одна и та же организация, но контактные лица при отправке и получении, естественно, разные. Но даже если это было одно и то же лицо, которое по каким-либо причинам переместилось вслед за грузом, его так же нужно было бы указывать как в поле "sender", так и в поле "recipient". Такое вполне может быть, если заказ осуществляет частное лицо, которое занимается переездом из одного города в другой. 


{
    "type": "standard",
    "payer": "sender",
    "sender": {
        "customer": {
            "name": "ООО \"РОГА И КОПЫТА\"",
            "countryCode": "RU",
            "legalType": "COMPANY",
            "tin": "7723643863",
            "kpp": "772301001"
        },
        "contact": {
            "name": "Бобчинский Петр Иванович",
            "phones": [{
                "number": "+7 900 000 11 22"
            }]
        }
    },
    "recipient": {
        "customer": {
            "name": "ООО \"РОГА И КОПЫТА\"",
            "countryCode": "RU",
            "legalType": "COMPANY",
            "tin": "7723643863",
            "kpp": "772301001"
        },
        "contact": {
            "name": "Добчинский Петр Иванович",
            "phones": [{
                "number": "+7 900 000 22 11"
            }]
        }
    },
    "locationFrom": {
        "fiasGuid": "0c5b2444-70a0-4932-980c-b4dc0d3f02b5"	// Москва
    },
    "locationTo": {
        "fiasGuid": "c2deb16a-0330-4f05-821f-1d09c93331e6"	// Санкт-Петербург
    },
    "storehouseFrom": {
        "uuid": "615595f3-bbea-0a29-c5a2-22842428acf8",		// Склад Домодедово
        "date": "{{tomorrow}}"								// Дату нужно подставить в формате YYYY-MM-DD, например, 2020-10-20
    },
    "storehouseTo": {
        "uuid": "e907453d-7e2d-2154-2df9-21892698a52a"
    },
    "cargo": [
        {
            "dimensions": {
                "dimensionsItem": {
                    "length": 0.3,
                    "width": 0.1,
                    "height": 0.5,
                    "weight": 0.2
                },
                "amount": 100
            },
            "pack": ["CARDBOARD-BOX"]
        }
    ],
    "cargoType": "Веники",
    "dimensionsMax": {
        "length": 0.3,
        "width": 0.1,
        "height": 0.5,
        "weight": 0.2
    }
}

Курьерская доставка

Предположим, что мы являемся Интернет-магазином электросамокатов, у нас уже выполнена интеграция по API. Тогда наш код должен будет формировать запрос, представленный ниже.

Обратите внимание на то, что, указав type="courier", наш запрос будет несколько отличаться от запроса для стандартной доставки.

Во-первых, payer мы оставляем пустым или можем вообще опустить, т.к. в случае курьерской доставки перевозку оплачивает отправитель в рамках специального договора. Если же мы попробуем указать в качестве payer какое-то другое значение (как sender, так и recipient), в ответе мы получим ошибку 

		{
            "code": "ERR-FIELD-INCORRECT-DATA",
            "message": "Не удалось идентифицировать плательщика по накладной. Проверьте правильность заполнения плательщика, а в случае его отсутствия - отправителя.",
            "details": {
                "fieldNames": [
                    "payer"
                ],
                "suggest": []
            }
        }

Во-вторых, для своего удобства мы можем добавить поле clientInfo, где например мы можем указать номер заказа в рамках собственной системы.

В-третьих, поля locationFrom, locationTo, storehouseFrom отличаются по составу от тех, что были в стандартной отправке, а storehouseTo вообще отсутствует, т.к. мы предполагается, что клиент не поедет на склад получать свою покупку.

Также стоит отметить наличие доп.услуг PICKUP и DELIVERY. Как первая, так и вторая, в общем-то не являются обязательными для указания. И если PICKUP действительно зависит от схемы работы Интернет-магазина (какие-то организации сами привозят товар на склад, каким-то организациям проще заказывать забор груза), то DELIVERY лучше указывать сразу.

Ещё появляется поле openAllowed.

И наконец, самое главное и характерное отличие — появляются поля, описывающие стоимость доставки для получателя. Из них формируется наложенный платёж. 

	"cargo": [
        {
            // ...
            "itemNumber": 1, // порядковый номер в списке товаров
            "description": "Электросамокат Xiaomi Mijia M365 Pro",	// наименование позиции
            "payment": {	// стоимость товара для покупателя (клиента Интернет-магазина)
                "currency": "RUB",
                "value": 38000
            }
        },
	],
	// ...
	"deliveryPayment": {	// стоимость доставки для покупателя
        "currency": "RUB",
        "value": 250
    },
	// ...


Итак, собственно сам запрос следующий:

{
    "type": "courier",
    "payer": "",
    "sender": {
        "customer": {
            "name": "ООО \"МАГАЗИН САМОКАТОВ\"",
            "countryCode": "RU",
            "legalType": "COMPANY",
            "tin": "7723643863",
            "kpp": "772301001",
            "passport": null,
            "phone": [
                {}
            ],
            "email": "info@electro.samokaty.ru",
            "address": null
        },
        "contact": {
            "name": "Бургамистров Дермидонт Ибрагимович",
            "phones": [{
                "number": "+7 900 111 11 11",
                "additional": null
            }],
            "email": "bdi@electro.samokaty.ru"
        }
    },
    "recipient": {
        "customer": {
            "name": "Полуэктов Эдуард Игнатьевич",
            "countryCode": "RU",
            "legalType": "PERSONAL",
            "passport": {
                "countryCode": "RU",
                "series": "1234",
                "number": "098765",
                "dateIssue": "2009-05-13",
                "organization": "ГУ МВД РОССИИ ПО Г. МОСКВЕ",
                "dateBirth": "1975-08-27"
            },
            "phone": {
                "number": "+7 900 222 22 22"
            }
        },
        "contact": {
            "name": "Полуэктов Эдуард Игнатьевич",
            "phones": [{
                "number": "+7 900 222 22 22"
            }],
            "email": "poluektov.e.i.31254299@gmail.com"
        }
    },
    "clientInfo": {
        "orderNumber": "electro-s-0000146"
    },
    "locationFrom": {
        "countryCode": "RU",
        "fiasGuid": "0c5b2444-70a0-4932-980c-b4dc0d3f02b5",
        "city": "Москва",
        "address": "Кривоколенный переулок, 10с5"
    },
    "locationTo": {
        "countryCode": "RU",
        "fiasGuid": "c2deb16a-0330-4f05-821f-1d09c93331e6",
        "city": "Санкт-Петербург",
        "address": "улица Марата, 12"
    },
    "storehouseFrom": {
        "date": "{{tomorrow}}"
    },
    "services": [
        {
            "code": "PICKUP",
            "params": {
                "date": "{{tomorrow}}",
                "interval": {
                    "start": "10:00",
                    "end": "18:00"
                },
                "person": {
                    "name": "Бургамистров Дермидонт Ибрагимович",
                    "phones": [{
                        "number": "+7 900 111 11 11"
                    }]
                }
            }
        },
        {
            "code": "DELIVERY",
            "params": {
                "date": "{{today_plus_5}}",
                "interval": {
                    "start": "15:00",
                    "end": "18:00"
                },
                "person": {
                    "name": "Полуэктов Эдуард Игнатьевич",
                    "phones": [{
                        "number": "+7 900 222 22 22"
                    }],
                    "email": "poluektov.e.i.31254299@gmail.com"
                }
            }
        }
    ],
    "cargo": [
        {
            "dimensions": {
                "dimensionsItem": {
                    "length": 1.5,
                    "width": 0.5,
                    "height": 0.4,
                    "weight": 14
                },
                "amount": 1
            },
            "itemNumber": "Артикул 1",
            "description": "Электросамокат Xiaomi Mijia M365 Pro",
            "payment": {
                "currency": "RUB",
                "value": 38000
            }
        },
        {
            "dimensions": {
                "dimensionsItem": {
                    "length": 0.2,
                    "width": 0.05,
                    "height": 0.2,
                    "weight": 0.3
                },
                "amount": 2
            },
            "itemNumber": "Артикул 2",
            "description": "Покрышки 8.5 дюймов",
            "payment": {
                "currency": "RUB",
                "value": 800
            }
        }
    ],
    "cargoType": "Электросамокат",
    "openAllowed": true,
    "deliveryPayment": {
        "currency": "RUB",
        "value": 250
    },
    "dimensionsMax": {
        "length": 1.5,
        "width": 0.5,
        "height": 0.4,
        "weight": 14
    }
}

Результат создания

Если нет ошибок в заполнении полей, то при отправке запроса на создание заказа мы получим ответ следующего вида

{
    "result": {
        "uuid": "6fb504e0-fa1b-42e4-fe67-25430371ad8a",
        "title": "МСК-СПБ-788394/20-Д",
        "orderClientInfo": {
            "orderNumber": "electro-s-0000146",
            "tn": null,
            "ttn": null,
            "trn": null,
            "sf": null,
            "additional": null
        },
        "services": [
			// ...
		],
		// ...
		"sum": {
            "currency": "RUB",
            "value": 3354
        },
		// ...
	},
	"errors": [],
    "warnings": [],
    "meta": {
        "pagesAmount": null,
        "pagesCurrent": null,
        "pagesLimit": null
    },
    "debug": []
}

В массиве services вы можете увидеть список услуг, среди которых есть как те, которые вы запрашивали, так и те, которые могли появиться в силу указанных параметров заказа, например, "Въезд в садовое кольцо" или "Въезд в третье транспортное кольцо".

Мониторинг состояния накладных

Лучший способ следить за состоянием накладных — делать общий запрос за определённый период времени, например, за прошедшую неделю. Для этого можно написать скрипт, который будет выполняться по cron-расписанию, например, раз в час, проверять изменения в статусах заказов и оповещать пользователей о соответствующих изменениях. 

Для ситуации, когда нужно уточнить информацию только по одной накладной, например, когда пользователь сам зашёл в свой личный кабинет в Интернет-магазине, и хочет узнать, где находится его покупка, можно делать отдельные запросы на получение информации по конкретному заказу.

Получение списка заказов

Для получения списка заказов необходимо сделать запрос по адресу http://api.glavdostavka.ru/v2/order/filter/?auth={{AUTH}}

{
	"datesIntervalHandle": ["CREATE"],	// Указанные ниже даты относятся ко времени создания заказов
	"datesInterval": {				// Получаем данные по заказам, созданным в период
		"from": "{{week_ago}}",		// не раньше недели назад
		"to": "{{today}}"			// и по сегодняшний день
	},
	"status": [ "NEW", "PICKUP-PLAN", "PICKUP-DONE", "STOREHOUSE-FROM" ]	// И находящиеся в перечисленных статусах
}

В результате данного запроса вы получите ответ, содержащий достаточно полную информацию обо всех попавших под фильтр заказах

{
    "result": [
        {
            "uuid": "2ee0e862-fc80-b832-3d2d-25430360a629",
            "title": "МСК-РНД-788383/20-Д",
            "status": "NEW",
            "clientInfo": {
                "orderNumber": "insurance_alpha_api4-testCreateOrderByApi_beed00e03d36012d38162b5cfcc4f53d",
                "tn": "7901d5bfe9f42f6dc56c05ad1cd970f6",
                "ttn": "fe9fff55b5fbfbe5b6ce7948d74b5650",
                "trn": "9d48a360edbffe914f655887bbf60987",
                "sf": "1111f85b00717233ed53037328f9b68e",
                "additional": null
            },
			// и другие поля, совпадающие с теми, что были в ответе на создание заказа
		},
		{
			// второй заказ
		},
		{
			// третий заказ
		},
		// ...
	],
	"errors": [],
    "warnings": [],
    "meta": {
        "pagesAmount": null,
        "pagesCurrent": null,
        "pagesLimit": null
    },
    "debug": []
}

Получение информации по отдельному заказу

Запрос информации по отдельному заказу производится по адресу http://api.glavdostavka.ru/v2/order/filter/?auth={{AUTH}} одним из следующих способов.

Либо по UUID

{
    "uuid": "ab7cedbe-474f-1b0f-e09d-25430369a9a0"
}

либо по номеру накладной

{
    "title": "МСК-СПБ-788392/20-Д"
}

Информация, которую вы получите в результате такого запроса, совпадает с той, которая приходит при запросе заказов списком, с той лишь разницей, что вместо массива заказов вы получаете один элемент такого массива.

Документы по накладным

Маркировка

Для скачивания маркировки в формате PDF необходимо сделать запрос по адресу http://api.glavdostavka.ru/v2/document/order/?auth={{AUTH}}

{
	"uuid": "084c1099-d045-f06a-54c1-25430406af03",
	"documentType": "CARGO-LABEL"
}

Сводный список накладных

Для формирования списка накладных на определённую дату забора нужно сделать запрос по адресу http://api.glavdostavka.ru/v2/document/receipt-number/?auth={{AUTH}}

{
	"pickupDate": "{{tomorrow}}"
}

Экспедиторская расписка

Теперь, имея список номеров накладных на определённую дату, для скачивания экспедиторской расписки по отдельному заказу в формате PDF нужно выполнить запрос по адресу http://api.glavdostavka.ru/v2/document/receipt/?auth={{AUTH}}

{
    "pickupDate": "{{tomorrow}}",
    "title": "084c1099-d045-f06a-54c1-25430406af03"
}