Бесплатное API отслеживания посылок ГдеПосылка.Ру

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

ГдеПосылка предоставляет вам новый упрощенный API для отслеживания посылок. Все запросы к API представляют из себя обычные HTTP-запросы, но для доступа всё ещё нужен ключ, который можно получить здесь.
Ответ всегда будет приходить в виде JSON.

Правила использования. Правила использования API всё ещё не разработаны, но API точно не разрешается использовать для (1) разработки мобильных приложений,
(2) ботов для социальных сетей,
(3) отслеживания личных посылок,
(4) сервисов отслеживания посылок (если это является основным функционалом проекта).

Использование API ограничено — 2 тысячи запросов с новыми треками в день. Проверять старые треки можно не превышая лимит 30 запросов в минуту.

API предоставляется без гарантий. Мы не гарантируем бесперебойной работы сервиса, качества информации и т.п. Хотя мы и стараемся поддерживать качество, вы используете API на свой страх и риск.

Каждый запрос обязательно должен содержать следующие заголовки:

X-Authorization-Token: ВАШ_API_КЛЮЧ
Content-Type: application/json

В случае ошибки ответ будет выглядеть вот так:

{
  "result": "error",
  "error": "Invalid token",
  "messages": []
}

Типы данных

Служба доставки

`slug`	Уникальный код службы.
`name`	Название службы.
`name_alt`	Альтернативное название службы.
`country_code`	Код страны, в которой находится служба.

Результат определения службы

`tracking_number`	Трекинг-номер, приведенный к правильному виду.
`courier`	Объект «Служба доставки».
`tracker_url`	URL по которому можно запросить информацию о трекинг-номере для указанной службы.

Результат отслеживания посылки (Трек)

`id`	Внутренний идентификатор трека.
`tracking_number`	Трекинг-номер.
`courier`	Объект «Служба доставки».
`is_active`	Флаг, указывающий отслеживается ли трек в данный момент или отслеживание остановлено.
`is_delivered`	Флаг, указывающий была ли посылка доставлена или все еще находится в пути.
`last_check`	Дата последней проверки трекинг-номера, формат `Y-m-d H:i:s`, или `null` если первая проверка пока не закончена.
`checkpoints`	Массив объектов «Контрольная точка».
`extra`	Массив объектов «Дополнительная информация о треке».

Контрольная точка

`time`	Время прохождения посылки через контрольную точку, формат `Y-m-d H:i:s`.
`courier`	Объект «Служба доставки».
`status_code`	Код статуса посылки, если этот код `other`, то статус не классифицирован, если `null`, то статус мы пока не обработали.
`status_name`	Название статуса, которое можно отображать пользователю. Если код `other` или `null`, то отображается сырой статус.
`status_raw`	Сырой статус, полученный от службы доставки.
`location_translated`	Местоположение, обработанное и переведенное нами. `null`, если мы этого не сделали.
`location_raw`	Сырое местоположение, полученное от службы доставки.
`location_zip_code`	Почтовый индекс местоположения.

Дополнительная информация о посылке

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

Доступные службы доставки

GET https://gdeposylka.ru/api/v4/couriers

Метод служит для определения какой службе доставки принадлежит трек. Причем служб, которым соответстует трек может быть несколько. В результате возможны несколько ситуаций:

Формат успешного ответа

`result`	Результат определения, может быть только `success`.
`length`	Количество служб доставки в ответе.
`data`	Массив объектов «Служба доставки».

Успешный ответ

{
  "result": "success",
  "length": 73,
  "data": [
    {
      "slug": "russian-post",
      "name": "Почта России",
      "name_alt": null,
      "country_code": "RUS"
    },
    {
      "slug": "hongkong-post",
      "name": "Почта Гонконга",
      "name_alt": "Hong Kong Post",
      "country_code": "HKG"
    },
    [ .. ]
  ]
}

Определение службы по трек-номеру

GET https://gdeposylka.ru/api/v4/tracker/detect/_AA00000000AA_

Формат успешного ответа

`result`	Результат определения, может быть `success`, `unsure`, `unknown`.
`length`	Количество служб доставки в ответе.
`tracking_number`	Трекинг-номер для которого определялись службы доставки.
`data`	Массив объектов «Результат определения службы».

Служба успешно опознана

{
  "result": "success",
  "length": 1,
  "tracking_number": "ftl02045437MY",
  "data": [
    {
      "tracking_number": "FTL02045437MY",
      "courier": {
        "slug": "malaysia-post",
        "name": "Почта Малайзии",
        "name_alt": "Malaysia Post",
        "country_code": "MYS"
      },
      "tracker_url": "https://gdeposylka.ru/api/v4/tracker/malaysia-post/FTL02045437MY
    },
    [ .. ]
  ]
}

Служба определена неточно

{
  "result": "unsure",
  "length": 35,
  "tracking_number": "EC201092176RO",
  "data": [
    {
      "tracking_number": "EC201092176RO",
      "courier": {
        "slug": "usps",
        "name": "Почта США",
        "name_alt": "USPS",
        "country_code": "USA"
      },
      "tracker_url": "https://gdeposylka.ru/api/v4/tracker/usps/EC201092176RO"
    },
    {
      "tracking_number": "EC201092176RO",
      "courier": {
        "slug": "singapore-post",
        "name": "Почта Сингапура",
        "name_alt": "Singapore Post",
        "country_code": "SNG"
      },
      "tracker_url": "https://gdeposylka.ru/api/v4/tracker/singapore-post/EC201092176RO"
    },
    [ .. ]
  ]
}

Служба не определена

{
  "result": "unknown",
  "length": 0,
  "tracking_number": "EC20106RO",
  "data": [ ]
}

Отслеживание посылке по службе и трек-номеру

GET https://gdeposylka.ru/api/v4/tracker/_slug_/_AA00000000AA_

Формат успешного ответа

`result`	Результат отслеживания, может быть `success` или `waiting`. Если `waiting` — попробуйте отследить посылку через 3-5 минут, информация должна будет появиться.
`data`	Объект «Результат отслеживания посылки».
`messages`	Массив строк, служит исключительно для отладки.

Пример ответа свежедобавленного трека

{
  "result": "waiting",
  "data": {
    "id": 6574343,
    "tracking_number": "LM951174329CN",
    "courier": {
      "slug": "china-post",
      "name": "Почта Китая",
      "country_code": "CHN"
    },
    "is_active": true,
    "is_delivered": false,
    "last_check": null,
    "checkpoints": [],
    "extra": []
  },
  "messages": [
    "Tracking number not found in database, trying to fix...",
    "Fixed tracking number not found in database, trying to add...",
    "Tracking number added to database!",
    "We're collecting first info about this tracking number. Please try again little later."
  ]
}

Пример успешного ответа

{
  "result": "success",
  "data": {
    "id": 3617843,
    "tracking_number": "LM951174328CN",
    "courier": {
      "slug": "china-post",
      "name": "Почта Китая",
      "name_alt": "China Post",
      "country_code": "CHN"
    },
    "is_active": false,
    "is_delivered": true,
    "last_check": "2015-07-29 19:42:15",
    "checkpoints": [
      {
        "time": "2015-07-28 19:35:00",
        "courier": {
          "slug": "russian-post",
          "name": "Почта России",
          "name_alt": null,
          "country_code": "RUS"
        },
        "status_code": "delivered",
        "status_name": "Посылка доставлена",
        "status_raw": "Вручение - Вручение адресату",
        "location_translated": "Воронеж 88",
        "location_raw": "Воронеж 88",
        "location_zip_code": "394088"
      },
      {
        "time": "2015-07-27 09:29:00",
        "courier": {
          "slug": "russian-post",
          "name": "Почта России",
          "name_alt": null,
          "country_code": "RUS"
        },
        "status_code": "other",
        "status_name": "Неудачная попытка вручения - Временное отсутствие адресата",
        "status_raw": "Неудачная попытка вручения - Временное отсутствие адресата",
        "location_translated": "Воронеж 88",
        "location_raw": "Воронеж 88",
        "location_zip_code": "394088"
      },
      [ .. ],
      {
        "time": "2015-07-16 12:29:00",
        "courier": {
          "slug": "china-post",
          "name": "Почта Китая",
          "name_alt": "China Post",
          "country_code": "CHN"
        },
        "status_code": "accepted",
        "status_name": "Посылка принята",
        "status_raw": "收寄",
        "location_translated": "Shenzhen post office express couriers",
        "location_raw": "深圳市邮政局速递公司",
        "location_zip_code": null
      }
    ],
    "extra": [
      {
        "courier_slug": "russian-post",
        "data": {
          "weight": "",
          "weight.volume": 0,
          "weight.actual": "73",
          "weight.dimensions": "",
          "weight.seats": 0,
          "recipient.title": "Anton Vladimirovich Vlasov",
          "recipient.location.title": "Воронеж, Воронежская обл.",
          "recipient.location.zip_code": "394088",
          "recipient.location.phone": "",
          "sender.title": "",
          "sender.location.title": "",
          "sender.location.zip_code": "",
          "delivery": "",
          "delivery.service_name": "",
          "specific": "",
          "specific.russian-post": "",
          "specific.russian-post.finance": "",
          "specific.russian-post.finance.payment": 0,
          "specific.russian-post.finance.value": 0,
          "specific.russian-post.finance.mass_rate": 0,
          "specific.russian-post.finance.insr_rate": 0,
          "specific.russian-post.finance.air_rate": 0,
          "specific.russian-post.finance.rate": 0,
          "specific.russian-post.item": "",
          "specific.russian-post.item.complex_item_name": "Мелкий пакет заказной",
          "specific.russian-post.item.mail_rank": "Без разряда",
          "specific.russian-post.item.mail_type": "Мелкий пакет",
          "specific.russian-post.item.post_mark": "Без отметки",
          "specific.russian-post.item.mail_category": "Заказное"
        }
      },
      [ .. ]
    ]
  },
  "messages": [
    "Tracking number found in database!"
  ]
}

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

Получить список служб доставки:
curl https://gdeposylka.ru/api/v4/couriers -H "X-Authorization-Token: AUTH_TOKEN"

Определить службу доставки для трека:
curl https://gdeposylka.ru/api/v4/tracker/detect/9361289878909410176578 -H "X-Authorization-Token: AUTH_TOKEN"

Пример трека с неточным определением:
curl https://gdeposylka.ru/api/v4/tracker/detect/CD005181905RO -H "X-Authorization-Token: AUTH_TOKEN"

Отслеживание посылки:
curl https://gdeposylka.ru/api/v4/tracker/usps/9361289878909410176578 -H "X-Authorization-Token: AUTH_TOKEN"

Отслеживание посылки с дополнительной информацией:
curl https://gdeposylka.ru/api/v4/tracker/china-post/LM951174328CN -H "X-Authorization-Token: AUTH_TOKEN"

Техническая поддержка

Вопросы, предложения и сообщения о проблемах, пожалуйста, пишите на Форуме разработчиков.
У нас нет платных услуг и индивидуальных условий, мы не отвечаем на подобные вопросы на форуме и в поддержке.
Мы не оказываем индивидуальных консультаций по интеграции API.
Если у вас есть срочный вопрос или интересное предложение: пишите на [email protected], но мы не гарантируем получение ответа.

ГдеПосылка.API v4 beta

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

Типы данных

Служба доставки

Результат определения службы

Результат отслеживания посылки (Трек)

Контрольная точка

Дополнительная информация о посылке

Доступные службы доставки

Формат успешного ответа

Успешный ответ

Определение службы по трек-номеру

Формат успешного ответа

Служба успешно опознана

Служба определена неточно

Служба не определена

Отслеживание посылке по службе и трек-номеру

Формат успешного ответа

Пример ответа свежедобавленного трека

Пример успешного ответа

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

Техническая поддержка

ГдеПосылка.API v4 ^beta