Как да изпращате множество номера за проследяване в една API заявка (ограничения на пакетите и частични неуспехи)
За да изпратите множество номера за проследяване в една API заявка, използвайте крайна точка на Tracking API, която изрично приема пакетни заявки, форматирайте всяка пратка според схемата на заявката и разделете по-дългите списъци на пакети в рамките на документираните ограничения. След това проверете както HTTP отговора, така и резултата за всяка пратка: успешната HTTP заявка не означава непременно, че всеки номер за проследяване е приет. Повторете опита само за допустимите грешки и изяснете несигурните резултати, преди да изпратите отново целия пакет.

Това ръководство е предназначено за разработчици, които свързват проследяването на пратки със система за управление на поръчки, складова платформа, приложение за електронна търговия или вътрешно табло. Целта не е просто да изпращате по-малко заявки. Трябва да отчетете всяка пратка, без да създавате дублираща се работа или да губите неуспешните записи.
Първо установете какво всъщност прави пакетната крайна точка
Една интеграция за проследяване може да включва няколко различни операции. Регистрирането на пратки, извличането на последната информация за проследяване и получаването на последващи актуализации не са взаимозаменяеми.
- Регистрация: Изпращате пратки, за да може услугата да започне или да поддържа проследяването им.
- Проверка: Заявявате информация за проследяване на пратки съгласно правилата за извличане на крайната точка.
- Актуализиране на доставката: Получавате последващи промени чрез поддържан механизъм, например webhooks, или ги извличате чрез планирани заявки.
Проверете документацията за точната операция, от която се нуждаете. Крайна точка за регистрация, която приема множество записи, не доказва, че крайна точка за проверка приема същия брой записи, използва същата схема или има същото ограничение на честотата.
За интеграция с 17TRACK започнете с продуктовата страница на Tracking API и използвайте официалната API документация, за да потвърдите операцията, метода за удостоверяване, формата на заявката и полетата в отговора. Разглеждайте примерите по-долу като модели за реализация, а не като заместител на договора на API.
Ограниченията на пакетите включват повече от максималния брой пратки
Няма универсално ограничение за пакетите в Tracking API. Ограниченията могат да се различават според доставчика, крайната точка, версията на API и конфигурацията на акаунта. Преди да реализирате пакетна обработка, запишете тези ограничения отделно.
| Ограничение | Какво да потвърдите | Последица за реализацията |
|---|---|---|
| Елементи на заявка | Максималният брой записи за конкретната операция | Разделете входния списък преди изпращане |
| Размер на тялото на заявката | Всяко документирано ограничение в байтове | Вземете предвид незадължителните полета и размера след сериализация |
| Честота на заявките | Разрешеният брой заявки за определен интервал | Регулирайте заявките чрез общ ограничител |
| Едновременност | Всяко ограничение за едновременни заявки | Ограничете броя на активните работници |
| Отчитане на използването | Дали използването се брои по заявка, пратка или друга единица | Оценявайте потреблението отделно от обема на заявките |
Например, ако хипотетична крайна точка позволява 25 записа на заявка, 63 записа изискват три заявки, съдържащи съответно 25, 25 и 13 записа. Тези числа илюстрират разделянето на части; те не са посочени ограничения на 17TRACK.
Не приемайте, че пакетната обработка намалява таксуваното използване. Тя може да намали разходите за HTTP заявки, но влиянието върху таксите зависи от действителните правила на доставчика. По същия начин валидният размер на пакет не разрешава неограничен брой паралелни заявки.
Подгответе записите, преди да изградите заявката
Повечето предотвратими грешки при пакетна обработка започват с подготовката на входните данни. Валидирайте всяка пратка, преди да я добавите към пакет, но избягвайте правила, които случайно отхвърлят валидни номера за проследяване от различни превозвачи.
- Съхранявайте номерата за проследяване като низове. Преобразуването им в числа може да премахне водещите нули или да промени дългите идентификатори.
- Премахвайте случайните интервали в началото и края. Не премахвайте вътрешни символи и не променяйте регистъра, освен ако съответната спецификация не разрешава такава нормализация.
- Валидирайте задължителните полета. Някои работни процеси може да изискват идентификатор на превозвач или допълнителна информация за пратката. Използвайте само документирани имена и стойности на полета.
- Определете изричен обхват за премахване на дубликати. Повтарящият се номер за проследяване не е автоматично дубликат за всеки превозвач, търговец или историческа пратка.
- Съхранявайте локален идентификатор на пратката. Запазете връзката между изпращания елемент и записа за поръчката или пратката, дори когато API не приема персонализирани референтни полета.
При Carrier Tracking в множество мрежи не определяйте превозвача единствено по дължината или префикса на номера за проследяване, освен ако това заключение е надеждно за конкретния ви работен процес. Когато API поддържа идентифициране на превозвач, следвайте документираното поведение при нееднозначност.
Илюстративна структура на заявка
Следващият JSON показва концепцията за пакетен payload. Обвивката, имената на свойствата и идентификаторите са илюстративни, а не схема на заявка за 17TRACK. Някои API очакват масив на най-горно ниво вместо обект, съдържащ масив.
{
"shipments": [
{
"tracking_number": "EXAMPLE000001",
"carrier_id": "DOCUMENTED_CARRIER_ID"
},
{
"tracking_number": "EXAMPLE000002",
"carrier_id": "DOCUMENTED_CARRIER_ID"
}
]
}Изграждайте payload чрез JSON сериализатор, а не чрез слепване на низове. Изпращайте идентификационните данни чрез документирания механизъм и не ги съхранявайте в системата за контрол на версиите, код, доставян до браузъра, или стандартни логове.
Обработвайте отговора на две нива
Пакетната заявка има резултат на транспортно ниво и резултат на ниво приложение. Интеграцията ви трябва да оцени и двете.
Ниво 1: Получи ли заявката използваем отговор?
Започнете с HTTP статуса, заглавките на отговора и тялото на отговора. Грешки при удостоверяване, неправилно форматирани заявки, ограничаване на честотата и сървърни грешки могат да възпрепятстват нормалната обработка на елементите. Мрежовото изтичане на времето е различно: клиентът може да не знае дали сървърът е получил или обработил заявката.
Семантиката на HTTP е дефинирана в RFC 9110. Документацията на доставчика обаче определя как полетата с резултати на ниво приложение се свързват с действителните резултати за пратките.
Ниво 2: Какво се случи с всяка пратка?
Ако отговорът поддържа резултати на ниво елемент, класифицирайте всеки изпратен запис. Не приемайте, че HTTP 200 означава успех за всеки запис или че списъкът с резултати запазва реда на заявката, освен ако договорът изрично не гарантира това.
- Приет: Операцията е успешна според документираната дефиниция на крайната точка.
- Постоянна входна грешка: Коригирайте или проучете записа, преди да направите нов опит.
- Грешка, подлежаща на повторен опит: Планирайте нов опит съгласно указанията на доставчика.
- Неизвестен резултат: Отговорът липсва, непълен е или не може безопасно да бъде съпоставен с изпратения запис.
Дръжте отговорите като „вече регистриран“ или други подобни отговори, свързани с дубликати, отделно, докато не разберете документираното им значение. Те може да показват, че желаното състояние вече съществува, но не трябва автоматично да се приемат като потвърждение за собственост, конфигурация или абонамент.
След обработката на отговора всеки входен запис трябва да има точно един локален резултат. Полезна проверка за съгласуване е: изпратените записи са равни на приетите записи плюс постоянните грешки плюс грешките за повторен опит плюс неизвестните резултати. Това е локално счетоводно правило, а не задължителен формат на отговора от API.
Обработвайте частичните грешки, без да повтаряте успешните записи
Да предположим, че илюстративен пакет съдържа десет пратки: седем са приети, две имат невалидни задължителни полета, а една среща документирана временна грешка. Запазете седемте успешни резултата, изпратете двата невалидни записа за корекция и повторете опита само за временната грешка.
Повторното изпращане на всичките десет записа създава ненужен трафик и може да усложни обработката на дубликати. То също така затруднява разграничаването на първоначално отхвърляне от последващ отговор, свързан с дубликат.
| Резултат | Препоръчително действие |
|---|---|
| Невалидно поле или неподдържана стойност | Коригирайте входните данни; не повтаряйте опита без промяна |
| Грешка при удостоверяване или разрешенията | Спрете засегнатата работа и коригирайте идентификационните данни или достъпа |
| Отговор за ограничение на честотата | Изчакайте според документираните указания и приложимите заглавки на отговора |
| Временна грешка на ниво елемент | Повторете опита за този елемент с ограничен брой опити и експоненциално изчакване |
| Изтичане на времето след изпращане | Маркирайте резултата като несигурен; съгласувайте го или използвайте документирани гаранции за безопасно повторение |
| Неразпознат или непълен резултат | Запазете доказателствата и проучете случая, вместо да приемате успех |
HTTP 429 означава твърде много заявки и отговорът може да съдържа заглавка Retry-After, както е описано в RFC 6585. Не приемайте, че тази заглавка винаги присъства. Когато не е посочено изрично време за повторен опит, използвайте ограничена политика за изчакване, съвместима с документацията на API.
Добавете случайно отклонение, за да разпределите повторните опити от множество работници, задайте максимален брой опити или максимална възраст на повторението и изпращайте изчерпаните записи в опашка за преглед. Безкрайното повтаряне може да прикрие постоянен проблем с конфигурацията.
Защо изтичането на времето изисква специален подход
Изтичането на времето не доказва отхвърляне. Сървърът може да е приел пакета, преди връзката да прекъсне. Следователно автоматичното повторно изпращане на заявка, която променя състояние, може да повтори работата.
Ако крайната точка поддържа документирани ключове за идемпотентност, следвайте правилата ѝ, включително обхвата и срока на съхранение на ключа. Не измисляйте заглавка за идемпотентност и не приемайте, че сървърът я спазва. В противен случай използвайте поддържан работен процес за проверка или съгласуване, за да определите дали желаното състояние съществува, преди да изпратите отново заявката. Локалното премахване на дубликати помага за координиране на собствените ви работници, но не гарантира идемпотентност от страна на сървъра.
Практически работен процес за пакетна обработка
Съхранявайте специфичните за доставчика подробности в адаптер, така че логиката за опашката, планирането на повторните опити и мониторинга да не зависи от необработените имена на полетата в отговора.
валидирайте записите и запазете локалните идентификатори на пратките
разрешете дубликатите в рамките на целевия бизнес обхват
разделете записите според документираните ограничения за елементи и payload
за всеки пакет чрез ограничен пул от работници:
запазете запис за опита преди изпращане
изчакайте общия ограничител на честотата
изпратете чрез специфичния за доставчика адаптер
ако резултатът е несигурен:
добавете към опашката за съгласуване
продължете
класифицирайте резултатите на ниво заявка и елемент
запазете един резултат за всеки изпратен запис
планирайте повторен опит само за допустимите грешки
изпратете невалидните или изчерпаните записи за преглед
Направете съхраняването на резултатите и планирането на повторните опити възстановими. Например надежден запис на задача или транзакционен модел за поставяне в опашка може да предотврати загубата на решението за повторен опит при срив на процеса. При рестартиране работниците трябва да могат да разграничат неизпратената работа от работата, чийто отдалечен резултат все още е несигурен.
Използвайте размера на пакета като конфигурируема настройка, свързана със съответната крайна точка, а не като константа, разпръсната из кодовата база. По-малък пакет може да е полезен при отстраняване на проблеми или изолиране на проблемни записи; най-големият разрешен пакет не е автоматично най-добрият работен размер.
Наблюдавайте резултатите за пратките, а не само достъпността на HTTP
API Monitoring трябва да показва дали пратките достигат желаното състояние. Табло, което отчита само процента успешни HTTP заявки, може да пропусне частични грешки в иначе успешни отговори.
- Процент на приемане на елементи: Приетите записи, разделени на изпратените записи, с ясно определено третиране на повторните опити.
- Разпределение на грешките: Броеве по крайна точка, документиран код на грешка и релевантен контекст на превозвача.
- Неизвестни резултати: Несъгласувани записи и времето, през което са останали нерешени.
- Опашка за повторни опити: Чакащи повторения, възраст на най-старото повторение и изчерпани опити.
- Състояние на заявките: Латентност, изтичане на времето, ограничаване на честотата и сървърни грешки.
- Актуалност на проследяването: Дали приетите пратки впоследствие получават използваема информация за проследяване.
Приемането на регистрация не е доказателство за ново сканиране от превозвача. Дръжте статуса на обработката от API отделно от движението на пратката и актуалността на данните, за да не бъде инцидент в интеграцията объркан със забавяне на доставката.
Записвайте локалните идентификатори на пакетите, референциите на пратките, броя опити, документираните кодове на грешки и идентификаторите на заявките към доставчика, когато са налични. Маскирайте идентификационните данни и ненужната лична информация. Използвайте идентификаторите за проследяване само когато са оперативно необходими и избягвайте да поставяте необработени идентификатори на пратки в етикети на метрики с висока кардиналност.
Тествайте тези случаи преди продукция
Използвайте документирана sandbox среда или контролирана тестова среда, когато е налична. Не приемайте, че измислените номера за проследяване ще предизвикат предвидими отговори в продукция.
- Изпратете валиден пакет с документирания лимит за елементи, след което проверете как клиентът ви предотвратява прекалено голям пакет.
- Уверете се, че номерата за проследяване с водещи нули оцеляват при сериализация и съхранение.
- Тествайте смесени приети и отхвърлени елементи, без да повтаряте успешните записи.
- Симулирайте ограничаване на честотата и потвърдете, че множество работници спазват едно и също ограничение.
- Симулирайте изтичане на времето след изпращане и проверете пътя за съгласуване.
- Рестартирайте работник между получаването на отговора и локалното му съхранение.
- Тествайте липсващи, непознати или несъпоставими резултати на елементи.
- Потвърдете, че невалидните записи достигат видима опашка за корекция, вместо да се повтарят безкрайно.
Готовата за продукция интеграция може да обясни състоянието на всяка изпратена пратка, включително тези, чийто резултат временно е неизвестен. Намаляването на броя заявки е полезно; запазването на тази отчетност е по-важната цел на дизайна.
Често задавани въпроси
Колко номера за проследяване мога да изпратя в една заявка?
Използвайте ограничението, документирано за конкретната крайна точка и версия на API. Проверете също размера на заявката, ограниченията на честотата и всички ограничения, специфични за акаунта. Няма безопасен универсален брой, който да се прилага за всички API за проследяване или за различните операции в едно API.
Може ли един невалиден номер за проследяване да доведе до неуспех на целия пакет?
Да, в зависимост от правилата за валидиране на крайната точка. Някои API връщат отделни отхвърляния, докато други могат да отхвърлят заявката преди обработката на елементите. Проверявайте както грешките на ниво заявка, така и резултатите на ниво елемент; не приемайте, че всяка пакетна крайна точка поддържа частично приемане.
Трябва ли да повторя пакет, когато HTTP отговорът е успешен?
Не автоматично. Първо анализирайте документирания статус на ниво приложение и резултатите за елементите. Запазете успешните записи и повторете опита само за допустимите грешки. Ако резултатът не може да бъде безопасно интерпретиран, класифицирайте го като несигурен и го проучете.
Мога ли да смесвам превозвачи в един пакет?
Само когато крайната точка поддържа такава структура на заявката. Потвърдете дали информацията за превозвача се подава за всяка пратка, дали се поддържа автоматично идентифициране и какво се случва при нееднозначно идентифициране. Услугата за множество превозвачи сама по себе си не определя правилата за пакетна обработка на всяка крайна точка.
Прави ли пакетната обработка актуализациите за проследяване по-бързи?
Пакетната обработка може да намали броя заявки, които приложението ви изпраща, но сама по себе си не кара събитията от превозвача да се появяват по-рано. Регистрацията, извличането на данни, наличността на сканиране от превозвача и доставката на актуализации са отделни части от работния процес.
Източници
- 17TRACK Tracking API — официална продуктова отправна точка за разработчици, които оценяват интеграция за проследяване.
- 17TRACK API документация — справочник за специфичния за доставчика договор на крайната точка, ограниченията, удостоверяването и обработката на отговорите.
- RFC 9110: HTTP Semantics — семантика на HTTP статусите, идемпотентност, автоматични повторни опити и Retry-After.
- RFC 6585: Additional HTTP Status Codes — дефиниция на HTTP 429 Too Many Requests и неговата незадължителна заглавка Retry-After.


