Тестване на интеграция с Tracking API в среда за разработка: Sandbox, тестови номера, симулирани webhook-и
За да тествате интеграция с API за проследяване в среда за разработка, използвайте три допълващи се метода: тестова среда на доставчика или документирани тестови номера за поведението на API, локални фикстури за повтаряеми сценарии с пратки и макетни уебкуки за вашата крайна точка за получаване. След това извършете контролирана проверка на живо, за да валидирате частите, които симулациите не могат да докажат, включително идентификационни данни, конфигурация на абонамента и реалното доставяне на събития.
Това ръководство е предназначено за разработчици, които свързват проследяването на пратки с платформа за електронна търговия, система за управление на поръчки, ERP или услуга за известяване на клиенти. Целта не е просто да получите успешен отговор от API. Трябва да докажете, че актуализациите за проследяване създават правилното състояние на поръчката без дублирани съобщения, изгубени събития или случайно свързване с реални клиенти.
Разделете поведението на доставчика от поведението на приложението
Интеграцията за проследяване има поне две граници: заявките, които приложението ви изпраща към доставчика, и актуализациите, които приложението ви получава или извлича след това. Успешната заявка на първата граница не доказва, че втората граница работи.
Изградете тестовия план около тези граници, вместо да очаквате един тестов номер за проследяване да упражни цялата система.
| Метод на тестване | Какво може да валидира | Какво не може да установи самостоятелно |
|---|---|---|
| Тестова среда на доставчика | Поддържани формати на заявки, удостоверяване и симулирано поведение, описано от доставчика | Наличност на данни от превозвачи в продукция или поведение при доставяне в продукция |
| Документирани тестови номера | Конкретните сценарии, зададени за тези номера | Други статуси, превозвачи или последователности от уебкуки |
| Локални фикстури и макети на API | Вашия парсер, правилата за съпоставяне, съхранението и обработката на грешки | Дали реалният доставчик приема заявки или изпраща същия полезен товар |
| Макетни заявки към уебкуки | Обработката на крайната точка, валидирането, предотвратяването на дублиране и последващите ефекти | Конфигурацията на обратните извиквания от страна на доставчика или реалните повторни опити за доставяне |
| Контролиран тест на живо | Реалната свързаност и наблюдавания работен процес на пратката | Всяка рядка грешка, изключение или последователност на доставяне |
Препоръчителен подход: направете локалните тестове детерминистични, използвайте поддържано от доставчика тестване, когато е налично, и запазете пратките на живо за потвърждаване на връзката между системите.
Потвърдете договора с доставчика, преди да пишете фикстури
Започнете с официалната документация за версията на API, която възнамерявате да използвате. Потвърдете базовия URL адрес, метода за удостоверяване, изискванията за регистрация, схемата на отговора, настройката на уебкуките и всички документирани възможности за тестване. Не приемайте, че съществува отделна тестова среда само защото доставчикът предлага API.
За интеграция с 17TRACK използвайте страницата на 17TRACK Tracking API и официалната документация за API като отправна точка. Проверете приложимите спецификации за заявки и обратни извиквания там, преди да изграждате специфични за доставчика примери. Примерите по-долу умишлено са фикстури, принадлежащи на приложението, а не представяне на схемата на API на 17TRACK.
Изяснете следните въпроси, преди да свържете кода за разработка с външен акаунт:
- Отделни ли са идентификационните данни за разработка и продукция и до каква среда дава достъп всеки набор от идентификационни данни?
- Поддържа ли тестовата среда обратни извиквания или само тестване заявка-отговор?
- Документирани ли са тестовите номера и какви точно резултати създават?
- Могат ли регистрациите или други тестови заявки да използват квотата на акаунта или да създават постоянни записи?
- Какви са документираните правила за удостоверяване на обратните извиквания, потвърждение, изчакване и повторни опити?
- Кои идентификатори свързват регистрация за проследяване, пратка, превозвач и събитие на обратното извикване?
Ако поведението при тестване не е ясно документирано, поискайте потвърждение от доставчика. Междувременно продължете да тествате собствената си логика за обработка с макети. Непотвърдената възможност на тестовата среда е несигурност при планирането, а не доказателство, че доставчикът не я поддържа.
Изградете изолирана среда за разработка
Използвайте отделна база данни или изолиран клиент, отделни секрети и синтетични поръчки. Насочете имейлите, SMS съобщенията и другите известия към тестови дестинации или система за събиране на известия. Пратка, маркирана като доставена във фикстура, не трябва да задейства съобщение до реален купувач.
Добавете изричен маркер на средата към вътрешните записи и журналите. Съхранявайте идентификационните данни на доставчика на сървъра, извън системата за контрол на версиите, и маскирайте секретите от записите на заявките. Ако за обратни извиквания е необходим временен публичен достъп, изложете само предназначения маршрут за разработка и запазете контролите му за удостоверяване.
Създайте малък набор от известни поръчки, преди да изпращате събития. Включете две пратки, свързани с една поръчка, и ако приложението ви го поддържа, един и същ низ на номер за проследяване при различни контексти на превозвач. Тези случаи разкриват предположенията, че само номерът за проследяване винаги идентифицира уникален бизнес запис.
Определете предварително очаквания ефект от всеки тест: състоянието на пратката, свързването с поръчката, записите във времевата линия, броя известия и одитния запис. Така демонстрацията се превръща в твърдение, което може да премине или да се провали.
Използвайте тестовите номера само за документираната им цел
Номерът за проследяване има две различни роли при тестване. Той може да бъде вход, използван за валидиране на регистрацията, и може да идентифицира пратка, която създава събития за проследяване. Номер, който преминава проверката на формата, не предоставя непременно полезна история на събитията.
Когато са налични официални тестови номера
Записвайте посочения от доставчика сценарий заедно с всеки номер. Не трябва да приемате, че номер, документиран за доставена пратка, симулира изключение, връщане или неуспешен опит за доставка. Проверете също дали резултатът му е фиксиран, променя се с времето или изисква избор на конкретен превозвач.
Съхранявайте тези номера в отделна конфигурация за интеграционни тестове. Не ги разпръсквайте в модулните тестове, където промяната във външното поведение може да направи иначе детерминистичните тестове ненадеждни.
Когато официалните тестови номера не са потвърдени
Използвайте синтетични идентификатори в собственото си приложение и симулирайте границата с доставчика. Никога не измисляйте номер, който изглежда правдоподобно, и не приемайте, че е запазен за тестване: той може да съвпадне с реална пратка.
За валидиране на живо използвайте пратки, които контролирате и до които имате разрешен достъп. Избягвайте да копирате номера за проследяване от публични екранни снимки или разговори с клиенти. Приемайте историите на пратките за потенциално чувствителни, тъй като могат да съдържат местоположения, времеви отметки и информация за доставката.
По-стара доставена пратка може да помогне за валидиране на парсирането, но е лоша зависимост за непрекъсната интеграция. Наличността на исторически данни и външният отговор могат да се променят. Запазете дезинфекцирана фикстура за повтаряеми тестове и отделете проверката на живо.
Създайте фикстури около значими преходи на пратката
Изградете фикстурите от документираната схема и, когато са налични, от дезинфекцирани реални отговори. Съхранявайте фикстурите на полезния товар от доставчика отделно от вътрешния ви нормализиран модел на събитията. Тествайте адаптера между тях, така че вътрешен макет да не прикрива повреден парсер на доставчика.
Полезният начален набор обхваща следните сценарии:
- Все още няма събития за проследяване: запазете пратката, без да твърдите, че има движение или доставка.
- В транзит: актуализирайте времевата линия и запазете правилното свързване с поръчката.
- Излязла за доставка: приложете политиката си за известия, без да третирате доставката като завършена.
- Доставена: запишете завършването и изпълнете предвиденото бизнес действие само веднъж.
- Изключение или опит за доставка: запазете разликата спрямо завършена доставка.
- Движение по връщане: не интерпретирайте всяко следващо сканиране като напредък към първоначалния получател.
- Неизвестен статус: запазете достатъчно информация за диагностика, без да измисляте съпоставяне на статуса.
Използвайте собствени нормализирани имена за тези сценарии, след което изрично съпоставете документираните стойности на доставчика с тях. Не приемайте, че различните API използват еднакви етикети за статус или че един етикет има идентично бизнес значение навсякъде.
Променяйте също формата на данните: празен списък от събития, липсващи незадължителни полета, допълнителни неизвестни полета, имена на местоположения в Unicode, времеви отметки с отместване на часовата зона и неправилно форматирани задължителни стойности. Парсерът ви трябва да допуска съвместими допълнения, като същевременно отхвърля данни, които не могат да бъдат обработени безопасно.
Изпращайте макетни уебкуки през реалния път за получаване
Макетният уебкук трябва да упражнява маршрута за получаване, междинния слой за удостоверяване, валидирането, съхранението и обработката от работника, а не просто да извиква крайната функция за актуализиране на статуса.
Следният полезен товар представлява синтетично вътрешно събитие. Имената на полетата, идентификаторът на събитието и статусът са илюстративни; те не представляват договор за обратни извиквания на доставчика.
{
"event_id": "dev-event-001",
"shipment_id": "dev-shipment-001",
"tracking_number": "INTERNAL-TEST-001",
"status": "in_transit",
"occurred_at": "2025-01-15T10:00:00Z"
}
Запазете го като tracking-event.json и го изпратете към локален тестов получател:
curl --request POST \
http://localhost:3000/dev/tracking-events \
--header 'Content-Type: application/json' \
--data-binary @tracking-event.json
Тази команда валидира само локалното маршрутизиране и обработка. Тя не демонстрира удостоверяване на доставчика. Направете маршрут, предназначен само за разработка, недостъпен в продукция, или тествайте продукционния получател с документирания от доставчика метод за удостоверяване и отделен тестов секрет.
Тествайте удостоверяването, без да отслабвате контролите в продукция
Ако доставчикът посочва подписани обратни извиквания, приложете точно тази схема, вместо да избирате произволен хедър или алгоритъм за подпис. При схеми, които подписват байтовете на заявката, запазете оригиналното тяло за проверка; парсирането и повторното сериализиране на JSON може да промени тези байтове.
Тествайте валидно удостоверяване, липсващи идентификационни данни, подправени тела и неправилни подписи, когато е приложимо. Ако документираната схема включва времеви отметки или защита от повторно възпроизвеждане, тествайте и тези правила. HMAC е стандартизирана конструкция за удостоверяване на съобщения, но съществуването му не доказва, че конкретен доставчик на проследяване го използва.
Тествайте дублирания, подреждането и възстановяването
Обработката на пратките трябва да остане коректна, когато една и съща актуализация пристига многократно или събитията пристигат в неочакван ред. Това са защитни тестови сценарии, а не твърдения относно гаранцията за доставяне на конкретен доставчик.
| Тест | Очаквано поведение на приложението |
|---|---|
| Изпратете едно и също събитие два пъти | Запазете едно логическо събитие и избегнете дублирани известия до клиента. |
| Изпратете по-старо транзитно сканиране след доставката | Запазете полезната история, без автоматично да обръщате състоянието „доставена“. |
| Изпратете едновременни актуализации | Прилагайте последователни преходи на състоянието въпреки едновременните работници. |
| Спрете обработката след трайно получаване | Възстановете и обработете съхраненото събитие, без да изисквате ново обратно извикване. |
| Съхранението се проваля, преди получаването да стане трайно | Не потвърждавайте неправилно успешно приемане. |
| Изпратете неизвестна пратка | Следвайте определена политика за карантина или отхвърляне; никога не отгатвайте връзката с поръчката. |
Предпочитайте документиран стабилен идентификатор на събитието за предотвратяване на дублиране, когато такъв е предоставен. В противен случай определете внимателно ограничена идентичност от съответните полета и тествайте сблъсъците. Сам по себе си номерът за проследяване не е идентичност на събитие, защото една пратка може да генерира много легитимни актуализации.
Разделете историята на събитията от текущата проекция на пратката. Съхраняването на историческите сканирания не означава, че всяко късно пристигнало сканиране трябва да замества показвания статус. Нито правилото „използвайте най-новата времева отметка“ е пълно: корекциите, процесите на връщане и различните значения на времевите отметки изискват изрична обработка.
При асинхронна обработка потвърждавайте само след като събитието достигне трайна точка за предаване, например запис във входящата кутия или трайна опашка, съобразно архитектурата ви. Следвайте документираните изисквания на доставчика за потвърждение. HTTP определя семантиката на кодовете за състояние, но графикът за повторни опити на конкретния изпращач трябва да произтича от неговия договор.
Извършете контролирана проверка на живо и определете критериите за издаване
След като детерминистичните тестове преминат, регистрирайте разрешена пратка чрез реалната интеграция и потвърдете целия път. Проверете дали доставчикът е приел предвидения запис, дали конфигурацията на обратното извикване сочи към правилната среда и дали входящите данни се съпоставят с очакваната пратка.
Не изисквайте всеки статус на пратката да се появи по време на тази проверка на живо. Реалните пратки не са контролируеми фикстури. Използвайте изпълнението на живо за валидиране на свързаността и наблюдаваната съвместимост с договора; използвайте фикстури, които могат да се възпроизвеждат, за редки или разрушителни сценарии.
Преди издаване изисквайте следните резултати:
- Обработват се документираните успешни отговори и отговори за грешки, включително грешки на ниво елемент, ако API поддържа пакетни операции.
- Изчакванията не задействат сляпо повторно създаване, когато първата заявка може вече да е успешна.
- Дублираните събития не могат да създадат дублирани бизнес действия.
- Невалидните обратни извиквания не могат да променят състоянието на пратката.
- Грешките на работниците оставят възстановими събития, вместо да ги губят безшумно.
- Трафикът от разработката не може да уведомява реални клиенти или да променя продукционни поръчки.
- Журналите свързват заявките, получените събития, резултатите от обработката и опитите за известяване, без да разкриват секрети.
Изданието е готово, когато можете да обясните както нормалния работен процес, така и начина, по който системата се възстановява след несигурна заявка, повторено обратно извикване или прекъснат работник. Една успешна справка за проследяване не е достатъчна.
Често задавани въпроси
Мога ли да тествам интеграция за проследяване без тестова среда?
Да. Симулирайте изходящата граница на API, възпроизвеждайте документирани фикстури за обратни извиквания и тествайте локално нормализацията и бизнес правилата си. След това използвайте разрешена пратка на живо, за да потвърдите реалната свързаност. Това осигурява значително покритие, но не възпроизвежда недокументираното поведение на доставчика.
Защо заявката ми за проследяване е успешна, но не връща събития?
Приемането на заявката и наличността на данни за проследяване са различни резултати. Проверете подробностите в отговора на доставчика, изискванията за регистрация, правилата за идентифициране на превозвача и документираното поведение при пратки без събития. Не измисляйте информация за движение или доставка, за да запълните празна времева линия.
Доказва ли успешният макетен уебкук, че реалните уебкуки ще пристигат?
Не. Той доказва само пътя, упражнен от макета. Реалното доставяне зависи и от конфигурацията на доставчика, публичната достъпност, TLS, удостоверяването и действителния договор за обратното извикване. Валидирайте ги с тестово доставяне, поддържано от доставчика, или с разрешен работен процес на живо.
Трябва ли да връщам HTTP 200, преди обработката да приключи?
Следвайте документирания договор на доставчика за потвърждение. При асинхронен дизайн потвърдете след трайното приемане, а след това обработете събитието в работник. Връщането на успех преди трайното приемане може да доведе до загуба на събитие, ако процесът се провали непосредствено след това.
Как трябва да тествам известията до клиентите?
Изпращайте всички известия от разработката към контролирана система за събиране. Проверявайте дестинацията, шаблона, задействащия преход и броя изпращания. Възпроизведете същото събитие и симулирайте повторни опити на работника, за да проверите, че една актуализация на пратката не генерира повтарящи се съобщения до клиента.
Източници
- 17TRACK Tracking API — официална отправна точка за продукта за API за проследяване.
- Документация за API на 17TRACK — справка за специфичния за доставчика договор за интеграция; потвърдете тук приложимите изисквания за тестване и обратни извиквания.
- RFC 9110: HTTP Semantics — семантика на HTTP отговорите и съображения при повторение на заявки.
- RFC 2104: HMAC — стандартизираната конструкция за удостоверяване на съобщения, разгледана в указанията за сигурност на обратните извиквания.


