Skip to main content
Басты бетБлогНұсқаулықтарӘзірлеу ортасында Tracking API интеграциясын тестілеу: Sandbox, тест нөмірлері, жалған Webhook-тар

Әзірлеу ортасында Tracking API интеграциясын тестілеу: Sandbox, тест нөмірлері, жалған Webhook-тар

17TRACK

Әзірлеу ортасында tracking API интеграциясын тексеру үшін бірін-бірі толықтыратын үш әдісті пайдаланыңыз: API әрекетін тексеру үшін провайдердің sandbox ортасын немесе құжатталған тест нөмірлерін, қайталанатын жөнелтілім сценарийлері үшін жергілікті fixture файлдарын және қабылдау endpoint-іңіз үшін mock webhook-тарды қолданыңыз. Содан кейін симуляциялар дәлелдей алмайтын бөліктерді, соның ішінде тіркелгі деректерін, жазылым конфигурациясын және нақты оқиғалардың жеткізілуін тексеру үшін бақыланатын live тексеру жүргізіңіз.

Әзірлеу ортасында Tracking API интеграциясын тексеру: Sandbox және тест нөмірлері

Бұл нұсқаулық жөнелтілімдерді tracking жүйесін ecommerce платформасына, тапсырыстарды басқару жүйесіне, ERP жүйесіне немесе клиенттерге хабарлау қызметіне қосатын әзірлеушілерге арналған. Мақсат — жай ғана сәтті API жауабын алу емес. Tracking жаңартуларының қайталанатын хабарламаларсыз, жоғалған оқиғаларсыз немесе нақты клиенттермен кездейсоқ байланыссыз дұрыс тапсырыс күйін тудыратынын дәлелдеу.

Провайдердің әрекетін қолданбаның әрекетінен ажыратыңыз

Tracking интеграциясында кемінде екі шекара бар: қолданбаңыз провайдерге жіберетін сұраулар және кейін қолданбаңыз алатын немесе шығарып алатын жаңартулар. Бірінші шекарада сәтті орындалған сұрау екінші шекараның жұмыс істейтінін дәлелдемейді.

Тест жоспарын бүкіл жүйені бір тест tracking нөмірі тексереді деп күтпей, осы шекаралардың негізінде құрыңыз.

Тест әдісіНені тексере аладыЖалғыз өзі нені дәлелдей алмайды
Провайдердің sandbox ортасыПровайдер сипаттаған қолдау көрсетілетін сұрау форматтары, аутентификация және симуляцияланған әрекетӨндірістегі тасымалдаушы деректерінің қолжетімділігін немесе өндірістегі жеткізу әрекетін
Құжатталған тест нөмірлеріОсы нөмірлерге бекітілген нақты сценарийлердіБасқа күйлерді, тасымалдаушыларды немесе webhook реттіліктерін
Жергілікті fixture файлдары және API mock-тарыПарсеріңізді, салыстыру ережелерін, сақтауды және ақауларды өңдеудіНақты провайдердің сұрауларды қабылдайтынын немесе дәл сондай payload жіберетінін
Mock webhook сұрауларыEndpoint өңдеуін, тексеруді, қайталануды жоюды және кейінгі әсерлердіПровайдер жағындағы callback конфигурациясын немесе нақты жеткізу қайталауларын
Бақыланатын live тестНақты байланыс пен байқалған жөнелтілім жұмыс процесінӘрбір сирек қатені, ерекшелікті немесе жеткізу реттілігін

Ұсынылатын тәсіл: жергілікті тестерді детерминирленген етіңіз, қолжетімді болғанда провайдер қолдайтын тестілеуді пайдаланыңыз және live жөнелтілімдерді жүйелер арасындағы байланысты растауға ғана қалдырыңыз.

Fixture файлдарын жазбас бұрын провайдер келісімшартын растаңыз

Пайдалануды жоспарлаған API нұсқасының ресми құжаттамасынан бастаңыз. Негізгі URL мекенжайын, аутентификация әдісін, тіркелу талаптарын, жауап схемасын, webhook орнатуын және құжатталған тестілеу мүмкіндіктерін растаңыз. Провайдер API ұсынатындықтан, бөлек sandbox бар деп болжамаңыз.

17TRACK интеграциясы үшін бастапқы нүкте ретінде 17TRACK Tracking API беті мен ресми API құжаттамасын пайдаланыңыз. Провайдерге тән мысалдарды құрастырмас бұрын, сол жердегі қолданылатын сұрау және callback спецификацияларын тексеріңіз. Төмендегі мысалдар әдейі қолданбаға тиесілі fixture файлдары ретінде берілген, олар 17TRACK API схемасын көрсетпейді.

Әзірлеу кодын сыртқы тіркелгіге қоспас бұрын мына сұрақтарды шешіңіз:

  • Әзірлеу және өндіріс тіркелгі деректері бөлек пе және әр тіркелгі дерегі қай ортаға қол жеткізеді?
  • Sandbox callback-тарды қолдай ма, әлде тек сұрау-жауап арқылы тестілеуді ғана ма?
  • Тест нөмірлері құжатталған ба және олар нақты қандай нәтижелер береді?
  • Тіркеулер немесе басқа тест сұраулары тіркелгі квотасын жұмсай ма немесе тұрақты жазбалар жасай ма?
  • Callback аутентификациясы, растау, тайм-аут және қайталау ережелері қалай құжатталған?
  • Tracking тіркеуін, жөнелтілімді, тасымалдаушыны және callback оқиғасын қандай идентификаторлар байланыстырады?

Тестілеу әрекеті анық құжатталмаса, провайдерден оны растауды сұраңыз. Осы арада mock-тар арқылы өз өңдеу логикаңызды тестілеуді жалғастырыңыз. Расталмаған sandbox мүмкіндігі — жоспарлау белгісіздігі, провайдерде мұндай мүмкіндік жоқ екенінің дәлелі емес.

Оқшауланған әзірлеу ортасын құрыңыз

Бөлек дерекқорды немесе оқшауланған tenant-ті, бөлек құпияларды және синтетикалық тапсырыстарды пайдаланыңыз. Электрондық пошта, SMS және басқа хабарламаларды тест мақсатындағы мекенжайларға немесе хабарламалар sink-іне бағыттаңыз. Fixture файлында жеткізілді деп белгіленген жөнелтілім нақты сатып алушыға хабарлама жібермеуі тиіс.

Ішкі жазбалар мен журналдарға ортаның нақты белгісін қосыңыз. Провайдер тіркелгі деректерін серверде, бастапқы кодты басқару жүйесінен тыс сақтаңыз және сұрау жазбаларындағы құпияларды бүркемелеңіз. Callback-тар үшін уақытша жалпыға қолжетімділік қажет болса, тек жоспарланған әзірлеу бағытын ашып, оның аутентификация бақылауларын сақтаңыз.

Оқиғаларды жібермес бұрын белгілі тапсырыстардың шағын жиынын жасаңыз. Бір тапсырысқа тіркелген екі жөнелтілімді және қолданбаңыз қолдаса, әртүрлі тасымалдаушы контекстіндегі бірдей tracking-нөмір жолын қосыңыз. Бұл жағдайлар tracking нөмірі ғана бірегей бизнес жазбаны әрқашан анықтайды деген болжамдарды ашады.

Әр тестінің күтілетін әсерін алдын ала анықтаңыз: жөнелтілім күйі, тапсырыспен байланысы, timeline жазбалары, хабарламалар саны және аудит жазбасы. Бұл демонстрацияны өтуі немесе өтпеуі мүмкін assertion-ға айналдырады.

Тест нөмірлерін тек құжатталған мақсатына пайдаланыңыз

Tracking нөмірінің тестілеуде екі түрлі рөлі бар. Ол тіркеуді тексеру үшін кіріс ретінде пайдаланылуы және tracking оқиғаларын тудыратын жөнелтілімді анықтауы мүмкін. Формат тексеруінен өткен нөмір пайдалы оқиғалар тарихын міндетті түрде бермейді.

Ресми тест нөмірлері қолжетімді болғанда

Әр нөмірмен бірге провайдер көрсеткен сценарийді жазып алыңыз. Жеткізілген жөнелтілім үшін құжатталған нөмір exception, қайтару немесе сәтсіз жеткізу әрекетін симуляциялайды деп болжамаңыз. Сондай-ақ нәтиже тұрақты ма, уақыт өте өзгере ме немесе белгілі бір тасымалдаушыны таңдауды қажет ете ме — тексеріңіз.

Бұл нөмірлерді арнайы integration-test конфигурациясында сақтаңыз. Оларды unit тестеріне шашыратпаңыз, өйткені сыртқы әрекеттің өзгеруі басқа жағдайда детерминирленген тестерді сенімсіз етуі мүмкін.

Ресми тест нөмірлері расталмаған кезде

Қолданбаңыздың ішінде синтетикалық идентификаторларды пайдаланып, провайдер шекарасын mock жасаңыз. Шынайы көрінетін нөмірді ойдан шығарып, оны тестілеуге бөлінген деп ешқашан болжамаңыз: ол нақты жөнелтілімге сәйкес келуі мүмкін.

Live тексеру үшін өзіңіз бақылайтын және қол жеткізуге рұқсатыңыз бар жөнелтілімдерді пайдаланыңыз. Tracking нөмірлерін жалпыға қолжетімді скриншоттардан немесе клиенттермен сөйлесулерден көшірмеңіз. Жөнелтілім тарихын ықтимал құпия ақпарат ретінде қарастырыңыз, өйткені онда орындар, уақыт белгілері және жеткізу туралы ақпарат болуы мүмкін.

Бұрын жеткізілген жөнелтілім парсерді тексеруге көмектесуі мүмкін, бірақ continuous integration үшін нашар тәуелділік болып табылады. Тарихи деректердің қолжетімділігі мен сыртқы жауап өзгеруі мүмкін. Қайталанатын тестер үшін тазартылған fixture сақтап, live тексеруді бөлек жүргізіңіз.

Fixture файлдарын мағыналы жөнелтілім ауысуларының негізінде жасаңыз

Fixture файлдарын құжатталған схемаға және қолжетімді болса, тазартылған нақты жауаптарға сүйеніп жасаңыз. Провайдердің payload fixture файлдарын ішкі қалыптандырылған оқиғалар моделінен бөлек сақтаңыз. Олардың арасындағы adapter-ді тестілеңіз, сонда ішкі mock бұзылған провайдер парсерін жасыра алмайды.

Пайдалы бастапқы жиынтық мына сценарийлерді қамтиды:

  • Әзірге tracking оқиғалары жоқ: қозғалыс немесе жеткізу туралы мәлімдемей, жөнелтілімді сақтаңыз.
  • Жолда: timeline-ды жаңартып, дұрыс тапсырыс байланысын сақтаңыз.
  • Жеткізуге шықты: жеткізу аяқталды деп есептемей, хабарлама саясатыңызды қолданыңыз.
  • Жеткізілді: аяқталғанын жазып, жоспарланған бизнес әрекетін бір рет іске қосыңыз.
  • Exception немесе жеткізу әрекеті жасалды: оны аяқталған жеткізуден ажыратыңыз.
  • Қайтару қозғалысы: әрбір кейінгі сканды бастапқы алушыға қарайғы ілгерілеу деп түсіндірмеңіз.
  • Белгісіз күй: күй сәйкестігін ойдан шығармай, диагностика үшін жеткілікті ақпаратты сақтаңыз.

Осы сценарийлер үшін өзіңіздің қалыптандырылған атауларыңызды пайдаланып, провайдердің құжатталған мәндерін оларға нақты салыстырыңыз. Әртүрлі API бірдей күй белгілерін пайдаланады немесе бір белгі барлық жерде бірдей бизнес мағынаға ие деп болжамаңыз.

Деректер пішінін де өзгертіңіз: бос оқиғалар тізімі, жоқ міндетті емес өрістер, қосымша белгісіз өрістер, Unicode орын атаулары, уақыт белдеуі ығысулары бар уақыт белгілері және қате пішімделген міндетті мәндер. Парсеріңіз үйлесімді толықтыруларды қабылдауы, бірақ қауіпсіз өңделмейтін деректерді қабылдамауы тиіс.

Mock webhook-тарды нақты қабылдау жолы арқылы жіберіңіз

Mock webhook тек соңғы күйді жаңарту функциясын шақырмай, қабылдау бағытын, аутентификация middleware-ін, тексеруді, сақтауды және worker өңдеуін іске қосуы тиіс.

Келесі payload синтетикалық ішкі оқиғаны көрсетеді. Өріс атаулары, event ID және күй мысал ретінде берілген; олар провайдердің callback келісімшарты емес.

{
  "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

Бұл пәрмен тек жергілікті бағыттау мен өңдеуді тексереді. Ол провайдер аутентификациясын көрсетпейді. Әзірлеуге ғана арналған бағытты өндірісте қолжетімсіз ұстаңыз немесе өндірістік қабылдағышты провайдердің құжатталған аутентификация әдісімен және бөлек тест құпиясымен тексеріңіз.

Өндірістік бақылауларды әлсіретпей аутентификацияны тексеріңіз

Егер провайдер қол қойылған callback-тарды көрсетсе, ерікті signature header немесе алгоритм таңдаудың орнына дәл сол схеманы іске асырыңыз. Сұрау байттарына қол қоятын схемаларда тексеру үшін бастапқы body-ді сақтаңыз; JSON-ды талдау және қайта сериализациялау осы байттарды өзгертуі мүмкін.

Қолданылатын жағдайларда дұрыс аутентификацияны, жоқ тіркелгі деректерін, өзгертілген body-лерді және қате signature-ларды тексеріңіз. Құжатталған схема уақыт белгілерін немесе replay қорғауын қамтыса, бұл ережелерді де тестілеңіз. HMAC — стандартталған хабарлама аутентификациясы конструкциясы, бірақ оның болуы белгілі бір tracking провайдері оны пайдаланады дегенді білдірмейді.

Қайталануларды, реттілікті және қалпына келуді тексеріңіз

Бір жаңарту бірнеше рет келсе немесе оқиғалар күтпеген ретпен келсе де, жөнелтілімдерді өңдеу дұрыс күйінде қалуы тиіс. Бұл — белгілі бір провайдердің жеткізу кепілдігі туралы мәлімдеме емес, қорғаныстық тест сценарийлері.

ТестҚолданбаның күтілетін әрекеті
Бір оқиғаны екі рет жіберуБір логикалық оқиғаны сақтап, клиенттерге қайталанатын хабарламалар жібермеу.
Жеткізілгеннен кейін ескі транзит сканын жіберуПайдалы тарихты сақтап, жеткізілді күйін автоматты түрде кері қайтармау.
Бір мезеттегі жаңартуларды жіберуПараллель worker-лерге қарамастан күй ауысуларын бірізді қолдану.
Тұрақты қабылдаудан кейін өңдеуді тоқтатуЖаңа callback талап етпей, сақталған оқиғаны қалпына келтіріп өңдеу.
Қабылдау тұрақты болмай тұрып сақтауды істен шығаруСәтті қабылдауды жалған растау.
Белгісіз жөнелтілімді жіберуАнықталған quarantine немесе қабылдамау саясатын орындау; тапсырыс байланысын ешқашан болжамау.

Оқиға идентификаторы берілсе, қайталануды жою үшін құжатталған тұрақты идентификаторға басымдық беріңіз. Әйтпесе сәйкес өрістерден мұқият шектелген идентификация анықтап, қақтығыстарды тестілеңіз. Tracking нөмірінің өзі оқиға идентификаторы емес, өйткені бір жөнелтілім көптеген заңды жаңартулар жасай алады.

Оқиғалар тарихын ағымдағы жөнелтілім проекциясынан бөлек ұстаңыз. Тарихи скандарды сақтау әрбір кеш келген сканның көрсетілген күйді қайта жазуына мүмкіндік беруді талап етпейді. Сондай-ақ «ең жаңа уақыт белгісін пайдалану» толық ереже емес: түзетулер, қайтару процестері және әртүрлі уақыт белгілерінің мағыналары нақты өңдеуді қажет етеді.

Асинхронды өңдеу кезінде архитектураңызға сәйкес оқиға тұрақты handoff нүктесіне, мысалы, бекітілген inbox жазбасына немесе тұрақты кезекке жеткеннен кейін ғана растаңыз. Провайдердің құжатталған растау талаптарын орындаңыз. HTTP күй кодтарының мағынасын анықтайды, бірақ нақты жіберушінің қайталау кестесі оның жеке келісімшартынан алынуы тиіс.

Бақыланатын live тексеруді жүргізіп, шығарылым критерийлерін белгілеңіз

Детерминирленген тестер өткеннен кейін нақты интеграция арқылы рұқсат етілген жөнелтілімді тіркеп, толық жолды растаңыз. Провайдер жоспарланған жазбаны қабылдағанын, callback конфигурациясы дұрыс ортаға бағытталғанын және кіріс деректерінің күтілетін жөнелтілімге салыстырылғанын тексеріңіз.

Live тексеру кезінде әрбір жөнелтілім күйі пайда болуын талап етпеңіз. Нақты жөнелтілімдер басқарылатын fixture емес. Live іске қосуды байланысты және байқалған келісімшарт үйлесімділігін тексеру үшін, ал сирек немесе жойқын сценарийлерді қамту үшін қайта ойнатылатын fixture файлдарын пайдаланыңыз.

Шығарылым алдында мына нәтижелерді талап етіңіз:

  • Құжатталған сәтті және қате жауаптары, соның ішінде API batch операцияларын қолдаса, элемент деңгейіндегі қателер өңделеді.
  • Бірінші сұрау сәтті орындалған болуы мүмкін кезде тайм-ауттар соқыр түрде жаңа жасау әрекеттерін іске қоспайды.
  • Қайталанатын оқиғалар қайталанатын бизнес әрекеттерін жасай алмайды.
  • Жарамсыз callback-тар жөнелтілім күйін өзгерте алмайды.
  • Worker ақаулары оқиғаларды үнсіз жоғалтпай, қалпына келтірілетін күйде қалдырады.
  • Әзірлеу трафигі нақты клиенттерге хабарлай алмайды немесе өндірістік тапсырыстарды өзгерте алмайды.
  • Журналдар құпияларды ашпай, сұрауларды, қабылданған оқиғаларды, өңдеу нәтижелерін және хабарлама әрекеттерін байланыстырады.

Белгісіз сұраудан, қайталанған callback-тан немесе үзілген worker-ден кейін жүйенің қалай қалпына келетінін және қалыпты жұмыс процесін түсіндіре алсаңыз, шығарылым дайын. Бір сәтті tracking іздеуі жеткіліксіз.

FAQ

Sandbox болмаса, tracking интеграциясын тексере аламын ба?

Иә. Шығыс API шекарасын mock жасап, құжатталған callback fixture файлдарын қайта ойнатыңыз және қалыптандыру мен бизнес ережелеріңізді жергілікті тексеріңіз. Содан кейін нақты байланысты растау үшін рұқсат етілген live жөнелтілімді пайдаланыңыз. Бұл едәуір қамтуды қамтамасыз етеді, бірақ құжатталмаған провайдер әрекетін қайталамайды.

Неліктен tracking сұрауым сәтті орындалады, бірақ оқиғалар қайтарылмайды?

Сұрауды қабылдау мен tracking деректерінің қолжетімділігі — екі түрлі нәтиже. Провайдердің жауап мәліметтерін, тіркеу талаптарын, тасымалдаушыны анықтау ережелерін және оқиғалары жоқ жөнелтілімдерге қатысты құжатталған әрекетті тексеріңіз. Бос timeline-ды толтыру үшін қозғалыс немесе жеткізу ақпаратын ойдан шығармаңыз.

Сәтті mock webhook нақты webhook-тардың келетініне дәлел бола ма?

Жоқ. Ол тек mock тексерген жолды дәлелдейді. Нақты жеткізу провайдер конфигурациясына, жалпыға қолжетімділікке, TLS-ке, аутентификацияға және нақты callback келісімшартына да байланысты. Оларды провайдер қолдайтын тест жеткізуі немесе рұқсат етілген live жұмыс процесі арқылы тексеріңіз.

Өңдеу аяқталмай тұрып HTTP 200 қайтаруым керек пе?

Провайдердің құжатталған растау келісімшартын орындаңыз. Асинхронды дизайнда тұрақты қабылдаудан кейін растаңыз, содан соң worker ішінде өңдеңіз. Тұрақты қабылдауға дейін сәттілік қайтару процесс бірден істен шықса, оқиғаның жоғалуына әкелуі мүмкін.

Клиенттерге хабарламаларды қалай тестілеуім керек?

Барлық әзірлеу хабарламаларын басқарылатын sink-ке жіберіңіз. Қабылдаушыны, шаблонды, іске қосушы ауысуды және жіберулер санын assertion арқылы тексеріңіз. Бір жөнелтілім жаңартуы қайталанатын клиент хабарламаларын тудырмайтынын тексеру үшін сол оқиғаны қайта ойнатып, worker қайталауларын симуляциялаңыз.

Дереккөздер

  • 17TRACK Tracking API — tracking API өнімі үшін ресми бастапқы нүкте.
  • 17TRACK API құжаттамасы — провайдерге тән интеграция келісімшартына арналған анықтамалық; қолданылатын тестілеу және callback талаптарын осы жерден растаңыз.
  • RFC 9110: HTTP Semantics — HTTP жауаптарының мағынасы және сұрауларды қайталауға қатысты мәселелер.
  • RFC 2104: HMAC — callback қауіпсіздігі жөніндегі нұсқаулықта талқыланған стандартталған хабарлама аутентификациясы конструкциясы.