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

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

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

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

Использование 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], но мы не гарантируем получение ответа.