Поиск по сайту

API
Главная / API - Отчеты

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

Обновлено 30.10.2017
157 кб

Общие сведения

Сервис предназначен для получения статистической отчетности и аналогичен соответствующему разделу личного кабинета. Доступ к сервису предоставляется аккаунту с полным доступом в Личный Кабинет ГК Деловые Линии.

Получение отчета осуществляется в два этапа: необходимо последовательно направить запросы к двум методам API, описанным в документе.

При обращении к первому методу передаются параметры формирования отчета и инициализируется его генерация. В ответе метода пользователь получает номер формируемого отчета.

В запросе ко второму методу следует передать полученный номер отчета - в ответ будет выведен статус формирования отчета. Если на момент направления запроса отчет уже сформирован, то ответ также будет содержать ссылки на отчет в форматах json, xml и xlsx. Если отчет ещё не сформирован, ответ будет содержать соответствующий статус.

Сформированный отчет доступен на сервере в течение недели.

Используемые термины и сокращения

Термин / СокращениеОписание
ИННИдентификационный номер налогоплательщика
КАКонтрагент
НВНакладная на выдачу
ПНПриемная накладная

Инициализация формирования отчета

Запрос метода

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

Адрес метода: https://api.dellin.ru/v1/customers/create_report.json

{
   "appkey":"00000000-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-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ДаstringID сессии. Для получения сессии необходимо воспользоваться методом "Авторизация пользователя"
counteragentUIDНетstring
UID КА. В запросе может быть передан только один UID. Если параметр пустой или отсутствует, то будут возвращены заявки/накладные для всех КА
stateRequestНетarray of strings

Статус заявки.

Доступные значения:

  • "saved" - черновик
  • "loaded" - в обработке
  • "accepted" - принята
  • "declined" - отклонена

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

stateShippingНетarray of strings

Статус накладной.

Доступные значения:

  • "inway" - груз в пути
  • "arrived" - груз прибыл на терминал
  • "giveout" - груз выдан

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

Период построения отчета
dateStartНетdate

Дата начала периода.

Формат даты: "ГГГГ-ММ-ДД"

dateEndНетdate

Дата окончания периода.

Формат даты: "ГГГГ-ММ-ДД"

Отчет будет содержать данные по заказам, дата создания которых попадает в указанный период.Период построения отчета не должен превышать 31 день.Если даты начала и окончания в запросе не переданы, то применяется период по умолчанию:
  • дата начала периода = сегодняшний день - 31 день;
  • дата окончания периода = сегодняшний день.
Например, если сегодняшняя дата - 04.04.2017, то период по умолчанию: с 05.03.2017 по 04.04.2017.Если в запросе передана дата начала, но не передана дата окончания периода, то дата окончания устанавливается как дата начала + 31 день.Если в запросе передана дата окончания, но не передана дата начала периода, то дата начала устанавливается как дата окончания - 31 день.
Параметры отчета
reportParamsНетarray of strings

Перечень параметров, которые необходимо передать в отчете. Доступны параметры из "Справочника параметров для статистического отчета".

Если параметр пустой или отсутствует, то отчет будет содержать все параметры из справочника

Параметры выборки данных и группировки отчета
Выборка данных и группировка отчета при передаче соответствующих параметров из данной группы осуществляется только для тех параметров, которые были переданы в массиве "reportParams". Наименования параметров массива "reportParams", соответствующих доступным параметрам (признакам) группировки, приведены ниже - в описании этих признаков группировки.При инициации группировки отчета (по одному или нескольким признакам) в отчет выводятся не все параметры, переданные в массиве "reportParams", а только:
  • параметры, соответствующие всем признакам группировки (при этом, если в массиве "reportParams" не были переданы какие-то параметры, соответствующие этим признакам, тогда эти параметры возвращаются пустые)
  • параметр "shippingCost" (если он был передан в массиве "reportParams")
  • параметр "deliveryCost" (если он был передан в массиве "reportParams")
cityCodeDerivalНетstring

Код КЛАДР города отправки груза. В запросе может быть передан только один код КЛАДР.

Если параметр пустой или отсутствует, то отчет будет содержать данные по всем городам

groupCityDerivalНетboolean

Признак группировки результатов отчета по городу отправки груза.

Если значение параметра "groupCityDerival" = "true" и:

  • параметр "cityCodeDerival" пустой или отсутствует, тогда результаты в отчете будут сгруппированы по всем городам отправки;
  • в параметре "cityCodeDerival" передан код КЛАДР города отправки, тогда результаты в отчете будут сгруппированы по указанному городу.

Значение по умолчанию: "false".

Чтобы осуществлялась данная группировка, в массиве "reportParams" должен быть передан параметр "derivalPoint"

cityCodeArrivalНетstringКод КЛАДР города прибытия груза. В запросе может быть передан только один код КЛАДР.

Если параметр пустой или отсутствует, то отчет будет содержать данные по всем городам

groupCityArrivalНетboolean

Признак группировки результатов отчета по городу прибытия груза.

Если значение параметра "groupCityArrival" = "true" и:

  • параметр "cityCodeArrival" пустой или отсутствует, тогда результаты в отчете будут сгруппированы по всем городам прибытия;
  • в параметре "cityCodeArrival" передан код КЛАДР города прибытия, тогда результаты в отчете будут сгруппированы по указанному городу.

Значение по умолчанию: "false".

Чтобы осуществлялась данная группировка, в массиве "reportParams" должен быть передан параметр "arrivalPoint"

addressArrivalНетstring

Код КЛАДР улицы доставки груза (адрес доставки). В запросе может быть передан только один адрес.

Если параметр пустой или отсутствует, то отчет будет содержать результаты по всем адресам

groupAddressArrivalНетboolean

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

Если значение параметра "groupAddressArrival" = "true" и:

  • параметр "addressArrival" пустой или отсутствует, тогда результаты в отчете будут сгруппированы по всем адресам доставки;
  • в параметре "addressArrival" передан адрес доставки, тогда результаты в отчете будут сгруппированы по указанному адресу.

Значение по умолчанию: "false".

Чтобы осуществлялась данная группировка, в массиве "reportParams" должен быть передан параметр "arrivalAddress"

terminalIDНетinteger

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

Если параметр пустой или отсутствует, то отчет будет содержать результаты по всем терминалам

groupTerminalНетboolean

Признак группировки результатов отчета по терминалу выдачи груза.

Если значение параметра "groupTerminal" = "true" и:

  • параметр "terminalID" пустой или отсутствует, тогда результаты в отчете будут сгруппированы по всем терминалам;
  • в параметре "terminalID" передан терминал выдачи, тогда результаты в отчете будут сгруппированы по указанному терминалу.

Значение по умолчанию: "false".

Чтобы осуществлялась данная группировка, в массиве "reportParams" должен быть передан параметр "arrivalTerminal"

senderCounteragentIDНетinteger

ID КА-отправителя груза.

Если параметр пустой или отсутствует, то отчет будет содержать результаты по всем КА-отправителям

groupSenderНетboolean

Признак группировки результатов отчета по отправителю груза.

Если значение параметра "groupSender" = "true" и:

  • параметр "senderCounteragentID" пустой или отсутствует, тогда результаты в отчете будут сгруппированы по всем отправителям;
  • в параметре "senderCounteragentID" передан ID КА-отправителя, тогда результаты в отчете будут сгруппированы по указанному КА.

Значение по умолчанию: "false".

Чтобы осуществлялась данная группировка, в массиве "reportParams" должен быть передан параметр "senderName"

receiverCounteragentIDНетinteger

ID КА-получателя груза.

Если параметр пустой или отсутствует, то отчет будет содержать результаты по всем КА-получателям

groupReceiverНетboolean

Признак группировки результатов отчета по получателю груза.

Если значение параметра "groupReceiver" = "true" и:

  • параметр "receiverCounteragentID" пустой или отсутствует, тогда результаты в отчете будут сгруппированы по всем получателям;
  • в параметре "receiverCounteragentID" передан ID КА-получателя, тогда результаты в отчете будут сгруппированы по указанному КА.

Значение по умолчанию: "false".

Чтобы осуществлялась данная группировка, в массиве "reportParams" должен быть передан параметр "receiverName"

payerCounteragentIDНетinteger

ID КА-плательщика.

Если параметр пустой или отсутствует, то отчет будет содержать результаты по всем КА-плательщикам

groupPayerНетboolean

Признак группировки результатов отчета по плательщику.

Если значение параметра "groupPayer" = "true" и:

  • параметр "payerCounteragentID" пустой или отсутствует, тогда результаты в отчете будут сгруппированы по всем плательщикам;
  • в параметре "payerCounteragentID" передан ID КА-плательщика, тогда результаты в отчете будут сгруппированы по указанному КА.

Значение по умолчанию: "false".

Чтобы осуществлялась данная группировка, в массиве "reportParams" должен быть передан параметр "payerName"

Ответ метода

Пример ответа

{  
   "reportNumber":"12345"
}
<response>
   <reportNumber>12345</reportNumber>
</response>

Описание параметров

Response
ПараметрТипОписание
reportNumberstringНомер отчета

Обработка ошибок

Если в запросе один из параметров был передан некорректно, то вернётся соответствующее сообщение об ошибке. Например, если передан некорректный 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-000000000000",
   "sessionID":"00000000-0000-0000-0000-000000000000",   
   "reportNumber":"12345"
}

Адрес метода: https://api.dellin.ru/v1/customers/get_report.xml

<request>
   <appkey>00000000-0000-0000-000000000000</appkey>
   <sessionID>00000000-0000-0000-0000-000000000000</sessionID>
   <reportNumber>12345</reportNumber>
</request>

Описание параметров

Request
ПараметрR*ТипОписание
appkeyДаstringКлюч приложения. Для получения ключа необходимо пройти регистрацию
sessionIDДаstringID сессии. Для получения сессии необходимо воспользоваться методом "Авторизация пользователя"
reportNumber
ДаstringНомер отчета, по которому необходимо получить информацию. Номер отчета можно получить с помощью метода "Инициализация формирования отчета"

Ответ метода

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

Пример ответа - Запрос не сформирован

{  
   "reportState":"queue"
}
<response>
   <reportState>queue</reportState>
</response>

Описание параметров

Response
ПараметрТипОписание
reportStatestring

Статус отчета.

Возможные значения:

  • "queue" - в очереди (запрос находится в очереди на обработку)
  • "processing" - в процессе (запрос поступил в обработку)
  • "finished" - отчет сформирован и доступен на сервере

Для данного случая вернется значение "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

Статус отчета.

Возможные значения:

  • "queue" - в очереди (запрос находится в очереди на обработку)
  • "processing" - в процессе (запрос поступил в обработку)
  • "finished" - отчет сформирован и доступен на сервере

Для данного случая вернется значение "finished"

reportobjectСсылки на отчет в форматах json, xml и xlsx
reportJSONstringСсылка на отчет в формате json
reportXMLstringСсылка на отчет в формате xml
reportXLSXstringСсылка на отчет в формате 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
ПараметрТипНаименование параметра в отчетеОписание
datedateДата оформления заявки/накладной

Дата создания заявки.

Формат даты: "ГГГГ-ММ-ДД"

numberstringНомер заявки/накладнойНомер заявки/накладной
derivalPointstringГород отправкиГород отправки груза
arrivalPointstringГород прибытияГород прибытия груза
arrivalAddressstringАдрес доставкиАдрес доставки груза
arrivalTerminalstringТерминал выдачиОСП и адрес ОСП
freightNamestringНаименование грузаХарактер груза
quantityintegerКоличество местКоличество мест в одной грузоперевозке по заказу
volumefloatОбщий объемОбщий объем груза
weightfloatОбщий весОбщий вес груза
shippingCostfloatСумма ПНОбщая стоимость грузоперевозки по ПН, руб
deliveryCostfloatСумма НВОбщая стоимость грузоперевозки по НВ, руб
insuranceSumfloatСтраховкаСтоимость страховки, руб
discountSumfloatСкидкаСумма скидки, руб
senderobjectОтправительКА-отправитель
sender.senderNamestringОтправительНаименование КА-отправителя
sender.senderInnintegerОтправительИНН КА-отправителя
receiverobjectПолучательКА-получатель
receiver.receiverNamestringПолучательНаименование КА-получателя
receiver.receiverInnintegerПолучательИНН КА-получателя
realReceiverstringФактический получательФактический получатель груза
payerobjectПлательщикКА-плательщик
payer.payerNamestringПлательщикНаименование КА-плательщика
payer.payerInnintegerПлательщикИНН КА-плательщика
blockstringБлокировкаНаличие блокировок по заказу. Дата и вид блокировки
warehousingstringПлатное хранениеДата начала и стоимость платного хранения
statestringСтатусСтатус накладной/заказа/заявки
accompanyingDocumentsstringСопроводительные документыДанные по сопроводительным документам
commentstringКомментарий к ПНКомментарий к ПН
serviceKindstringВид перевозкиВид услуги: авто, авиа, экспресс и тд.

Рассмотрим пример отчета, при формировании которого была запрошена группировка и выборка данных. Например, запрос метода "Инициализация формирования отчета" имел следующий вид:

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

Адрес метода: https://api.dellin.ru/v1/customers/create_report.json

{  
   "appkey":"00000000-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-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>
Параметры отчета соответствуют параметрам отчета, сформированного без запроса выборки и группировки.