ГдеПосылка предоставляет вам новый упрощенный 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"