Skip to main content
НачалоБлогРъководства15 въпроса, които да зададете на доставчик на API за проследяване, преди да преминете към продукция

15 въпроса, които да зададете на доставчик на API за проследяване, преди да преминете към продукция

17TRACK

Преди да внедрите tracking API в продукция, попитайте как обработва реалните ви превозвачи и видове пратки, какво означават събитията му, как пристигат актуализациите и какво се случва при грешка в данните или интеграцията. Следващите 15 въпроса дават на инженерните и оперативните екипи практичен начин да проверят тези отговори, преди клиентите, служителите по поддръжката или автоматизираните работни процеси да започнат да разчитат на тях.

15 въпроса, които да зададете на доставчик на Tracking API, преди да продължите

Успешната демонстрация не е тест в продукционна среда. Използвайте представителна извадка от пратки, включително забавени, върнати и трудни за идентифициране пратки. За всеки отговор поискайте документация, примерен payload или резултат от тест. Запишете всеки нерешен въпрос заедно с отговорно лице и дата за решение, вместо да предполагате, че ще бъде решен след старта.

Започнете със съвместимостта на пратките и значението на данните

1. Кои от реалните ни пратки можете да проследявате и какво означава покритието?

Предоставете на доставчика извадка от вашите превозвачи, услуги, двойки на произход и местоназначение и формати на номера за проследяване. Поискайте да посочи кои пратки може да приеме, кои превозвачи може да идентифицира автоматично и къде трябва да подадете код на превозвача. Фактът, че даден превозвач присъства в списък, не доказва, че всяка услуга, предаване или вид пратка ще генерира необходимите за приложението ви събития.

Тествайте реални примери от високонатоварени направления и оперативни гранични случаи. Включете пратка, която сменя превозвача по време на транспортирането, ако това се случва във вашия бизнес. Запишете дали API отхвърля пратката, приема я, без да открива събития, или връща събития с ограничени подробности. Тези резултати изискват различна обработка в системата за управление на поръчки.

2. Какво е необходимо за регистриране на пратка и как предотвратявате дублирани регистрации?

Изяснете необходимите идентификатори, правилата за избор на превозвач, момента на регистрация и реакцията при невалиден или все още неактивен номер за проследяване. Попитайте дали само номерът за проследяване е достатъчен за вашия случай или е нужна допълнителна информация. Потвърдете какво се случва, ако една и съща пратка бъде изпратена два пъти — от една и съща система или от отделни услуги.

Изградете един поток за регистрация с ясно разпределени отговорности: коя система изпраща пратките, коя съхранява идентификатора на доставчика и коя повтаря неуспешно или несигурно изпращане. Ако заявката изтече след обработването ѝ от доставчика, сляпото повторение не трябва незабелязано да създава втори запис или дублирани последващи известия.

3. Какво означават статусите ви и можем ли да разглеждаме основните събития на превозвача?

Поискайте речник на статусите и представителни необработени събития. Термини като „в транзит“, „излязла за доставка“, „изключение“, „доставена“ и „върната“ са полезни обобщения, но бизнес правилата ви може да изискват повече подробности. Установете дали доставчикът предоставя оригиналните описания на превозвача наред със стандартизираните статуси и как обработва събитие, което не може да бъде коректно съпоставено.

Съгласувайте собствения си вътрешен модел на статусите преди старта. По-специално решете кое събитие може да приключи пратката, да задейства съобщение за доставка или да започне работен процес за изключение. Не приемайте широк етикет на статус като доказателство за конкретно физическо събитие, освен ако основните данни не подкрепят това тълкуване.

4. Какви времеви отметки и местоположения се предоставят и как трябва да ги тълкуваме?

За всяко събитие разграничете времето, когато превозвачът посочва, че то се е случило, от времето, когато доставчикът го е получил или публикувал. Попитайте за часовите зони, липсващите отмествания, точността на местоположението и актуализациите, които пристигат след по-късни събития. Наскоро получено събитие може да описва по-старо сканиране; сортирането единствено по времето на приемане може да създаде подвеждаща хронология.

Тествайте payload спрямо схемата на базата си данни и визуализацията за клиентите. Решете как да показвате събитие, когато местната му часова зона е несигурна, и избягвайте да представяте точно време или местоположение на доставка, ако източникът не ги предоставя.

5. Как са представени изключенията, връщанията и доказателството за доставка?

Поискайте примери за неуспешни опити за доставка, задържане от митницата, проблеми с адреса, връщане към подателя и доставени пратки. Попитайте кои подробности са стандартизирани, кои остават специфични за превозвача и дали потвърждението за доставка включва подкрепящи доказателства в случаите, които ви интересуват. Не приемайте, че статусът „доставена“ включва име на получателя, подпис, снимка или друго доказателство.

Съпоставете всяко изключение с отговорно лице и действие. Някои събития изискват преглед от поддръжката; други не изискват съобщение до клиента, докато не пристигне повече информация. Ако доказателството за доставка е необходимо за процес при спор, превърнете неговата наличност и формат в отделен критерий за приемане, а не в подразбираща се част от покритието за проследяване.

Тествайте как актуализациите достигат до системите ви

6. Предоставяте ли актуализации чрез webhook, polling или и двете и кога трябва да използваме всеки метод?

Поискайте документирания модел за доставка, примери за payload, настройка на абонамента и указания за възстановяване на пропуснати актуализации. Ако се предлагат webhook-и, установете дали те съобщават за променена пратка, предоставят пълен моментен snapshot или съдържат отделно събитие. Ако polling е задължителен или се използва като резервен вариант, изяснете подходящия модел на заявките и начина за идентифициране на променените записи.

Изберете модела според работния процес. Клиентската хронология може да понася различно забавяне на актуализациите от опашката за изключения. Архитектурата ви не трябва да обещава незабавни известия само защото интеграцията използва webhook-и: превозвачът първо трябва да направи събитието налично, а всяка следваща система трябва да го обработи.

7. Какво се случва, когато известията са дублирани, забавени или пристигат в неправилен ред?

Попитайте дали доставчикът повтаря неуспешните доставки, за колко време и какъв отговор очаква от вашия endpoint. Поискайте стабилен идентификатор на събитието или пратката, ако има такъв. След това изпратете едно и също известие два пъти, изпратете по-старо събитие след по-ново и временно върнете грешка от вашия endpoint.

Получателят ви трябва да е проектиран да потвърждава само това, което безопасно е приел, да обработва повторенията без повторно изпращане на клиентски съобщения и да възстановява правилна хронология, когато събитията пристигат в неправилен ред. Ако предложената архитектура зависи от точно една доставка на всяко известие, оспорете това допускане преди пускането.

8. Как ще измерваме актуалността на данните и какво ѝ влияе?

Попитайте какво може да измери доставчикът на всеки етап: времето на събитието при превозвача, времето на приемане от доставчика и времето на доставяне до вашата система. Разграничете тези измервания от всякакви ангажименти, които той поема. Дългият интервал между физическото движение и актуализацията във вашето приложение може да възникне нагоре по веригата, при обработката от доставчика или във вашата собствена опашка.

По време на пилотния период измервайте тези интервали за представителни пратки и проучвайте отклоненията. Задайте прагове за известия според реалните изисквания на работния процес. Ако забавено сканиране може да доведе до вредно клиентско съобщение или пропусната ескалация, определете резервен вариант, например етикет за остарели данни или ръчен преглед.

9. Как са защитени API идентификационните данни и webhook заявките?

Поискайте документацията за удостоверяване и управление на идентификационните данни. Потвърдете как се издават, ограничават, ротират и оттеглят идентификационните данни; дали тестовите и продукционните идентификационни данни са отделни; и как получателят на webhook може да провери автентичността на заявката. Попитайте също какви защити са налични срещу повторно изпращане на webhook заявки.

Нека екипът ви по сигурността прегледа предложената реализация, а не само списъка с функции на доставчика. Не съхранявайте тайни в клиентския код и логовете, ограничете достъпа до продукционните идентификационни данни и репетирайте ротацията им. Ако приложението ви не може да провери входящо известие чрез документирания механизъм, това блокира пускането на работен процес, базиран на webhook.

10. Какви данни за пратки и клиенти съхранявате и къде отиват?

Избройте всяко поле, което интеграцията ви би изпращала, включително номера за проследяване, референции на поръчки, адреси, данни за контакт и персонализирани метаданни. Попитайте кои полета са задължителни, колко дълго се съхраняват данните и логовете, как работят заявките за изтриване и кои региони или подизпълнители са от значение за изискванията на организацията ви. Получете договорна или документация за сигурността, когато прегледът ви я изисква.

Минимизирайте предаваните данни. Интеграцията за проследяване не трябва да получава информация за клиента само защото е удобно да предадете целия обект на поръчката. Екипите ви по поверителност, правни въпроси и сигурност трябва да решат дали документираната обработка от доставчика е подходяща за пазарите, на които работите.

Планирайте откази и оперативни промени

11. Какви са ограниченията за честота на заявките и как клиентите трябва да реагират при грешки?

Поискайте ограниченията за endpoint, идентификационни данни и среда, както и правилата за паралелност и препоръчителното поведение при повторни опити. Разграничете невалидна заявка от временен проблем с услугата и от заявка, ограничена по честота. За HTTP API значенията на кодовете за статус са важни: RFC 6585 определя 429 за твърде много заявки, докато RFC 9110 описва семантиката на HTTP, включително грешките на сървъра.

Изчислете очаквания трафик за обикновени дни и пикове, след което тествайте клиент, който увеличава интервалите между опитите, поставя работата на опашка и изпраща известия при продължителни откази. Потвърдете дали несигурна операция за запис може безопасно да бъде повторена. Политика за повторни опити, която умножава трафика по време на прекъсване, може да затрудни възстановяването.

12. Как се съобщават промените в схемата, статусите и интеграциите с превозвачите?

Попитайте за версионирането на API, известията за оттегляне, регистрите на промените и дали полетата на събитията могат да бъдат добавяни без промяна на версията. Описанията, предоставени от превозвача, и поведението при проследяване също могат да се променят. Установете как доставчикът съобщава за промяна, която засяга един превозвач или маршрут, а не целия API.

Пишете толерантни парсъри за незадължителни полета и неизвестни стойности на статуси, но не превръщайте тихомълком непозната стойност в „доставена“ или „неуспешна“. Съхранявайте достатъчно подробности от източника, за да диагностицирате променено съпоставяне. Определете отговорно лице, което да преглежда известията на доставчика и да актуализира интеграционните тестове, преди промяната да достигне до клиентите.

13. Какво можем да тестваме преди продукция и доколко тестовата среда съответства на реалното поведение?

Поискайте достъп до документацията, тестова среда, ако се предлага, примерни отговори и начин за упражняване на пътищата с грешки. Попитайте кои сценарии са симулирани и кои изискват реални пратки. Sandbox средата може да докаже, че кодът ви обработва payload, но да не казва почти нищо за пълнотата на събитията от превозвача, времето на актуализациите или регионалната съвместимост.

Проведете два вида тестове: детерминирани интеграционни тестове за парсинг, повторни опити и сигурност; и ограничен пилот с реални пратки за оперативното поведение. Включете дублирани изпращания, timeout на доставчика, забавено сканиране, връщане и неизвестен статус. Изискайте както инженерният екип, така и екипът, който ще обработва изключенията, да одобрят резултатите.

14. Какви ангажименти за поддръжка и инциденти важат, когато проследяването спре да се актуализира?

Попитайте кои канали за поддръжка са достъпни за акаунта ви, как се съобщават инциденти и какви договорни ангажименти за услугата — ако има такива — важат за API или доставката на известия. Изяснете дали ангажиментът за наличност обхваща endpoint-а на API, доставката на актуализации за проследяване или и двете. Това не е един и същ оперативен резултат.

Създайте собствена процедура: кой открива отказ, кой се свързва с доставчика, кога се използва polling или друг резервен вариант и какво виждат клиентите, докато актуализациите са забавени. Поискайте процес за решаване както на проблем с данните за конкретна пратка, така и на прекъсване на цялата платформа. Тествайте пътя за ескалация, преди да ви потрябва.

15. Как се изчисляват използването и разходите и какво се случва, ако прекратим услугата?

Попитайте кои действия се броят към таксуването или ограниченията за използване: изпращания, проследявани пратки, заявки, известия или друга единица. Потвърдете как се третират дублираните регистрации, повторните опити, неактивните пратки, превишаването на лимитите и тестовият трафик според предложеното споразумение. Получете приложимите условия в писмен вид, вместо да изчислявате разходите от демонстрация на API.

Планирайте и прекратяването. Установете как можете да експортирате хронологиите на пратките, колко дълго ще остане достъпът и какво ще се случи с активните записи за проследяване. Работещият план за изход не означава, че непременно ще смените доставчика; той е начин да избегнете загубата на видимост върху пратки, които вече са в движение.

Превърнете отговорите в решение за пускане в продукция

Полезният преглед преди пускане има три резултата:

  • Резултат за съвместимостта на пратките: тествана извадка, показваща кои записи за проследяване са приети и дали събитията им поддържат планираните клиентски и оперативни работни процеси.
  • Резултат за интеграцията: доказана обработка на удостоверяване, дубликати, повторни опити, забавени събития, вариации на схемата и възстановяване от пропуснати актуализации.
  • Оперативно споразумение: документирани ограничения, условия за обработка на данни, контакти за поддръжка, допускания за разходите и отговорни лица за нерешените рискове.

17TRACK е един от доставчиците, които можете да оцените, ако multi-carrier tracking API отговаря на вашия случай; неговата страница за Tracking API и документацията за API са отправни точки за проверка на интеграцията спрямо тези въпроси. Същият стандарт трябва да се прилага към всеки доставчик: документацията установява как интерфейсът е предназначен да работи, а вашите собствени тестове с представителни пратки установяват дали работи за продукционния ви работен процес. Не пускайте клиентско известие или автоматизация за изключения, докато събитията, които ги задействат, не бъдат валидирани.

Често задавани въпроси

Достатъчен ли е sandbox тестът, за да одобрим tracking API за продукция?

Не. Sandbox средата може да валидира форматите на заявките и част от обработката на откази, но са необходими реални пратки, за да се оценят специфичните за превозвача събития, времето и полезността на данните за изключения по реалните ви направления. Използвайте и двете среди с отделни критерии за приемане.

Трябва ли да използваме webhook-и или polling за актуализациите на проследяването?

Вземете решение според документираните възможности за доставка на доставчика и допустимото от работния ви процес забавяне. Webhook-ите могат да намалят нуждата от повтарящи се проверки, когато се поддържат, но получателят ви все пак трябва да обработва повторения и дубликати. Polling може да е подходящ като основен метод или като път за възстановяване, при спазване на документираните ограничения.

Коя е най-честата грешка при съпоставянето на статусите за проследяване?

Използването на един широк статус като тригер за по-конкретно бизнес твърдение. Например самият етикет „доставена“ може да не предоставя доказателството, необходимо за разрешаване на спор. Определяйте тригерите чрез подробностите на основните събития, които доставчикът ви действително предоставя.

Кой трябва да одобри интеграцията преди старта?

Инженерният екип трябва да одобри надеждността и сигурността; оперативният екип или екипът по поддръжката трябва да одобри полезността на събитията и работните процеси за изключения; а подходящите отговорни лица за поверителност, правни въпроси и доставки трябва да прегледат обработката на данните и търговските условия. Определете конкретно отговорно лице за всяка оставаща празнина.

Източници