Как да регистрирате номер за проследяване чрез API: полета на заявката, кодове на превозвачите и отговори
За да регистрирате номер за проследяване чрез API, изпратете удостоверена заявка за регистрация, съдържаща номера за проследяване на пратката и, когато е необходимо, идентификатор на превозвача. След това проверете отговора за всяка изпратена пратка — не само HTTP статуса — и запишете дали регистрацията е успешна, неуспешна или остава несигурна. Регистрацията стартира работния процес по проследяване; тя не доказва, че превозвачът е сканирал пратката или че събитията за проследяване вече са налични.
Това ръководство е предназначено за разработчици, които свързват система за управление на поръчки, складово приложение или платформа за електронна търговия с API за проследяване. В него 17TRACK се използва като конкретен пример за интеграция и се обяснява кои подробности трябва да бъдат проверени в документацията за избраната от вас версия на API.
Какво прави регистрацията — и какво не прави
Заявката за регистрация указва на услугата за проследяване коя пратка искате да бъде проследявана. Тя се различава от закупуването на транспортен етикет, резервирането на вземане или заявяването към превозвач да създаде пратка. При типична интеграция работният процес по изпращане първо генерира номер за проследяване, а след това приложението ви регистрира този номер.
Разграничете тези три събития във вашето приложение:
- Пратката е създадена: вашата система за изпращане е присвоила номер за проследяване.
- Регистрацията е приета: услугата за проследяване е приела пратката за проследяване.
- Получена е информация за проследяване: събитията от превозвача са станали достъпни чрез услугата за проследяване.
Не променяйте статуса на поръчката на „в транзит“ само защото регистрацията е успешна. Новосъздаденият етикет може все още да няма физическо сканиране при приемане. Статусът на пратката, показван на клиентите, трябва да се определя от събитията за проследяване, интерпретирани чрез вашите правила за съпоставяне на статуси, а не от отговора при регистрация.
За интеграции с 17TRACK започнете с прегледа на Tracking API и използвайте официалната API документация като авторитетен източник за крайните точки, дефинициите на полетата, удостоверяването и кодовете на отговорите. Примерите по-долу са съсредоточени върху регистрацията, а не върху отделните задачи за получаване на резултати или приемане на актуализации.
Подгответе полетата на заявката, преди да напишете API извикването
Най-полезната подготовка е малък договор за полетата между системата ви за изпращане и интеграцията за проследяване. Определете откъде произлиза всяка стойност, дали може да липсва и как ще бъде валидирана.
| Поле или стойност | Предназначение | Правило за реализация |
|---|---|---|
| Номер за проследяване | Идентифицира пратката, която трябва да бъде проследявана. | Съхранявайте и предавайте като низ; запазвайте водещите нули. |
| Идентификатор на превозвача | Идентифицира превозвача в системата на доставчика на проследяване. | Използвайте документирания от доставчика идентификатор, а не вътрешен складов код. |
| Вътрешна референция | Свързва регистрацията със записа на вашата пратка. | Използвайте поддържано референтно поле, ако е налично; независимо от това запазете собственото си съпоставяне в базата данни. |
| Допълнителни идентификационни данни | Могат да помогнат за идентифициране на пратка, когато превозвачът изисква повече от нейния номер за проследяване. | Изпращайте само полета, документирани за тази интеграция и превозвач. |
| API идентификационни данни | Удостоверяват извикващия акаунт. | Съхранявайте ги на сървъра и ги изключвайте от логовете на приложението. |
Третирайте номера за проследяване като идентификатор
Никога не преобразувайте номер за проследяване в цяло число. Числовото преобразуване може да премахне водещите нули, а големите стойности могат да загубят точност в някои програмни среди. Премахвайте случайните интервали в началото и края, но не премахвайте пунктуация и не променяйте регистъра на буквите, освен ако съответната документация или форматът на превозвача не поддържа такава нормализация.
Валидирайте очевидните входни грешки, преди да извикате API: празни низове, неочаквани нови редове и номер на поръчка, копиран в полето за номер за проследяване. Избягвайте налагането на едно универсално правило за дължина или символи за всички превозвачи. Правило, подходящо за един превозвач, може да отхвърли валидни номера на друг.
Дръжте референциите на поръчките отделно от идентичностите на пратките
Една поръчка може да има множество колети, а заместваща пратка може да въведе друг номер за проследяване. Моделирайте регистрацията на ниво пратка или колет, вместо да предполагате по един номер за проследяване на поръчка.
Ако използвате поддържано от доставчика поле за етикет или референция, предпочитайте непрозрачна референция на пратката вместо имейл адрес или уличен адрес на клиента. Собствената ви база данни трябва да остане авторитетната връзка между поръчките, пратките, номерата за проследяване и съпоставянията на превозвачите.
Изберете правилния код на превозвача
Кодът на превозвача не е непременно универсален отраслов идентификатор. Стойността, разпознавана от платформата за проследяване, може да се различава от името на превозвача, съхранявано във вашия софтуер за изпращане. Дори две системи, които използват цифрови кодове, могат да присвоят различни номера на един и същ превозвач.
Поддържайте изрично съпоставяне от вашата услуга за изпращане към идентификатора на превозвача на доставчика на проследяване. Когато е необходимо, различавайте регионалната дейност или услугата на превозвача от по-широката му марка. Съпоставяне, основано само на показвано име, може да стане двусмислено, когато системите за изпращане използват псевдоними.
- Когато превозвачът е известен: използвайте документирания идентификатор на превозвача, когато се поддържа, особено когато форматите на номерата за проследяване се припокриват.
- Когато превозвачът е неизвестен: използвайте автоматично откриване само чрез документирания механизъм. Не приемайте, че пропускането, празният низ, нулата и null означават едно и също.
- Когато резултатът изглежда неправилен: проверете оригиналния етикет, услугата за изпращане и съпоставянето, преди да регистрирате многократно същия номер.
Автоматичното откриване е полезно, но не е доказателство, че конкретен превозвач физически държи пратката. По същия начин валидният код на превозвача не гарантира, че предоставеният номер за проследяване принадлежи на този превозвач.
Поддържайте съпоставянията на превозвачите конфигурируеми, вместо да ги разпръсквате в кода на приложението. Записвайте кога дадено съпоставяне е проверено за последно и включвайте известна пратка в регресионните тестове при всяка промяна.
Пример: изпращане на заявка за регистрация към 17TRACK
Следващият пример илюстрира крайната точка за регистрация на 17TRACK v2.2, заглавката за удостоверяване 17token и масив, съдържащ един обект с номер за проследяване. Потвърдете, че тази версия и изискванията ѝ към заявката съответстват на вашия акаунт и официалната документация, преди внедряване. Номерът за проследяване е заместител и трябва да бъде заменен с реален идентификатор на пратка.
curl --request POST \
--url 'https://api.17track.net/track/v2.2/register' \
--header "17token: ${TRACKING_API_TOKEN}" \
--header 'Content-Type: application/json' \
--data '[
{
"number": "YOUR_TRACKING_NUMBER"
}
]'
Този минимален пример не демонстрира избор на превозвач или специфични за превозвача допълнителни полета. Проверете документацията за регистрация, за да определите как работи откриването на превозвача, когато полето за превозвач е пропуснато, и дали вашата пратка се нуждае от допълнителна информация. Ако предоставяте превозвач, използвайте документираното поле carrier и идентификатора, очакван от тази версия на API.
Изпълнявайте тази заявка от сървърна среда. Не вграждайте токена в публичен онлайн магазин, браузърен скрипт или мобилно приложение, разпространявано до клиенти. Променлива на средата е удобна за локален пример; производствените внедрявания трябва да използват механизмите за управление на секрети на вашата организация.
Преди да увеличите обема, тествайте една известна пратка и проверете пълния отговор. След това тествайте невалиден вход и пакет, съдържащ както валидни, така и невалидни елементи. Тези проверки показват дали интеграцията ви действително обработва резултатите на ниво елемент, а не просто разпознава успешен HTTP отговор.
Прочетете отговора на три нива
Надеждният обработчик на отговори отговаря на три отделни въпроса: достигна ли заявката до услугата, прие ли услугата операцията и какво се случи с всяка пратка?
1. Резултат от HTTP и транспорта
Изтичане на времето за връзка, TLS грешка или прекъснат отговор не ви казват непременно дали сървърът е обработил заявката. Маркирайте този резултат като несигурен, докато не можете да го съгласувате. Успешният HTTP статус потвърждава успешен HTTP обмен, но все пак трябва да проверите отговора на приложението.
2. Резултат на ниво заявка
Проверете документираните от API резултат и полета за грешки на най-високо ниво. Грешките при удостоверяване, неправилният JSON и ограниченията на акаунта изискват различни действия. Съхранявайте оригиналния код и съобщение за грешка на доставчика, вместо да свеждате всеки отказ до „проследяването не е налично“.
Не приемайте, че цифровият код на приложението има същото значение като HTTP статус кода. Значенията им идват от различни слоеве и трябва да се интерпретират отделно.
3. Резултат на ниво пратка
При пакетна регистрация отчетете всеки изпратен елемент. Отговорът може да различава приети и отхвърлени пратки; анализаторът ви трябва да следва точната схема, документирана за избраната версия. Не маркирайте целия пакет като регистриран само защото един елемент е успешен.
Нормализирайте отговорите на доставчика във ваши стабилни състояния на приложението. Например базата ви данни може да използва accepted, rejected и uncertain. Това са предложени вътрешни състояния, а не буквални стойности в отговорите на 17TRACK. Запазвайте оригиналния отговор на доставчика съгласно подходяща политика за съхранение и достъп, така че разработчиците да могат да проучват несъответствия.
Полезният запис за регистрация съдържа вътрешния идентификатор на пратката, изпратения номер, избора на превозвач, часа на опита, версията на API, резултата и подробностите за грешката на доставчика. Дръжте статуса на регистрация отделно от статуса на доставка.
Обработвайте повторните опити, без да създавате безкраен цикъл
Политиката за повторни опити трябва да зависи от грешката, а не просто от това дали е възникнало изключение.
- Невалиден вход: коригирайте полето, преди да повторите опита. Повтарянето на непроменена неправилна заявка е малко вероятно да помогне.
- Неуспешно удостоверяване: проверете идентификационните данни и конфигурацията на акаунта. Избягвайте многократно изпращане на същия неуспешен пакет.
- Ограничаване на честотата: следвайте документираните ограничения и всички приложими инструкции за повторен опит. Използвайте ограничено обратно изчакване вместо незабавни паралелни повторения.
- Временна повреда на услугата: повторете опита в рамките на определен бюджет за брой опити и време.
- Изтичане на времето след изпращане: съгласувайте състоянието на регистрацията на пратката чрез документираното поведение на API, преди да приемете, че първият опит е неуспешен.
- Отговор, свързан с дубликат: проверете дали пратката вече е регистрирана и правилно свързана със записа на приложението ви.
Не приемайте, че регистрацията е идемпотентна, освен ако документацията не определя такова поведение. Дедупликацията на ниво приложение намалява случайните повторни изпращания, но не определя политиката на доставчика за обработка на дубликати.
Използвайте вътрешно правило за уникалност, подходящо за вашия модел на пратките. Самият номер за проследяване може да не е достатъчен постоянен ключ при различни превозвачи и дълги периоди на съхранение. Запазвайте контекста на превозвача и собствения си идентификатор на пратката и документирайте как се обработват заместващи и коригирани номера.
Наблюдавайте регистрацията отделно от актуализациите за проследяване
Наблюдението на API трябва да разграничава неуспешна интеграция от пратка, за която просто няма ново събитие от превозвача. Тези състояния изискват различни отговорни екипи и различни решения.
За регистрацията наблюдавайте броя на приеманията и отхвърлянията, категориите грешки, несигурните резултати, опашката за повторни опити и латентността на отговорите. За последващото проследяване наблюдавайте отделно получаването на актуализации или грешките при извличане. Не задавайте числови прагове за известия, преди да разберете нормалния трафик и документираните експлоатационни ограничения на доставчика.
Практическата производствена проверка трябва да отговаря на следните въпроси:
- Има ли запис за регистрация за всяка пратка, която чака проследяване?
- Може ли всяка приета регистрация да бъде проследена обратно до правилния колет?
- Насочват ли се отхвърлените елементи към човек, който може да коригира основните данни?
- Съгласуват ли се несигурните заявки, вместо да бъдат изоставяни или повтаряни безкрайно?
- Извеждат ли се клиентските статуси от събитията на пратката, а не от приемането на регистрацията?
- Изключени ли са идентификационните данни и ненужната лична информация от логовете?
За операциите по електронна търговия оперативното предаване е също толкова важно, колкото и API извикването. Разработчиците трябва да отговарят за транспортните грешки и грешките при анализиране; екипите по изпращане или изпълнение на поръчки трябва да могат да разследват неправилни етикети, съпоставяния на превозвачи и липсваща информация за пратките.
Често задавани въпроси
Мога ли да регистрирам номер за проследяване преди първото сканиране от превозвача?
Регистрацията и сканиранията от превозвача са отделни събития. Услугата може да приеме номер, преди да са налични събития за проследяване, в зависимост от правилата ѝ за валидиране. Не тълкувайте приемането като доказателство, че превозвачът е получил пратката.
Винаги ли трябва да предоставям код на превозвач?
Това зависи от документираното поведение на API за откриване и от конкретната пратка. Ако превозвачът е известен, изрично посочен и правилно съпоставен идентификатор може да намали двусмислието. Ако е неизвестен, използвайте документирания метод за автоматично откриване, вместо да измисляте стойност за превозвач.
Защо API върна HTTP успех, докато дадена пратка беше неуспешна?
HTTP заявката може да е успешна, докато приложението отхвърля отделен елемент. Прочетете резултата на приложението на най-високо ниво и резултатите на ниво пратка. Това разграничение е особено важно при пакетни заявки.
Какво трябва да направя, когато заявка за регистрация изтече?
Третирайте резултата като несигурен. Сървърът може да е обработил заявката, преди връзката да прекъсне. Проверете документираното поведение на доставчика при дубликати и наличните методи за справка за регистрация или проследяване, след което съгласувайте или повторете опита съгласно ограничена политика.
Регистрацията автоматично ли конфигурира известията за проследяване?
Не приемайте, че е така. Регистрацията, извличането на информация за проследяване и конфигурирането на webhook са отделни интеграционни въпроси. Проверете съответната документация и тествайте целия път на актуализацията, преди да разчитате на него за клиентски известия.
Източници
- Документация на 17TRACK API — справочник за крайните точки за регистрация, удостоверяването, полетата на заявките, идентификаторите на превозвачите, схемите на отговорите и обработката на грешки. Съобразете детайлите на реализацията с версията на API, която внедрявате.
- Преглед на 17TRACK Tracking API — официална отправна точка за продукта Tracking API и ресурсите за интеграция на разработчици.


