Получение статистической отчетности
Общие сведения
Сервис предназначен для получения статистической отчетности и аналогичен соответствующему разделу личного кабинета. Доступ к сервису предоставляется аккаунту с полным доступом в Личный Кабинет ГК Деловые Линии.
Получение отчета осуществляется в два этапа: необходимо последовательно направить запросы к двум методам API, описанным в документе.
При обращении к первому методу передаются параметры формирования отчета и инициализируется его генерация. В ответе метода пользователь получает номер формируемого отчета.
В запросе ко второму методу следует передать полученный номер отчета - в ответ будет выведен статус формирования отчета. Если на момент направления запроса отчет уже сформирован, то ответ также будет содержать ссылки на отчет в форматах json, xml и xlsx. Если отчет ещё не сформирован, ответ будет содержать соответствующий статус.
Сформированный отчет доступен на сервере в течение недели.
Используемые термины и сокращения
Термин / Сокращение | Описание |
---|---|
ИНН | Идентификационный номер налогоплательщика |
КА | Контрагент |
НВ | Накладная на выдачу |
ПН | Приемная накладная |
Инициализация формирования отчета
Запрос метода
Структура запроса
Адрес метода: https://api.dellin.ru/v1/customers/create_report.json
{ "appkey":"00000000-0000-0000-0000-000000000000", "sessionID":"00000000-0000-0000-0000-000000000000", "counteragentUID":220568, "stateRequest":["processed"], "stateShipping":["inway"], "dateStart":"2017-03-01", "dateEnd":"2017-03-31", "reportParams":["derivalPoint","arrivalPoint"], "cityCodeDerival":12345, "groupCityDerival":false, "cityCodeArrival":54321, "groupCityArrival":false, "addressArrival":"7700000000000000000000000", "groupAddressArrival":false, "terminalID":123456789, "groupTerminal":false, "senderCounteragentID":219467, "groupSender":false, "receiverCounteragentID":349231, "groupReceiver":false, "payerCounteragentID":239812, "groupPayer":false }
Адрес метода: https://api.dellin.ru/v1/customers/create_report.xml
<request> <appkey>00000000-0000-0000-0000-000000000000</appkey> <sessionID>00000000-0000-0000-0000-000000000000</sessionID> <counteragentUID>220568</counteragentUID> <stateRequest>processed</stateRequest> <stateShipping>inway</stateShipping> <dateStart>2017-03-01</dateStart> <dateEnd>2017-03-31</dateEnd> <reportParams>derivalPoint</reportParams> <reportParams>arrivalPoint</reportParams> <cityCodeDerival>12345</cityCodeDerival> <groupCityDerival>false</groupCityDerival> <cityCodeArrival>54321</cityCodeArrival> <groupCityArrival>false</groupCityArrival> <addressArrival>7700000000000000000000000</addressArrival> <groupAddressArrival>false</groupAddressArrival> <terminalID>123456789</terminalID> <groupTerminal>false</groupTerminal> <senderCounteragentID>219467</senderCounteragentID> <groupSender>false</groupSender> <receiverCounteragentID>349231</receiverCounteragentID> <groupReceiver>false</groupReceiver> <payerCounteragentID>239812</payerCounteragentID> <groupPayer>false</groupPayer> </request>
Описание параметров
Request | |||
---|---|---|---|
Параметр | R* | Тип | Описание |
appkey | Да | string | Ключ приложения. Для получения ключа необходимо пройти регистрацию |
sessionID | Да | string | ID сессии. Для получения сессии необходимо воспользоваться методом "Авторизация пользователя" |
Нет | array of strings | Статус заявки.
Если в массиве не передано ни одного значения, то будут возвращены заявки во всех статусах | |
stateShipping | Нет | array of strings | Статус накладной. Доступные значения:
Если в массиве не передано ни одного значения, то будут возвращены накладные во всех статусах |
Период построения отчета | |||
dateStart | Нет | date | Дата начала периода. Формат даты: "ГГГГ-ММ-ДД" |
dateEnd | Нет | date | Дата окончания периода. Формат даты: "ГГГГ-ММ-ДД" |
Отчет будет содержать данные по заказам, дата создания которых попадает в указанный период.Период построения отчета не должен превышать 31 день.Если даты начала и окончания в запросе не переданы, то применяется период по умолчанию:
| |||
Параметры отчета | |||
reportParams | Нет | array of strings | Перечень параметров, которые необходимо передать в отчете. Если параметр пустой или отсутствует, то отчет будет содержать все параметры из справочника |
Параметры выборки данных и группировки отчета | |||
Выборка данных и группировка отчета при передаче соответствующих параметров из данной группы осуществляется только для тех параметров, которые были переданы в массиве "reportParams". Наименования параметров массива "reportParams", соответствующих доступным параметрам (признакам) группировки, приведены ниже - в описании этих признаков группировки.При инициации группировки отчета (по одному или нескольким признакам) в отчет выводятся не все параметры, переданные в массиве "reportParams", а только:
| |||
cityCodeDerival | Нет | string | Код КЛАДР города отправки груза. В запросе может быть передан только один код КЛАДР. Если параметр пустой или отсутствует, то отчет будет содержать данные по всем городам |
groupCityDerival | Нет | boolean | Признак группировки результатов отчета по городу отправки груза. Если значение параметра "groupCityDerival" = "true" и:
Значение по умолчанию: "false". Чтобы осуществлялась данная группировка, в массиве "reportParams" должен быть передан параметр "derivalPoint" |
cityCodeArrival | Нет | string | Код КЛАДР города прибытия груза. В запросе может быть передан только один код КЛАДР. Если параметр пустой или отсутствует, то отчет будет содержать данные по всем городам |
groupCityArrival | Нет | boolean | Признак группировки результатов отчета по городу прибытия груза. Если значение параметра "groupCityArrival" = "true" и:
Значение по умолчанию: "false". Чтобы осуществлялась данная группировка, в массиве "reportParams" должен быть передан параметр "arrivalPoint" |
addressArrival | Нет | string | Код КЛАДР улицы доставки груза (адрес доставки). В запросе может быть передан только один адрес. Если параметр пустой или отсутствует, то отчет будет содержать результаты по всем адресам |
groupAddressArrival | Нет | boolean | Признак группировки результатов отчета по адресу доставки груза. Если значение параметра "groupAddressArrival" = "true" и:
Значение по умолчанию: "false". Чтобы осуществлялась данная группировка, в массиве "reportParams" должен быть передан параметр "arrivalAddress" |
terminalID | Нет | integer | Терминал выдачи груза. В запросе может быть передан только один терминал. Если параметр пустой или отсутствует, то отчет будет содержать результаты по всем терминалам |
groupTerminal | Нет | boolean | Признак группировки результатов отчета по терминалу выдачи груза. Если значение параметра "groupTerminal" = "true" и:
Значение по умолчанию: "false". Чтобы осуществлялась данная группировка, в массиве "reportParams" должен быть передан параметр "arrivalTerminal" |
senderCounteragentID | Нет | integer | ID КА-отправителя груза. Если параметр пустой или отсутствует, то отчет будет содержать результаты по всем КА-отправителям |
groupSender | Нет | boolean | Признак группировки результатов отчета по отправителю груза. Если значение параметра "groupSender" = "true" и:
Значение по умолчанию: "false". Чтобы осуществлялась данная группировка, в массиве "reportParams" должен быть передан параметр "senderName" |
receiverCounteragentID | Нет | integer | ID КА-получателя груза. Если параметр пустой или отсутствует, то отчет будет содержать результаты по всем КА-получателям |
groupReceiver | Нет | boolean | Признак группировки результатов отчета по получателю груза. Если значение параметра "groupReceiver" = "true" и:
Значение по умолчанию: "false". Чтобы осуществлялась данная группировка, в массиве "reportParams" должен быть передан параметр "receiverName" |
payerCounteragentID | Нет | integer | ID КА-плательщика. Если параметр пустой или отсутствует, то отчет будет содержать результаты по всем КА-плательщикам |
groupPayer | Нет | boolean | Признак группировки результатов отчета по плательщику. Если значение параметра "groupPayer" = "true" и:
Значение по умолчанию: "false". Чтобы осуществлялась данная группировка, в массиве "reportParams" должен быть передан параметр "payerName" |
Ответ метода
Структура ответа
{ "reportNumber":"12345" }
<response> <reportNumber>12345</reportNumber> </response>
Описание параметров
Response | ||
---|---|---|
Параметр | Тип | Описание |
reportNumber | string | Номер отчета |
Обработка ошибок
Если в запросе один из параметров был передан некорректно, то вернётся соответствующее сообщение об ошибке. Например, если передан некорректный UID КА, то сообщение будет иметь следующий вид:
Пример ответа - Некорректный параметр
{ "errors":{ "counteragentUID":"Некорректный counteragentUID" } }
<response> <errors> <counteragentUID>Некорректный counteragentUID</counteragentUID> </errors> </response>
Если в запросе переданы даты начала и окончания периода, при этом продолжительность периода превышает 31 день, то будет выведено следующее сообщение:
Пример ответа - Некорректный период
{ "errors":{ "period":"Период построения отчета должен быть меньше либо равен 31 дню" } }
<response> <errors> <period>Период построения отчета должен быть меньше либо равен 31 дню</period> </errors> </response>
Мониторинг статуса и получение отчета
Запрос метода
Структура запроса
Адрес метода: https://api.dellin.ru/v1/customers/get_report.json
{ "appkey":"00000000-0000-0000-0000-000000000000", "sessionID":"00000000-0000-0000-0000-000000000000", "reportNumber":"12345" }
Адрес метода: https://api.dellin.ru/v1/customers/get_report.xml
<request> <appkey>00000000-0000-0000-0000-000000000000</appkey> <sessionID>00000000-0000-0000-0000-000000000000</sessionID> <reportNumber>12345</reportNumber> </request>
Описание параметров
Request | |||
---|---|---|---|
Параметр | R* | Тип | Описание |
appkey | Да | string | Ключ приложения. Для получения ключа необходимо пройти регистрацию |
sessionID | Да | string | ID сессии. Для получения сессии необходимо воспользоваться методом "Авторизация пользователя" |
reportNumber | Да | string | Номер отчета, по которому необходимо получить информацию. Номер отчета можно получить с помощью метода "Инициализация формирования отчета" |
Ответ метода
Если в запросе был передан номер отчета, который еще не сформирован, ответ будет иметь следующий вид:
Пример ответа - Запрос не сформирован
{ "reportState":"queue" }
<response> <reportState>queue</reportState> </response>
Описание параметров
Response | ||
---|---|---|
Параметр | Тип | Описание |
string | Статус отчета. Возможные значения:
Для данного случая вернется значение "queue" или "processing" |
Если в запросе был передан номер отчета, который уже сформирован, вид ответа будет следующий:
Пример ответа - Запрос сформирован
{ "report":{ "reportXML":"https://assets.dellin.ru/assets/api.dellin.stage/2017/9/25/3520779/original/report_372_b90f83d74c4b4cca.xml", "reportJSON":"https://assets.dellin.ru/assets/api.dellin.stage/2017/9/25/3520778/original/report_372_cfbcbec714f14d35.json", "reportXLSX":"https://assets.dellin.ru/assets/api.dellin.stage/2017/9/25/3520780/original/report_372_d21374955caa477d.xlsx" }, "reportState":"finished" }
<response> <report> <reportXML>https://assets.dellin.ru/assets/api.dellin.stage/2017/9/25/3520779/original/report_372_b90f83d74c4b4cca.xml</reportXML> <reportJSON>https://assets.dellin.ru/assets/api.dellin.stage/2017/9/25/3520778/original/report_372_cfbcbec714f14d35.json</reportJSON> <reportXLSX>https://assets.dellin.ru/assets/api.dellin.stage/2017/9/25/3520780/original/report_372_d21374955caa477d.xlsx</reportXLSX> </report> <reportState>finished</reportState> </response>
Описание параметров
Response | ||
---|---|---|
Параметр | Тип | Описание |
reportState | string | Статус отчета. Возможные значения:
Для данного случая вернется значение "finished" |
report | object | Ссылки на отчет в форматах json, xml и xlsx |
reportJSON | string | Ссылка на отчет в формате json |
reportXML | string | Ссылка на отчет в формате xml |
reportXLSX | string | Ссылка на отчет в формате xlsx |
Обработка ошибок
Если в запросе был передан некорректный номер отчета или номер отчета, информации по которому нет в БД, то будет выведено следующее сообщение об ошибке:
Пример ответа - Некорректный номер отчета
{ "errors":{ "reportNumber":"Некорректный номер отчета" } }
<response> <errors> <reportNumber>Некорректный номер отчета</reportNumber> </errors> </response>
Пример отчета
Если в запросе метода "Инициализация формирования отчета" в массиве "reportParams" был передан полный набор параметров из "Справочника параметров для статистического отчета", при этом не была инициирована группировка данных в отчете (все признаки группировки были переданы со значениями "false"), то отчет, расположенный по ссылке из ответа метода, будет иметь следующий вид:
Пример отчета без выборки и группировки данных
{ "orders":[ { "date":"2017-09-23", "number":"17-00395018520", "derivalPoint":"Омск", "arrivalPoint":"Москва", "arrivalAddress":"117535, Москва г, Подольских Курсантов ул, дом № 17, корпус 2", "arrivalTerminal":"Москва Юг 2", "freightName":"Мебель", "quantity":1, "volume":2.0, "weight":2, "shippingCost":4592.0, "deliveryCost":"0.0", "insuranceSum":33.0, "discountSum":36.0, "senderName":"ООО \"Завод МарКон\"", "senderInn":"7604300539", "receiverName":"ООО \"ДЛК Маркет\"", "receiverInn":"1656064338", "realReceiver":"", "payerName":"ООО \"Завод МарКон\"", "payerInn":"7604300539", "block":"Блокировка по оплате, 2017-09-23", "warehousing":"300.0, 2017-09-25", "state":"inway", "accompanyingDocuments":"1112 от 2017-09-19", "comment":"Комментарий", "serviceKind":"Авто" } ] }
<orders> <date>2017-09-23</date> <number>17-00395018520</number> <derivalPoint>Омск</derivalPoint> <arrivalPoint>Москва</arrivalPoint> <arrivalAddress>117535, Москва г, Подольских Курсантов ул, дом № 17, корпус 2</arrivalAddress> <arrivalTerminal>Москва Юг 2</arrivalTerminal> <freightName>Мебель</freightName> <quantity>1</quantity> <volume>2</volume> <weight>2</weight> <shippingCost>4592</shippingCost> <deliveryCost>0.0</deliveryCost> <insuranceSum>33</insuranceSum> <discountSum>36</discountSum> <senderName>ООО "Завод МарКон"</senderName> <senderInn>7604300539</senderInn> <receiverName>ООО "ДЛК Маркет"</receiverName> <receiverInn>1656064338</receiverInn> <realReceiver></realReceiver> <payerName>ООО "Завод МарКон"</payerName> <payerInn>7604300539</payerInn> <block>Блокировка по оплате, 2017-09-23</block> <warehousing>300.0, 2017-09-25</warehousing> <state>inway</state> <accompanyingDocuments>1112 от 2017-09-19</accompanyingDocuments> <comment>Комментарий</comment> <serviceKind>Авто</serviceKind> </orders>
Описание параметров
Orders | |||
---|---|---|---|
Параметр | Тип | Наименование параметра в отчете | Описание |
date | date | Дата оформления заявки/накладной | Дата создания заявки. Формат даты: "ГГГГ-ММ-ДД" |
number | string | Номер заявки/накладной | Номер заявки/накладной |
derivalPoint | string | Город отправки | Город отправки груза |
arrivalPoint | string | Город прибытия | Город прибытия груза |
arrivalAddress | string | Адрес доставки | Адрес доставки груза |
arrivalTerminal | string | Терминал выдачи | ОСП и адрес ОСП |
freightName | string | Наименование груза | Характер груза |
quantity | integer | Количество мест | Количество мест в одной грузоперевозке по заказу |
volume | float | Общий объем | Общий объем груза |
weight | float | Общий вес | Общий вес груза |
shippingCost | float | Сумма ПН | Общая стоимость грузоперевозки по ПН, руб |
deliveryCost | float | Сумма НВ | Общая стоимость грузоперевозки по НВ, руб |
insuranceSum | float | Страховка | Стоимость страховки, руб |
discountSum | float | Скидка | Сумма скидки, руб |
sender | object | Отправитель | КА-отправитель |
sender.senderName | string | Отправитель | Наименование КА-отправителя |
sender.senderInn | integer | Отправитель | ИНН КА-отправителя |
receiver | object | Получатель | КА-получатель |
receiver.receiverName | string | Получатель | Наименование КА-получателя |
receiver.receiverInn | integer | Получатель | ИНН КА-получателя |
realReceiver | string | Фактический получатель | Фактический получатель груза |
payer | object | Плательщик | КА-плательщик |
payer.payerName | string | Плательщик | Наименование КА-плательщика |
payer.payerInn | integer | Плательщик | ИНН КА-плательщика |
block | string | Блокировка | Наличие блокировок по заказу. Дата и вид блокировки |
warehousing | string | Платное хранение | Дата начала и стоимость платного хранения |
state | string | Статус | Статус накладной/заказа/заявки |
accompanyingDocuments | string | Сопроводительные документы | Данные по сопроводительным документам |
comment | string | Комментарий к ПН | Комментарий к ПН |
serviceKind | string | Вид перевозки | Вид услуги: авто, авиа, экспресс и тд. |
Рассмотрим пример отчета, при формировании которого была запрошена группировка и выборка данных. Например, запрос метода "Инициализация формирования отчета" имел следующий вид:
Структура запроса
Адрес метода: https://api.dellin.ru/v1/customers/create_report.json
{ "appkey":"00000000-0000-0000-0000-000000000000", "sessionID":"00000000-0000-0000-0000-000000000000", "stateRequest":["accepted"], "stateShipping":["inway"], "reportParams":["number","date","derivalPoint","arrivalPoint","arrivalTerminal","shippingCost"], "cityCodeArrival":"7600000000000000000000000", "groupCityDerival":true, "groupCityArrival":true, "groupTerminalID":true }
Адрес метода: https://api.dellin.ru/v1/customers/create_report.xml
<request> <appkey>00000000-0000-0000-0000-000000000000</appkey> <sessionID>00000000-0000-0000-0000-000000000000</sessionID> <stateRequest>accepted</stateRequest> <stateShipping>inway</stateShipping> <reportParams>number</reportParams> <reportParams>date</reportParams> <reportParams>derivalPoint</reportParams> <reportParams>arrivalPoint</reportParams> <reportParams>arrivalTerminal</reportParams> <reportParams>shippingCost</reportParams> <cityCodeArrival>7600000000000000000000000</cityCodeArrival> <groupCityDerival>true</groupCityDerival> <groupCityArrival>true</groupCityArrival> <groupTerminalID>true</groupTerminalID> </request>
В этом случае сформированный отчет будет иметь вид:
Пример отчета с выборкой и группировкой данных
{ "orders":[ { "derivalPoint":"Димитровград", "arrivalPoint":"Ярославль", "arrivalTerminal":"Ярославль Промышленная 150044, Ярославская обл, Ярославль г, Промышленная ул, дом № 18 д", "shippingCost":"1799,00" }, { "derivalPoint":"Ярославль", "arrivalPoint":"Ярославль", "arrivalTerminal":"Ярославль Промышленная 150044, Ярославская обл, Ярославль г, Промышленная ул, дом № 18 д", "shippingCost":"160,00" } ] }
<orders> <order> <derivalPoint>Димитровград</derivalPoint> <arrivalPoint>Ярославль</arrivalPoint> <arrivalTerminal>Ярославль Промышленная 150044, Ярославская обл, Ярославль г, Промышленная ул, дом № 18 д</arrivalTerminal> <shippingCost>1799,00</shippingCost> </order> <order> <derivalPoint>Ярославль</derivalPoint> <arrivalPoint>Ярославль</arrivalPoint> <arrivalTerminal>Ярославль Промышленная 150044, Ярославская обл, Ярославль г, Промышленная ул, дом № 18 д</arrivalTerminal> <shippingCost>160,00</shippingCost> </order> </orders>