Бақылау API-і қандай деректерді қайтаруы керек? Ағымдағы күйден бөлек 12 өріс?
Бақылау API-і «Жолда» сияқты жай ғана белгі қайтармауы керек. Ағымдағы күйден бөлек, жөнелтілім идентификаторларын, тасымалдаушы туралы ақпаратты, күй туралы егжей-тегжейлі мәліметтерді, тасымалдаушының бастапқы хабарламаларын, оқиғалар тарихын, оқиға уақыт белгілерін, орналасқан жерлерді, жеткізудің болжамды мерзімдерін, ерекше жағдайларды, тасымалдаушылар арасындағы тапсыруларды, жеткізу мәліметтерін және деректердің жаңартылу өзектілігі туралы метадеректерді іздеңіз. Осы 12 деректер тобы әзірлеушілерге сенімді жұмыс процестерін құруға, ал операциялық топтарға әрекет ету үшін жеткілікті контекст алуға көмектеседі.

Бұл әзірлеушілерге, техникалық сатып алушыларға және электрондық коммерция операцияларының топтарына арналған ұсынылатын жауап келісімшарты — әрбір тасымалдаушы немесе API барлық өрісті ұсынады деген мәлімдеме емес. Кейбір мәндердің болмауы заңды жағдай. Жақсы жобалау мұндай олқылықтарды болжаммен толтырмай, оларды ашық көрсетеді.
Бақылау деректерін не пайдалы етеді?
Ағымдағы күй бір тар сұраққа жауап береді: жөнелтілімнің жинақталған күйі қандай? Ол міндетті түрде не болғанын, қашан болғанын, ақпараттың қаншалықты жаңа екенін немесе келесіде не істеу керегін түсіндірмейді.
Мысалы, екі жөнелтілім де «Жолда» деп көрсетілуі мүмкін, бірақ оларға әртүрлі жауап қажет болады. Бірінде нысанда жақында сканерлеу жасалған және ешқандай мәселе тіркелмеген болуы мүмкін. Екіншісінің оқиғалар тарихында шешілмеген мекенжай мәселесі көрсетілуі мүмкін. Тек негізгі күйді оқитын қолданба бұл айырмашылықты байқамай қалуы ықтимал.
Жауапты үш практикалық міндет бойынша бағалаңыз: жөнелтілімді дұрыс тапсырыспен сәйкестендіру, оның қозғалысын дәл түсіндіру және әрекет қажет пе екенін анықтау. Төмендегі өрістер осы міндеттерді қолдайды. Өріс атаулары мысал ретінде берілген; олар әмбебап стандарт немесе белгілі бір провайдердің схемасы емес.
Ағымдағы күйден бөлек бағаланатын 12 өріс
1. Жөнелтілім және бақылау идентификаторлары
Жауапта сипатталып отырған жөнелтілім анық көрсетілуі керек. Пайдалы мәндерге жіберілген бақылау нөмірі, API-дегі бақылау жазбасының идентификаторы және жүйеңіз орындау немесе орама жазбасымен байланыстыра алатын клиент сілтемесі жатады.
Бір тапсырыс бір жөнелтілімге тең деп ойламаңыз. Тапсырыс бірнеше орамаға бөлінуі мүмкін, ал ауыстырылған тауар жаңа жөнелтілімді тудыруы ықтимал. Бақылау жазбаларын орама немесе орындау деңгейінде сақтап, кейін оларды тапсырыспен байланыстырыңыз. Пішім мен бастапқы нөлдер жоғалмауы үшін бақылау нөмірлерін жолдар ретінде сақтаңыз.
2. Тасымалдаушының идентификациясы
Оқуға ыңғайлы тасымалдаушы атауымен бірге тұрақты тасымалдаушы идентификаторын іздеңіз. Мүмкін болса, жауапта қолданбаңыз нақты көрсеткен тасымалдаушы мен автоматты анықтау арқылы таңдалған тасымалдаушы ажыратылуы керек.
Бақылау нөмірі мен оның оқиғаларын түсіндіру кезінде тасымалдаушы контексті маңызды. Анықтау екіұшты болса, интеграцияңыз белгісіз сәйкестікті расталғандай үнсіз көрсетпей, оны шешу тәсілін ұсынуы керек. Қызмет деңгейі туралы ақпаратты бөлек сақтаңыз: тасымалдаушы атауының өзі жөнелтілімнің жедел, пошта немесе басқа қызметті пайдаланатынын көрсетпейді.
3. Қалыпқа келтірілген күй мәліметтері
Негізгі күймен бірге құжатталған егжей-тегжейлі кодты немесе ішкі күйді сұраңыз. Жалпы санат жөнелтілімді ерекше жағдай ретінде сипаттауы мүмкін, ал егжей-тегжейлі күй жеткізу әрекетін, мекенжай мәселесін немесе кеденге байланысты кідірісті көрсетуі мүмкін.
Бизнес логикасы үшін тұрақты кодтарды, ал көрсету үшін оқуға ыңғайлы белгілерді пайдаланыңыз. Провайдердің тасымалдаушы оқиғаларын осы кодтарға қалай түрлендіретінін, соның ішінде белгісіз немесе сәйкестендірілмеген оқиғаларды қалай өңдейтінін тексеріңіз. Қалыпқа келтірілген белгі әртүрлі тасымалдаушы арналарын пайдалануды жеңілдетеді, бірақ қолдау тобына қажет айырмашылықтарды жоймауы керек.
4. Тасымалдаушының бастапқы хабарламалары мен кодтары
Берілген кезде бастапқы оқиға сипаттамасы мен тасымалдаушы оқиғасының кодын сақтаңыз. Бұл мәндер қалыпқа келтірілген күйде жоқ болуы мүмкін контексті, әсіресе тасымалдаушы нақты операциялық тіркесті қолданғанда, қолдау агенттеріне береді.
Бастапқы мәтінді аударылған немесе қайта жазылған сипаттамалардан бөлек ұстаңыз. Әйтпесе клиентке арналған түсіндірмені тасымалдаушының дәл сөзі деп қате қабылдауы мүмкін. Көрсету кезінде тасымалдаушы мәтінін сенімсіз енгізу ретінде қарастырыңыз: оны тиісті түрде экранирлеңіз және орындалатын HTML ретінде көрсетпеңіз.
5. Бақылау оқиғаларының тарихы
Пайдалы жауап тек соңғы оқиғаны емес, жөнелтілім уақыт кестесін де көрсетуі керек. Әр оқиғада мүмкіндігінше идентификатор, күй немесе код, сипаттама, уақыт белгісі және қолжетімді орналасу ақпараты болуы керек.
API толық тарихты, шектеулі аралықты немесе беттелген нәтижелерді қайтаратынын тексеріңіз. Сондай-ақ түзетулер мен қайталанған бақылаулардың қалай көрсетілетінін анықтаңыз. Жауап келісімшарты бұл ретке нақты кепілдік бермесе, қолданбаңыз бірінші элемент әрқашан ең жаңасы деп есептемеуі керек.
6. Оқиға уақыт белгілері және уақыт белдеуі туралы ақпарат
Оқиғаның болған уақыты API оны қабылдаған немесе қайтарған уақыттан өзгеше. Мүмкін болса, екеуін де сақтаңыз. Бұл айырмашылық жаңадан алынған жаңарту бұрын болған оқиғаны сипаттауы мүмкін екенін түсіндіруге көмектеседі.
UTC ығысуы немесе UTC белгіленуі анық көрсетілген уақыт белгілерін сұраңыз. RFC 3339 интернет хаттамаларына, соның ішінде сандық уақыт ығысуларына жарамды уақыт белгісі пішімін анықтайды. Дереккөз тек ығысуы белгісіз жергілікті уақытты берсе, оны үнсіз UTC ретінде қабылдамай, осы белгісіздікті сақтаңыз. Бастапқы дереккөз тек күнді берсе, секунд деңгейіндегі дәлдікті ешқашан білдірмеңіз.
7. Оқиға орындары және жөнелтілім географиясы
Берілген кезде қала, өңір, ел және пошта индексі сияқты құрылымдалған орын құрамдастарын іздеңіз. Оны құрылымдалған өрістерге түрлендіру мағынаның жоғалуына әкелуі мүмкін болса, бастапқы орын жолын да сақтаңыз.
Сканерлеу орны ораманың нақты уақыттағы орналасқан жері болмауы мүмкін. Сол сияқты соңғы хабарланған нысан сәлемдеменің әлі сонда екенін дәлелдемейді. Клиентке арналған беттерде оны соңғы хабарланған орын ретінде сипаттаңыз. Толық емес сканерлеу мәтінінен координаталарды немесе жеткізудің нақты мекенжайын болжамаңыз.
8. Жеткізудің болжамды күні немесе аралығы
Жеткізудің болжамды мерзімі өрісінде бір күн немесе уақыт аралығы көрсетілгені, оны кім жасағаны және соңғы рет қашан жаңартылғаны анық болуы керек. Тасымалдаушы берген болжам мен бөлек есептелген болжам бір-бірінен ажыратылуы тиіс.
Тек күн көрсетілген болжамды нақты келу уақытына айналдырмаңыз. Интеграцияңыз жаңартылған немесе жойылған болжамдарды да өңдеп, бақылау бетінде ескірген уәдені сақтамауы керек. Болжам болмаса, оны негізсіз жорамалмен есептемей, қолжетімсіз екенін көрсетіңіз.
9. Ерекше жағдайдың себебі және қажет әрекет
Ерекше жағдай туралы ақпарат мәселені түсіндіріп, дереккөз қолдаса, әрекетті, жауапты тарапты немесе соңғы мерзімді көрсетуі керек. Жалпы кідіріс туралы хабарлама алушының ақпаратын сұраудан операциялық тұрғыдан өзгеше.
Хабарланған фактілерді өз жұмыс процесіңіздегі шешімдерден бөлек ұстаңыз. Мысалы, сіздің бизнесіңіз белгілі бір уақыт бойы жаңарту болмағаннан кейін қолдау тапсырмасын ашуы мүмкін. Бұл ішкі эскалация ережесі, тасымалдаушы сәлемдемені жоғалды деп жариялады деген дәлел емес. Екіұшты бақылау мәтінінен төлем нұсқауларын немесе құпия ақпарат сұрауларын жасамаңыз.
10. Тасымалдаушылар арасындағы тапсырулар және байланысты бақылау нөмірлері
Жөнелтілім операторлар арасында ауысқан кезде пайдалы деректерге келесі тасымалдаушы, байланысты бақылау нөмірі және бастапқы мен кейінгі жазбалардың арақатынасы жатады. Бұл жеткізу кезеңінде басқа идентификатор қолданылғанда үздіксіздікті сақтауға көмектеседі.
Хабарланған тапсыруды бастапқы тасымалдаушыны қайта жазудың орнына байланыс ретінде қарастырыңыз. Бағыттары немесе бақылау нөмірлері ұқсас көрінгені үшін жазбаларды біріктірмеңіз. Байланыс берілмесе немесе басқаша расталмаса, үздіксіз сапар ойлап таппай, оны шешілмеген күйде қалдырыңыз.
11. Жеткізу нәтижесі және растау сілтемелері
Жеткізу туралы хабарланған кезде жауапта тіркелген жеткізу уақыты мен қолжетімді жеткізу мәліметтері, мысалы қауіпсіз жер сипаттамасы немесе алушы санаты көрсетілуі керек. Тасымалдаушы мен қызмет ұсынса, жеткізуді растау сілтемесі де пайдалы болуы мүмкін.
«Жеткізілді» күйін жоспарланған алушының сәлемдемені жеке өзі қабылдағанының дәлелі деп қарастырмаңыз. Қолтаңбалар, фотосуреттер, есімдер және нақты орындар жеке ақпаратты қамтуы мүмкін. Қолжетімділікті шектеңіз, бұл мәліметтерді жалпыға ортақ бақылау беттерінде жарияламаңыз және растау сілтемелеріне қойылатын авторизация немесе жарамдылық мерзімі талаптарын тексеріңіз.
12. Өзектілік, алу күйі және жауап метадеректері
Жөнелтілімнің соңғы оқиғасын деректерді соңғы сәтті алудан ажырату үшін жеткілікті метадеректерді сұраңыз. Пайдалы мәндерге соңғы сәтті тексеру, соңғы сәтсіз әрекет, жауаптың жасалған уақыты және қайтарылған деректердің кэштелген немесе толық емес екені жатады.
API сұрауының сәтті орындалуы тасымалдаушының жаңа сканерлеуді жариялағанын өздігінен білдірмейді. HTTP жауап семантикасы сұрау нәтижесін сипаттайды; жөнелтілімнің қозғалысы қолданба деректеріне жатады. Уақытша байланыс мәселесі жалған жеткізу ескертуіне айналмауы үшін деректерді алу қателерін жөнелтілімдегі ерекше жағдайлардан бөлек сақтаңыз.
Жетіспейтін деректердің мағынасы анық болуы керек
Өрістің болуы келісімшарттың бір бөлігі ғана. Тобыңыз жоқ мәннің нені білдіретінін де түсінуі керек. Жеткізу болжамы дереккөзде қолжетімсіз болуы, әлі алынбауы немесе жеткізілгеннен кейін қолданылмауы мүмкін. Бұл жағдайлар автоматты түрде бірдей клиент хабарламасын тудырмауы керек.
- Белгісіз: Мән әлі анықталмаған.
- Берілмеген: Дереккөз алынған деректерде бұл мәнді ұсынбаған.
- Қолданылмайды: Өріс бұл жазбаға немесе күйге қатысты емес.
- Деректерді алу сәтсіз аяқталды: Жүйе тиісті іздеуді аяқтай алмады.
Бұл міндетті нақты мәндер емес, ұсынылатын айырмашылықтар. Қай көріністі таңдасаңыз да, оны құжаттаңыз. Жалған күндерді, жарамды жазбаларға ұқсайтын бос нысандарды және нақты орындар деп қате қабылдануы мүмкін әдепкі координаталарды пайдаланбаңыз.
Интеграция алдында жауапты қалай тексеруге болады
Бизнесіңіз пайдаланатын тасымалдаушылардан, қызметтерден және жеткізу бағыттарынан алынған нақты жүктемелерді бағалаңыз. Схема міндетті емес өрісті көрсете алады, бірақ әрбір бастапқы дереккөз оны толтыратынына кепілдік бермейді. 17TRACK интеграциясы үшін осы нұсқаулықтағы тұжырымдамалық өріс атауларын дайын параметрлер ретінде қабылдамай, жауап келісімшартын тексеру үшін ресми Tracking API құжаттамасын пайдаланыңыз.
- Өкілдік үлгі жасаңыз. Жаңадан тіркелген жөнелтілімдерді, белсенді жөнелтілімдерді, жеткізу әрекеттерін, аяқталған жеткізулерді және қолжетімді тапсыру жағдайларын қосыңыз.
- Өрістерді оқиғаларға дейін қадағалаңыз. Көрсетілген күй, соңғы оқиға және жеткізу мәліметтері бірізді жазбаны сипаттайтынын растаңыз. Сәйкессіздіктерді жасырмай, зерттеңіз.
- Кешіктірілген және қайталанған жаңартуларды тексеріңіз. Бір жүктемені қайта өңдеп, жаңасынан кейін ескі оқиғаны алыңыз. Екі жағдайдың да қайталанатын хабарландырулар тудырмайтынын немесе көрсетілген күйді қате өзгертпейтінін растаңыз.
- Жетіспейтін және қате пішімделген мәндерді тексеріңіз. Болжамдар жоқ, орындар белгісіз, күй кодтары бейтаныс және уақыт белгілері толық емес жағдайларды қосыңыз. Қолданба ойдан шығарылған алмастыруларсыз жұмысқа жарамды болып қалуы керек.
- Тасымалдау ақауларын бақылау нәтижелерінен ажыратыңыз. Аутентификация қатесі, күту уақытының аяқталуы немесе қате пішімделген жауап жөнелтілімнің ерекше жағдайы процесіне емес, интеграция қатесі жолына түсуі керек.
- Клиент көрінісін тексеріңіз. Ішкі сілтемелер, бастапқы диагностикалық мәліметтер және жеке ақпарат жалпыға ортақ беттерге немесе хабарландыруларға таралмайтынын тексеріңіз.
Вебхукке негізделген жаңартулар үшін провайдердің құжаттамасындағы жеткізу идентификаторларын, аутентификацияны, қайталап көру тәртібін және қайта ойнатуды өңдеуді де тексеріңіз. Бұл интеграция талаптары, жөнелтілім фактілері емес. Қабылдаушыңыз қайталанған жеткізулерді қауіпсіз өңдеуі және келу реті оқиғалар ретіне тең деп есептемеуі керек.
Қабылдау критерийі практикалық болуы керек: қолданбаңыз қолдау көрсетілмейтін мәлімдемелер жасамай, жөнелтілімді түсіндіре ала ма және операциялық тобыңыз негізделген келесі әрекетті анықтай ала ма? Жақсы анықталған шағын жүктеме түсіндірілмеген міндетті емес мәндерге толы үлкен жауаптан пайдалырақ болуы мүмкін.
Жиі қойылатын сұрақтар
Әрбір жөнелтілімде барлық 12 деректер тобы толтырылуы керек пе?
Жоқ. Жеткізу дәлелі, кейінгі бақылау нөмірлері және жеткізудің болжамды күндері қолжетімсіз немесе қолданылмайтын болуы мүмкін. Барлық жерде толтырылуын талап етудің орнына, өрістердің нақты анықтамалары мен жетіспейтін мәндердің болжамды өңделуін талап етіңіз. Ең маңызды өрістерді нақты жеткізу қоспаңызға қатысты тексеріңіз.
Бастапқы жауапты немесе тек қалыпқа келтірілген өрістерді сақтауымыз керек пе?
Қолданба логикасы үшін қалыпқа келтірілген өрістерді сақтаңыз. Тиісті бастапқы жүктемелерді сақтау жөндеу мен сәйкестендіру өзгерістеріне де көмектесуі мүмкін, бірақ құпиялылық, қауіпсіздік, келісімшарт және сақтау талаптарын ескеріңіз. Қолжетімділікті шектеп, жауапта кездескені үшін ғана құпия мазмұнды сақтамаңыз.
Соңғы оқиғаны қай уақыт белгісі анықтауы керек?
Уақыт белдеулері мен түзетулерді ескере отырып, құжатталған оқиғалар хронологиясы мен провайдердің реттеу ережелерін пайдаланыңыз. Қабылдау уақыты жүйеңіздің оқиға туралы қашан білгенін көрсетеді, оның міндетті түрде қашан болғанын емес. Уақыт белгілері толық емес немесе қайшы болса, нақты реттілік туралы мәлімдемей, екіұштылықты сақтаңыз.
Бақылау API-і сәлемдеменің жоғалғанын растай ала ма?
Дереккөз бұл түсіндірмені нақты қолдағанда ғана жоғалуды тасымалдаушы хабарлаған жағдай ретінде қарастырыңыз. Ұзақ уақыт бойы сканерлеудің болмауы операциялық ережелеріңіз бойынша тексеруді негіздеуі мүмкін, бірақ үнсіздік қана жоғалуды дәлелдемейді. «Ескірген бақылау» мен «жоғалғаны хабарланды» ұғымдарын бөлек ұстаңыз.
«Жеткізілді» күйі клиент шағымын жабуға жеткілікті ме?
Автоматты түрде жеткілікті емес. Ол бақылаудың хабарланған нәтижесін көрсетеді, бірақ алушының дау-жанжалын шешпеуі мүмкін. Қолжетімді жеткізу мәліметтерін, клиент есептік жазбасын және қолдау процесін қарап шығыңыз. Күй белгісін қайшы ақпаратты зерттеудің орнына қолданбаңыз.
Дереккөздер
- 17TRACK Tracking API құжаттамасы — интеграцияның құжатталған өрістері мен әрекетін тексеруге арналған өнімге тән анықтамалық; жоғарыдағы 12 топ редакциялық ұсыныстар болып табылады және оның схемасын қайталамайды.
- RFC 3339: Интернеттегі күн мен уақыт: уақыт белгілері — уақыт белгілерін көрсету және уақыт ығысуы туралы ережелер.
- RFC 9110: HTTP семантикасы — жөнелтілім деңгейіндегі бизнес күйінен бөлек HTTP жауап семантикасы.


