Подключиться

Для разработчиков

Авторизация и начало работы

API парсель доступно по URL https://api.parcelle.ru/. Взаимодействие с API происходит по протоколу https и RESTFUL.

Для работы с API вам потребуется API-ключ. Чтобы получить ключ напишите нам через форму обратной связи.

Отслеживание посылок

Что умеет:

  • Определять транспортную компанию по трек-номеру
  • Возвращать информацию от транспортной компании в JSON-формате
  • Обрабатывать от 1 до 100 трек-номеров в одном запросе.
  • Приводить к единому формату справочные данные транспортных компаний: статус отправления, местоположение, дата/время, параметры груза и возможные ошибки.

Что пока не умеет:

  • Отслеживать по номеру заказа интернет-магазина
  • Обращаться под договором с транспортной компанией другого ЮЛ (не Parcelle)

Варианты использования

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

Метод: GET

URL:

https://api.parcelle.ru/tracking/getsync?n=ваш_трекномер

Пример кода:

curl -X GET
     --header 'Accept: application/json'
     --header 'X-ApiKey: ваш_API_ключ'
https://api.parcelle.ru/tracking/getsync?n=ваш_трекномер

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

 

Последовательность действий:

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

Метод: POST

URL:

https://api.parcelle.ru/tracking/gettoken

Тело запроса:

"TrackingNumbers":
     [
         "ваш_трекномер",
         "ещё_один_трекномер",
         ...
     ]

Пример кода:

curl -X POST
     --header 'Content-Type: application/json' 
      --header 'Accept: application/json' 
      --header --header 'X-ApiKey: ваш_API_ключ'
          -d '{
             "TrackingNumbers": [
             "ваш_трекномер",
             "ещё_один_трекномер"
             ]
          }'
     'https://api.parcelle.ru/tracking/gettoken'

2. Получение информации по токену

Метод: GET

URL:

https://api.parcelle.ru/getresult?token=ваш_токен

Пример кода:

curl -X GET
     --header 'Accept: application/json'
     --header 'X-ApiKey: ваш_API_ключ'
https://api.parcelle.ru/tracking/getresult?token=ваш_токен

Формат ответа:

Количество элементов в массиве Items зависит от количества трек-номеров в запросе.

Тип данных datetime представлен в формате YYYY-MM-DDThh:mm:ss.fffzzz. Часовой пояс +03:00.

Общая информация

DeliveryCompanyName — Название транспортной компании (string)
DeliveryCompanyCode — Код транспортной компании (string)
TrackingNumber — Запрашиваемый трек-номер (string)
ErrorCode — Код ошибки отслеживания по трек-номеру (string)
ErrorText — Текст ошибки отслеживания по трек-номеру (string)
OriginalError — Текст ошибки, полученный от транспортной компании (string)

О текущем местоположении отправления

CurrentStatus — Информация о текущем статусе груза (string)
DeliveryStatusName — Текущий статус отправления (string)
DeliveryStatusCode — Код текущего статуса (string)
OriginalDeliveryStatus — Текст статуса, полученный от транспортной компании (string)
FlagFinalStatus — Флаг, является ли статус финальным (boolean)
DeliveryStatusDate — Дата и время присвоения статуса (datetime)
CurrentLocationName — Текущее местоположение груза (string)
CurrentLocationCode — Код текущего местоположения груза (string)
OriginalLocation — Текущее местоположение груза, полученной от транспортной компании (string)

О точке отправки

DepartureStatusName — Наименование статуса отправления груза (string)
DepartureStatusCode — Код статуса отправления груза (string)
OriginalDepartureStatus — Наименования статуса отправления груза, полученное от транспортной компании (string)
DepartureLocationName — Местоположение пункта отправления (string)
DepartureLocationCode — Код местоположения пункта отправления (string)
OriginalLocation — Местоположение пункта отправления, полученное от транспортной компании (string)
DepartureDate — Дата и время отправки (datetime)
TakeOnStockDate — Дата получения отправления транспортной компанией (datetime)

О месте назначения

ExpectedDeliveryDate — Планируемая дата доставки (datetime)
DestinationLocationName — Местоположение пункта назначения (string)
DestinationLocationCode — Код местоположения пункта назначения  (string)
OriginalLocation — Местоположение груза, полученное от транспортной компании (string)
DeliveryPointAddress — Адрес пункта выдачи заказов (string)
WorkingHours — Часы работы пункта выдачи заказов (string)
StorageToDate — Дата до которой груз будет храниться на складе пункта выдачи заказов (datetime)

Об отправлении

Weight — Вес в граммах (numeric)
Volume — Объем в сантиметрах кубических (numeric)
CargoType — Тип груза (string)
PayOnDeliveryFlag — Флаг наложенного платежа (boolean)

О запросе

Token — Токен запроса (string)
RequestDate — Дата и время запроса (datetime)
RequestErrorText — Текст ошибки запроса (string)
RequestErrorCode — Код ошибки запроса  (string)
RequestState — Состояние запроса (string)

Рекомендации по работе с API

  • После выполнения запроса проверяйте RequestState. Возможные состояния: New, InProgress, Done, Failed
  • Если RequestState = Failed, то сервис не смог обработать запрос, более подробная информация будет отражена в RequestErrorText. Процесс разбора ответа API Parcelle можно прекратить
  • RequestState = New означает, что сервис работает с вашbм запросом, но пока не было получено ответа от транспортной компании (ТК)
  • RequestState = InProgress означает, что по части трек-номеров из вашего запроса был получен ответ от ТК,  а часть еще находится в обработке. Обработанные трек-номера уже доступны в ответе API Parcelle
  • RequestState = Done означает, что был получен ответ от ТК и можно разбирать массив Items
  • При разборе элементов массива Items проверяйте ErrorText/Code, если это поле отлично от null, то API ТК вернуло ошибку, следовательно все остальные поля элемента массива будут пустыми

В API установлено ограничение на 10 запросов в секунду с одного аккаунта. Если приходит большее количество запросов, то API возвращает ответ с http-статус кодом 429. Если вам необходимо большее количество, то напишите нам

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

В API Parcelle можно получить информацию по следующим справочникам

  • Список транспортных компаний (код справочника — DeliveryCompany)
  • Список городов и населённых пунктов (Geography)
  • Список статусов отправлений (TrackingStatus)
  • Список ошибок (Errors)

Метод: GET

URL:

https://api.parcelle.ru/dict/код_справочника

Пример кода:

curl -X GET
     --header 'Accept: application/json'
     --header 'X-ApiKey: ваш_API_ключ'
https://api.parcelle.ru/dict/код_справочника