Skip to main content
НачалоБлогРъководства6 проверки, за да потвърдите, че най-новите събития за проследяване на превозвача са синхронизирани чрез вашия API

6 проверки, за да потвърдите, че най-новите събития за проследяване на превозвача са синхронизирани чрез вашия API

17TRACK

За да проверите дали вашият API е синхронизирал най-новите събития за проследяване от превозвача, проверете идентичността на пратката, времевите отметки на събитията, подробностите за събитията, маршрута на доставката, подредбата на събитията и актуалността спрямо независим изглед за проследяване. Успешният отговор от API или потвърждението на webhook потвърждава само една част от тази верига; само по себе си то не доказва, че приложението ви разполага с най-новото събитие от превозвача.

6 проверки за потвърждаване на синхронизирането на най-новите събития за проследяване от превозвача

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

Преди да започнете: определете какво означава „най-ново“

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

Изберете точка за сравнение, преди да започнете разследването. В идеалния случай използвайте страницата за проследяване на превозвача или друг оторизиран запис, предоставен от превозвача, за същата пратка. Ако това не е възможно, сравнете приложението си с текущия отговор от API на доставчика на проследяване. Това по-тясно сравнение може да установи дали приложението ви съвпада с доставчика; то не може да установи дали доставчикът вече разполага с всяко сканиране от превозвача. Запишете кога сте направили сравнението, за да не изглежда по-късна актуализация като несъответствие с по-ранен резултат.

1. Потвърдете, че и двете системи се отнасят до една и съща пратка

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

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

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

2. Сравнявайте времето на събитията, без да губите смисъла му

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

Изобразяване само на часа, предполагаема местна часова зона или анализатор, който незабелязано отхвърля отместването, може да премести събитието в друг календарен ден или да го постави в неправилен ред. Когато източникът предоставя двусмислено местно време, отбележете сравнението като несигурно, вместо да измисляте точен UTC момент. Разграничавайте също времето на настъпване на събитието от времето на отговора на API: отговор, получен сега, законно може да съдържа събитие, случило се по-рано.

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

3. Проверете данните на събитието, а не само основния статус

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

Проверете необработения отговор от API или запазеното тяло на webhook, когато правилата ви за обработка на данни го позволяват. След това проследете събитието през анализа, съпоставянето на полета, съхранението и представянето. Търсете полета със стойност null, заменени със стойности по подразбиране, неочаквани кодове на статуси, попаднали в обща категория, съкратен текст или потребителски интерфейс, който показва само избрани типове събития. Несъответствието в етикета на статуса се различава от липсващо събитие: то насочва към логиката за преобразуване или показване, а не към доставката.

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

4. Проследете как събитието е достигнало до приложението ви

Ако използвате webhooks, проверете журнала за получаване за съответната пратка и събитие. Уверете се, че крайната ви точка е приела заявката, съобщението е преминало валидирането и последващата обработка е завършила. Успешният HTTP отговор от крайната ви точка не доказва, че последващият worker на опашката е записал събитието. Ако обработката е асинхронна, проверете както входящата заявка, така и резултата от задачата.

Ако извършвате polling към API, проверете последната завършена заявка, идентификатора на пратката в нея, нейния отговор и всяка логика за странициране или извличане, която използва интеграцията ви. Успешната заявка все пак може да бъде последвана от неуспешен запис в базата данни или прочитане от остарял кеш. Използвайте приложимата документация на доставчика, за да проверите действителните полета в отговора, изискванията за удостоверяване и поведението при доставка за интеграцията си, вместо да предполагате, че всеки tracking API следва един и същ договор. За интеграция с 17TRACK подходящите начални точки са неговата страница на Tracking API и документация на API; потвърдете документираното поведение за използваните от вас крайна точка и метод.

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

5. Проверете правилата за подреждане и преход на състоянията

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

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

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

6. Измерете актуалността и съгласувайте изключенията

Накрая сравнете какво е знаел всеки слой в един и същ момент на наблюдение: изгледа на превозвача, отговора от доставчика на проследяване, входящия webhook или резултата от polling, записа в базата данни и изхода, видим за клиента. Отбележете първия слой, на който очакваното събитие изчезва. Тази граница е по-полезна от общ доклад, че „проследяването е забавено“.

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

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

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

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

Означава ли успешният отговор на webhook, че последното събитие е синхронизирано?

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

Защо страницата на превозвача показва по-ново сканиране от отговора ми от API?

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

Трябва ли да използвам времевата отметка на събитието или времето, в което системата ми го е получила, за избор на последния статус?

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

Какво да направя, ако статусът в API не се е променил, но списъкът със събития има нов запис?

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

Източници