Отслеживание посылок на Вашем сайте с API от Track24.ru
У Вас есть сайт связанный с покупками в интернет-магазинах или Вы владелец интернет-магазина?
Хотите повысить лояльность Ваших посетителей или клиентов Вашего магазина?
Подключите трекинг посылок от Track24.ru и это поможет Вам уменьшить количество возвращенных посылок, а также улучшить информированность, а следовательно и лояльность ваших клиентов.
С помощью нашего API, Вы и Ваши клиенты сможете отслеживать почтовые отправления почты России, Украины, Беларуси, Казахстана, а также из Китая, Гонкога, Сингапура, США и других стран.
Наши преимущества
- На сегодняшний день мы подключили и успешно отслеживаем трек-коды 650+ международных почтовых компаний и курьерских служб, это больше чем у любого аналогичного сервиса, как Российского так и зарубежного.
- Автоматическое определяем какими службами доставки мог бы доставляться отслеживаемый трек-код.
- Работа серверов 24/7, 365 дней в году, с практически 100% uptime.
Использование API
API (интерфейс программирования приложений) - это набор инструментов для автоматизированной работы с «Track24.ru». Функциональность API позволяет быстро интегрировать отслеживание почтовых отправлений в любое приложение / web сайт и является единственной точкой входа для всех клиентов и сервисов.
Все запросы к API отправляются по защищенному HTTPS протоколу методом GET с вашим API ключом.
Получение ключа API
Прежде чем начать пользоваться нашими API службами, Вам необходимо зарегистрироваться и получить API ключ.
- Войдите в свой аккаунт Track24 или зарегистрируйтесь, если это необходимо.
- Перейдите на страницу API.
- Выберите вкладку Документация и Api ключ будет сгенерирован автоматически.
- После быстрой регистрации, и получения API ключа, Вы можете приступить к использованию API
Ваш API ключ
Точка входа JSON
https://api.track24.ru/tracking.json.php
Отправка запросов
Запросы необходимо отправлять на точку входа, при этом необходимо указывать Ваш API ключ, имя домена с которого делается запрос, и трек-код.
apiKey: Ваш API ключ
domain: example.com
code: LC166805240CN
Пример формирования строки отправки запроса:
https://api.track24.ru/tracking.json.php?apiKey=В ответе на сформированный запрос, API отдаст всю доступную информацию по указанному трек-коду.[apiKey] &domain=you-domain-name.com&pretty=true&code=LC166805240CN
Ответы API
Результат обработки запроса отдается в формате JSON.
Пример ответа API в случае успеха выглядит следующим образом:
... {"status":"ok", "data":{ "events":[ {"id":"544", "operationDateTime":"02.07.2014 19:16:00", "operationAttribute":"Прибыло в место вручения", "operationPlacePostalCode":"101100", "operationPlaceName":"Москва 100", "operationType":"Прибыло в место вручения", "itemWeight":"45", "source":"cnpost" }] } ... }
Формат ответа
Объект содержит следующий набор полей:status
- статус ответа API;data
- массив объектов с доступной информацией по указанному трек-коду;
"status" : "ok"
, в случае ошибки "status": "error"
с описанием ошибки "message" : "Описание ошибки"
Если Вы отправили корректный запрос, ответ будет содержать объект
"data"
со следующими данными:"data": { "trackCreationDateTime": "", (дата и время первого отслеживания) "trackUpdateDateTime": "", (дата и время последнего отслеживания) "trackUpdateDiffMinutes": 0, (количесто минут с момента последнего отслеживания) "trackAwaitingDateTime": "", (дата и время прибытия в место вручения) "trackDeliveredDateTime": "", (дата и время прибытия в место вручения) "fromCountryCode": "", (код страны отправителя ISO 3166) "fromCountry": "", (страна отправителя) "fromName": "", (имя отправителя) "destinationName": "", (имя получателя) "destinationCountryCode": "", (код страны назначения ISO 3166) "destinationCountry": "", (страна назначения) "destinationPostalCode": "", (почтовый индекс получателя) "fromCity": "", (город отправителя) "destinationCity": "", (город получателя) "fromAddress": "", (адрес отправителя) "destinationAddress": "", (адрес получателя) "collectOnDeliveryPrice": "", (сумма наложенного платежа) "declaredValue": "", (объявленная стоимость) "trackCodeModified": "", (Перемаркированный трек-код) "deliveredStatus": "0", (флаг информирующий о вручении получателю 0/1) "awaitingStatus": "0", (флаг информирующий о прибытии в место вручения 0/1) "awaiting": false, (true/false флаг информирующий о прибытии в место вручения, устарело и будет удалено) "itemWeight": 0, (вес в граммах) "trackFirstOperationDateTime": "", (дата и время первого статуса) "daysInTransit": 5, (дней в пути) "daysTracking": 17, (кол-во дней с момента первого отслеживания)"events": [...]
, (массив со статусами отсортированными по дате и времени проведения операции)"groupedEvents": [...]
, (массив со статусами сгруппированными в отдельные массивы по перевозчикам)"groupedCompanyNames": [...]
, (названия перевозчиков из массива статусов сгруппированных по перевозчикам)"lastPoint": {...}
(объект с информацией из последнего статуса) }, "services": [], (массив с кодами служб перевозчиков) "deliveredStat": null, "id": "", (id запроса - отладочная информация) "rpm": 0, (количество запросов за последние 60 секунд с вашего API ключа) "totalTime": 0.000 (затраченное время)
Описание массивов
"events": [...]
, "groupedEvents": [...]
, "groupedCompanyNames": [...]
, "lastPoint": {...}
:events: массив со статусами отсортированными по дате и времени проведения операции
"events": [ ... { "id": "", (id события) "eventDateTime": "", (дата и время получения статуса) "operationDateTime": "", (дата и время проведения операции) "operationAttribute": "", (операция) "operationType": "", (тип операции) "operationPlacePostalCode": "", (почтовый индекс проведения операции) "operationPlaceName": "", (место проведения операции) "itemWeight": "", (вес) "source": "", (код службы перевозчика) "serviceName": "", (название перевозчика) "operationAttributeOriginal": "", (операция на языке полученном от перевозчика) "operationTypeOriginal": "", (тип операции на языке полученном от перевозчика) "operationPlaceNameOriginal": "", (место проведения операции на языке полученном от перевозчика) "operationAttributeTranslated": "", (перевод операции на язык выбранный параметромlng
) "operationTypeTranslated": "", (перевод типа операции на язык выбранный параметромlng
) "operationPlaceNameTranslated": "" (перевод место проведения операции на язык выбранный параметромlng
) "operationAttributeInformation": "", (справочная информация на русском языке об операции) "icon": "" (тип операции для визуализации в вашем приложении, смотрите таблицу ниже) } ... ]
icon: возможны следующие значения
Значение | Нормализировано из статуса |
---|---|
info-received | Электронная регистрация почтового отправления |
accepted | Прием |
arrived-to-warhouse | Прибыло на склад |
departed-from-warhouse | Покинуло склад |
arrived-at-sorting-center | Прибыло в сортировочный центр |
processing | Обработка |
departed-from-sorting-center | Покинуло сортировочный центр |
hand-over-to-air | Передано авиакомпании |
arrived-at-international-exchange | Прибыло в место международного обмена |
departed-from-international-exchange | Покинуло место международного обмена |
export | Экспорт |
send-to-destination | Отправлено в страну назначения |
arrived-in-destination | Прибыло в страну назначения |
import | Импорт |
customs-clearance | Таможенное оформление |
customs-complete | Выпущено таможней |
customs-warning | Направлено с таможенным уведомлением |
time | Ожидает отправки со склада |
exception | Отмена отгрузки |
attempt-fail | Неудачная попытка вручения |
awaiting | Прибыло в место вручения |
delivered | Вручение получателю |
"groupedEvents": [ [ (массив со статусами первого перевозчика) { (статусы полученные от первого перевозчика) } ... ], [ (массив со статусами второго перевозчика) { (статусы полученные от второго перевозчика) } ... ], [ (массив со статусами третьего перевозчика) { (статусы полученные от третьего перевозчика) } ... ], ... ]
groupedCompanyNames: - названия перевозчиков из массива статусов сгруппированных по перевозчикам
"groupedCompanyNames": [ "", (название первого перевозчика) "", (название первого перевозчика) "", (название первого перевозчика) ],lastPoint: - объект с информацией из последнего статуса
"lastPoint": { "id": "", (id события) "eventDateTime": "", (дата и время получения статуса) "operationDateTime": "", (дата и время проведения операции) "operationAttribute": "", (операция) "operationType": "", (тип операции) "source": "", (код службы перевозчика) "serviceName": "" (название перевозчика) }
Для получения информации только о последнем статусе, отправьте запрос с параметром lastPoint
Пример формирования строки отправки запроса:
https://api.track24.ru/tracking.json.php?apiKey=[apiKey] &pretty=true&lastPoint=true&code=LC166805240CN
Webhooks
Создание списка трек-кодов с отслеживанием на нашей стороне и уведомлениями на ваш webhook url
Для того чтобы добавить трек-код в список ваших трек-кодов, отправьте его c параметром add
add: true
code: [трек-код]
name: [описание трек-кода]
Пример формирования строки отправки запроса:
https://api.track24.ru/tracking.json.php?apiKey=При успешной обработке запроса, вы получите ответ сервера[apiKey] &add=true&code=LC166805240CN&name=order+12345
"status" : "ok"
, в случае ошибки "status": "error"
с описанием ошибки "message" : "Описание ошибки"
Повторный запрос с параметром add, обновляет информацию о трек-коде в списке, таким образом Вы можете изменить описание трек-кода и возобновить отслеживание в случае его прекращения по истечении 60 дней.
Добавленные трек-коды начнут автоматически отслеживаться на нашей стороне.
В случае получения новых статусов на ваш webhook url будет отправлена вся информация о трек-коде, аналогичная той, которую можно получить при отслеживании.
Для удаления трек-кода, отправьте запрос c параметром delete
delete: true
code: [трек-код]
Пример формирования строки отправки запроса:
https://api.track24.ru/tracking.json.php?apiKey=[apiKey] &add=true&code=LC166805240CN
Для получения списка трек-кодов, отправьте запрос c параметром getList
getList: true
Пример формирования строки отправки запроса:
https://api.track24.ru/tracking.json.php?apiKey=Пример ответа:[apiKey] &getList=true
{ "status": "ok", "data": { "id": xx, (ваш user id) "apiKey": "[apiKey] ", "trackingNumbers": [ { "code": "RF123456789SG", (трек-код) "name": "order 101", (описание трек-кода) "added": "2023-05-29 03:34:55", (дата и время добавления в список) "tracking": "2023-05-29 03:34:55", (дата и время отслеживания) "awaiting": false, (флаг информирующий о прибытии в место вручения true/false) "delivered": false (флаг информирующий о вручении получателю true/false) }, { "code": "CB987654321RU", "name": "order 102", "added": "2023-05-28 23:31:56", "tracking": "2023-05-29 03:45:00", "awaiting": false, "delivered": false } ], "count": 2 (общее количество трек-кодов в списке) }, "totalTime": 0.0001 (затраченное время) }
Возможные ошибки:
В случае ошибки, вы получите ответ с описанием ошибки:{ "status":"error", "message":"Invalid API key!" }Возможные ошибки
Значение | Описание |
---|---|
Invalid API key | Некорректный ключ API |
Non-existent API key! | Несуществующий ключ API |
Server too busy. Please try again later | Сервер перегружен, попробуйте позже |
Selected services not found | Выбрана несуществующая служба |
apiKey | Доступ с ключем |
Domain ... is blocked | Домен заблокирован |
IP is blocked | IP Заблокирован |
Bad request | некорректный запрос |
Too Many Requests | Превышено количество запросов |
Track code not valid | Некорректный трек-код |
Domain is NULL | Не указан домен |
Лимиты
Если Вы будете отправлять большое количество запросов, то получите ошибку информирующую Вас о превышении количества запросов (Too Many Requests).
'error' : 'Too Many Requests'
В данный момент, для базовой версии API установлены следующие лимиты:
- 1 запрос / сек
- 10 запросов / мин
- 100 запросов / в сутки
- 500 запросов / в месяц
Кэш и период обновления трек-кодов (актуально для интернет-магазинов)
Почтовые системы очень редко обновляют статусы почтовых отправлений, в среднем это происходит 1 раз в 1 - 3 дня.
Мы рекомендуем запрашивать информацию о трек-коде не чаще, чем один раз в сутки.
Отслеживания трек-кодов по выбранным компаниям
Для отслеживания только по одной компании (для уменьшения времени отслеживания) используйте параметр
selectedServiceОтслеживая по выбранной компании, Вы можете уменьшить время отслеживания цифровых трек-кодов (без букв) в десятки раз, т.к. цифровые трек-коды попадают под шаблоны более 60 компаний перевозчиков, на автоматическое определение перевозчика может быть затрачено от 60 до 300 секунд.
Примеры:
https://api.track24.ru/tracking.json.php?...&selectedService=intru https://api.track24.ru/tracking.json.php?...&selectedService=cdek https://api.track24.ru/tracking.json.php?...&selectedService=pec https://api.track24.ru/tracking.json.php?...&selectedService=gtd https://api.track24.ru/tracking.json.php?...&selectedService=rupost https://api.track24.ru/tracking.json.php?...&selectedService=uapost https://api.track24.ru/tracking.json.php?...&selectedService=hkpost https://api.track24.ru/tracking.json.php?...&selectedService=nlpost https://api.track24.ru/tracking.json.php?...&selectedService=lcmexpПримеры запросов:
https://api.track24.ru/tracking.json.php?apiKey=Также Вы можете передавать список служб через запятую:[apiKey] &pretty=true&domain=you-domain-name.com&code=LC166805240CN&selectedService=rupost https://api.track24.ru/tracking.json.php?apiKey=[apiKey] &pretty=true&domain=you-domain-name.com&code=LC166805240CN&selectedService=sgpost https://api.track24.ru/tracking.json.php?apiKey=[apiKey] &pretty=true&domain=you-domain-name.com&code=44501953810073&selectedService=intru https://api.track24.ru/tracking.json.php?apiKey=[apiKey] &pretty=true&domain=you-domain-name.com&code=1202847332&selectedService=cdek https://api.track24.ru/tracking.json.php?apiKey=[apiKey] &pretty=true&domain=you-domain-name.com&code=СРТЛВЯГ-1/1011&selectedService=pec https://api.track24.ru/tracking.json.php?apiKey=[apiKey] &pretty=true&domain=you-domain-name.com&code=ТЛТКСВ0100298615&selectedService=gtd
selectedService=rupost,uapost selectedService=cdek,pec,gtdПримеры запросов:
https://api.track24.ru/tracking.json.php?apiKey=[apiKey] &domain=you-domain-name.com&code=LC166805240CN&selectedService=rupost,sgpost https://api.track24.ru/tracking.json.php?apiKey=[apiKey] &pretty=true&domain=you-domain-name.com&selectedService=cdek,pec,gtd&code=1202847332 https://api.track24.ru/tracking.json.php?apiKey=[apiKey] &pretty=true&domain=you-domain-name.com&selectedService=cdek,pec,gtd&code=СРТЛВЯГ-1/1011 https://api.track24.ru/tracking.json.php?apiKey=[apiKey] &pretty=true&domain=you-domain-name.com&selectedService=cdek,pec,gtd&code=ТЛТКСВ0100298615
Получить список подключенных служб (код службы / название службы) можно получить сделав запрос с параметром
getShippers=trueПример запроса:
https://api.track24.ru/tracking.json.php?getShippers=true
Формат ответа
Если Вы отправили корректный запрос, ответ будет содержать следующие данные:"status":"ok", "data": { "shippers": { "all": {...}, массив содержащий список всех ранее подключенных перевозчиков "active": {...}, массив содержащий список подключенных в данный момент перевозчиков "disabled": {...} массив содержащий список отключенных в данный момент перевозчиков }, "count": { "all": 0, (кол-во всех ранее подключенных перевозчиков) "active": 0, (кол-во подключенных в данный момент перевозчиков) "disabled": 0 (кол-во отключенных в данный момент перевозчиков) }, }, "id": xx (id запроса) "totalTime": 0.000 (затраченное время)При успешной обработке запроса, вы получите ответ сервера
"status" : "ok"
, в случае ошибки "status": "error"
с описанием ошибки "message" : "Описание ошибки"
Выбор страны назначения
Если страна назначения не определилась в автоматическом режиме, Вы можете указать страну назначения принудительно.
Код страны назначения необходимо передавать параметром destinationCountryCode в соответствии со стандартом ISO 3166 - Alpha 2
Примеры запросов:
destinationCountryCode=RU destinationCountryCode=UA destinationCountryCode=KZ destinationCountryCode=CNПолучение списка подключенных стран
getCountries=trueПример запроса:
https://api.track24.ru/tracking.json.php?getCountries=true
Выбор языка статусов
По умолчанию результаты статусов отдаются на языке почтовых компаний (значения "operationAttributeOriginal", "operationTypeOriginal", "operationPlaceNameOriginal"),
для получения результатов отслеживания с переводом необходимо указывать язык.
Поддерживаемые языки в данный момент: русский, английский, украинский, португальский, итальянский, испанский, французский, немецкий, польский и нидерландский.
Обращаем Ваше внимание, согласно ISO 639-1, для украинского необходимо указывать код uk, а не ua.
lng=ru lng=en lng=uk lng=pt lng=it lng=es lng=fr lng=de lng=pl lng=nlПримеры запросов:
https://api.track24.ru/tracking.json.php?apiKey=[apiKey] &domain=you-domain-name.com&pretty=true&code=LC166805240CN&lng=ru https://api.track24.ru/tracking.json.php?apiKey=[apiKey] &domain=you-domain-name.com&pretty=true&code=LC166805240CN&lng=en
Cтатистика использования API
0.00 ₽
Подключение сервиса приема данных: Webhooks
Получайте уведомления на свой собственный сервис приема и обработки данных без затрачивания ресурсов на отслеживание.
- Добавьте ссылку на скрипт приема уведомлений.
- Ссылка на скрипт должна быть доступна и скрипт должен отвечать в течение пяти секунд, в противном случае вы получите ответ с ошибкой.
- Рекомендуем использовать защищенный протокол HTTPS.
- После добавления webhook ссылки вы сможете добавить трек-коды в ваш список отслеживания.
- Все добавленные трек-коды будут автоматически отслеживаться на нашей стороне несколько раз в сутки.
- Отслеживание прекращается через 60 дней после добавления в список ваших трек-кодов или при получении статуса о вручении.
- При получени новых статусов, на ваш обработчик будет отправлятся вся информация о трек-коде, аналогичная той, которую можно получить при отслеживании.
- Вы можете добавлять, редактировать, удалять и просматривать информацию по трек-кодам как в ручном режиме в разделе Webhook так и при помощи отправки запросов на Track24 API.
Установка виджета на свой сайт
Для установки виджета необходимо сделать 3 простых шага:
1. Подключить js скрипт:
<script type="text/javascript" language="javascript" src="https://api.track24.ru/track24widget.js?v=1.76"></script>
2. Настроить виджет:
<script type="text/javascript">
var track24Options = {
'apiKey' : '[apiKey] ' /* необходимо указать свой apiKey */,
'widgetId' : 'track24widget',
'domain' : 'you-domain-name.com',
'inputId' : 'track24Input',
'buttonId' : 'track24Button',
'resultId' : 'track24Result',
'useCss' : true,
'validate' : true,
'language' : 'ru',
'restoreLastTrackingNumber' : true
};
</script>
3. Добавить HTML код элемента, в который будет встраиваться виджет:
<div id="track24widget"></div>
Пример работы установленного виджета (для демонстрации работы виджета, необходимо авторизоваться)
Виджет сохраняет последний запрос в cookies, для отключение измените параметр restoreLastTrackingNumber с true на false.
Пример работы установленного виджета на отдельной странице: https://track24.net/demo.widget/
Модификация виджета
Если Вы хотите изменить расположение формы и выдачи результата трекинга, Вам необходимо вместо элемента с id="track24widget" самостоятельно вставить форму ввода трек-кода, и элемент выдачи результата трекинга в любое удобное место, на Вашей странице.
Пример:
<!-- Форма ввода трек-кода, устанавливается в любое, удобное место на вашей странице --> <form id="track24Form"> <input id="track24Input" type="text" value="" placeholder="Пример: 17010075171291"> <button id="track24Button" type="submit">Отследить</button> </form> <!-- Элемент выдачи результата трекинга, устанавливается в любое, удобное место на вашей странице --> <div id="track24Result" class="track24Result"></div>
Если Вы не хотите подключать наш css, укажите значение false в настройках подключения виджета.
'useCss' : false
И настройте css на свой вкус и цвет.
#track24Input { } #track24Button { } .track24Result { } .track24Result-Title { } .track24Result-Events { } .track24Result-Row { } .track24Result-Status { } .track24Result-DateTime { } .track24Result-Date { } .track24Result-Time { } .track24Result-Operations { } .track24Result-OperationAttribute { } .track24Result-OperationType { } .track24Result-Place { } .track24Result-OperationPlacePostalCode { } .track24Result-operationPlaceName { } .track24Result-copyright { } .track24Result-copyright-link { }
Пример работы API в Google таблицах + google apps-script
Пример apps script для google таблиц: track24API.gs
Пример: google таблиц + apps script (для корректной работы необходимо авторизоваться в google)
Условия использования базовой (бесплатной) версии Track24 API
- При использовании виджета, не допускается удаление строк кода отвечающих за вывод блока с копирайтом.
Мы рекомендуем подгружать track24widget.js, с ресурса https://api.track24.ru.
- На странице с установленным виджетом или при использовании API, необходимо установить активную и видимую без прокрутки посетителям сайта (или приложения) гиперссылку на track24.ru
Ссылка не должна быть закрыта тегами noindex, параметром nofollow, без использования JavaScript и т.д.
Пример: Информация об отслеживании предоставлена сервисом track24.ru
- Строка "Информация предоставлена сервисом Track24.ru" должна быть видна пользователям.
- При подключении к API, запрещается указывать вымышленные (не принадлежащие Вам) имена доменов, использовать несколько аккаунтов, proxy серверов и других технологий для обхода лимитов.
- API предназначено для использования торговыми площадками и интернет-магазинами, не допускается использование API для создания сервисов отслеживания посылок и подобных систем.
Лимиты
В данный момент, для базовой версии API установлены следующие лимиты:
- 1 запрос / сек
- 10 запросов / мин
- 100 запросов / в сутки
- 500 запросов / в месяц
При нарушении условий использования API, а также при значительном превышении лимитов, Ваш аккаунт может быть заблокирован.
Благодарим вас за использование Track24 API
Track24.ru оставляет за собой право обновлять и изменять данные Условия API или любые документы, которые включаются в данный документ путем ссылки.
Вы всегда можете найти самую последнюю версию данных Условий API на странице https://track24.ru/?page=api#apiRules
Track24.ru может изменять данные Условия API путем публикации новой версии.
Использование Track24 API после подобных изменений означает, что вы приняли эти изменения.
Цены
В сутки | В месяц | Стоимость | Сумма в месяц |
---|---|---|---|
>1 | >1 | 4 ₽ | от 4 ₽ |
>30 | >900 | 3 ₽ | от 2'700 ₽ |
>100 | >3'000 | 2 ₽ | от 6'000 ₽ |
>500 | >15'000 | 1 ₽ | от 15'000 ₽ |
>1500 | >45'000 | 0.95 ₽ | от 42'750 ₽ |
>5'000 | >150'000 | 0.90 ₽ | от 135'000 ₽ |
>10'000 | >300'000 | 0.85 ₽ | от 255'000 ₽ |
>15'000 | >450'000 | 0.80 ₽ | от 360'000 ₽ |
>30'000 | >900'000 | 0.75 ₽ | от 675'000 ₽ |
>50'000 | >1'500'000 | 0.70 ₽ | от 1'050'000 ₽ |
Калькулятор использования API
-
Трек-кодов в месяц:1'000
-
Трек-кодов в сутки:33
-
Запросов в месяц:∞
-
Стоимость отслеживания:3 ₽
-
Итого:3'000 ₽
Отказ от Copyright, снятие лимитов и предоставление полного доступа ко всем 650 компаниям подключенных к нашему сервису, предоставляется на платной основе.
Стоимость отслеживания каждого трек-кода зависит от общего количества отслеживаемых трек-кодов за месяц.
Расчеты производятся ежемесячно, исходя из суммы уникальных трек-кодов, все повторные запросы Вы делаете абсолютно бесплатно.
Таким образом, чем больше трек-кодов вы отслеживаете, тем ниже стоимость.
Мои трек-коды
- Сохранять историю отслеживания
- Получать бесплатные уведомления об изменении статусов трек-кодов
- А также, для доступа ко всем функциям системы Track24.ru
Регистрация займет не более 20 секунд.
Попробуйте, это несложно! ;)