Shipping API жеткізу күйі: күй кодтары, вебхуктар және ерекше жағдайлар туралы ескертулер

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

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

HTTP кодтарын, API нәтижелерін және жөнелту күйлерін ажыратыңыз

«Күй коды» тіркесі үш түрлі қабатқа қатысты болуы мүмкін. Оларды араластыру жаңылыстыратын бақылау тақталары мен қажетсіз клиент хабарландыруларын тудырады.

Қабат	Нені көрсетеді	Түсіндіру мысалы
HTTP жауабы	HTTP сұрауының нәтижесі	200 жауабы HTTP деңгейіндегі сәттілікті білдіреді; бұл сәлемдеменің жеткізілгенін білдірмейді.
API бизнес нәтижесі	Сұралған операцияның провайдердің қолданбалық ережелері бойынша сәтті орындалғаны	API осындай құрылымды пайдаланса, жауап денесі бақылауды тіркеуден бас тартылғанын, тіпті HTTP жауабы сәтті болған жағдайда да хабарлауы мүмкін.
Жөнелту күйі	Сәлемдеменің хабарланған физикалық немесе операциялық күйі	Жолда, алып кетуді күтуде немесе жеткізілді.

HTTP семантикасы стандарты HTTP жауаптарының мағыналарын анықтайды. Мысалы, 202 Accepted сұраудың өңдеуге қабылданғанын, бірақ өңдеу міндетті түрде аяқталмағанын білдіреді. Бұл тасымалдаушының сәлемдемені қабылдағанының дәлелі емес.

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

Тасымалдаушы мәліметтерін жоғалтпай, күй үлгісін жасаңыз

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

Практикалық ішкі үлгі нормаланған күйлердің шағын жиынтығын бастапқы тасымалдаушы оқиғасымен біріктіреді. Нормализация бірізді есеп беруді қолдайды; бастапқы оқиға тексеру үшін қажет мәліметтерді сақтайды.

Ішкі күй мысалы	Мағынасы	Операциялық ескерту
Ақпарат алынды	Жөнелту туралы электрондық ақпарат бар.	Жапсырманың жасалуын физикалық тапсырудың расталуы деп қабылдамаңыз.
Жолда	Бақылау жазбасы жеткізу желісі арқылы қозғалысты көрсетеді.	Бұл кең санат әртүрлі тасымалдау кезеңдерін қамтуы мүмкін.
Жеткізуге шықты	Сәлемдеме жеткізу бағытына шыққаны хабарланды.	Мұны шартсыз жеткізу кепілдігіне айналдырмаңыз.
Алып кетуді күтуде	Алушы сәлемдемені алып кетуі керек.	Алып кету нұсқауларын немесе мерзімдерін тек бастапқы дерек қолдағанда ғана қосыңыз.
Жеткізілді	Бақылау көзі жеткізілгенін хабарлайды.	Жеткізу сканері өздігінен клиенттің алмадым деген шағымын шешпейді.
Ерекше жағдай	Оқиға назар аударуды қажет етуі немесе қалыпты барысты үзуі мүмкін.	Әр ерекше жағдайды жоғалған деп есептемей, себебін сақтаңыз.
Қайтарылуда немесе қайтарылды	Сәлемдеме кері бағытта қозғалып жатыр немесе қайтарудың аяқталғаны хабарланды.	Қайтару барысын бастапқы алушыға жеткізуден бөлек ұстаңыз.
Белгісіз	Қолжетімді ақпаратты сенімді түрде сәйкестендіру мүмкін емес.	Жеткізу күйін ойдан шығармай, сәйкестендіруді немесе дерек жетіспеушілігін зерттеңіз.

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

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

Вебхуктарды тұрақты қабылдау негізінде өңдеуді құрыңыз

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

1. Сұрауды аутентификациялаңыз. Провайдердің құжатталған тексеру әдісін қолданыңыз. Қолтаңбалар қолдау тапса, оларды көрсетілген алгоритм және бастапқы сұрау байттары арқылы тексеріңіз. Қолтаңба тақырыбын ойдан шығармаңыз және әрбір қызмет HMAC қолданады деп болжамаңыз.
2. Пайдалы жүктемені тексеріңіз. Міндетті өрістерді, типтерді, пайдалы жүктеме өлшемін және есептік жазбаңыз басқаратын жөнелтумен байланысын тексеріңіз. Болашақ үйлесімділікті қажетсіз бұзбай, белгісіз қосымша өрістерді өңдеңіз.
3. Растамас бұрын сақтаңыз. Құжатталған сәтті жауапты жібермес бұрын қабылданған оқиғаны сақтаңыз немесе тұрақты кезекке орналастырыңыз. Сақтау сәтсіз болса, оқиғаны қауіпсіз қабылданды деп растамаңыз.
4. Асинхронды өңдеңіз. Мүмкіндігінше күйді сәйкестендіруді, тапсырыстарды жаңартуды және хабарландыру шешімдерін сұрау өңдегішінен тыс орындаңыз.
5. Жанама әсерлерді идемпотентті етіңіз. Қайталанған оқиға басқа қолдау билетін жасамауы немесе сол клиент хабарламасының тағы бір көшірмесін жібермеуі керек.

Нақты растау коды, күту уақыты, қайталап жіберу кестесі және қайта ойнату тәртібі провайдерге байланысты. Бұл мәліметтерді нақты тексеріңіз. «200 қайтарыңыз» деген жалпы нұсқау вебхук келісімін алмастырмайды.

HTTPS пайдаланыңыз және тіркелгі деректерін URL мекенжайлары мен күнделікті журналдарға енгізбеңіз. Сақталған пайдалы жүктемелерге қол жеткізуді бақылаңыз, себебі бақылау деректерінде жеке ақпарат болуы мүмкін. OWASP REST Security Cheat Sheet тасымалдауды қорғау, кірісті тексеру және соңғы нүкте қауіпсіздігі бойынша тиісті нұсқаулар береді.

Нақты жаңартуларды баспай, оқиғаларды қайталанудан қорғаңыз

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

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

Оқиға уақытын қабылдау уақытынан бөлек ұстаңыз

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

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

Ерекше жағдайларды жауапты әрекеттерге айналдырыңыз

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

Шағын бағыттау саясатынан бастаңыз:

• Мекенжай немесе қолжетімділік мәселесі: Мәселені тексеру және тасымалдаушы ұсынатын түзету процесін анықтау үшін клиенттерді қолдау тобына бағыттаңыз. Мүмкін екеніне көз жеткізбей тұрып мекенжайды өзгертетіндігіңізге уәде бермеңіз.
• Алып кету қажет: Дереккөз қолдануға болатын алып кету нұсқауын ұсынғанда алушыға хабарлаңыз. Расталған мерзімді сақтаңыз.
• Кедендік әрекет қажет: Сұралған құжаттарды немесе ақпаратты кім ұсынуы тиіс болса, істі соған сәйкес тағайындаңыз. Кеденге қатысты оқиғаның өзі төлем жасау керектігін білдірмейді.
• Сәтсіз жеткізу әрекеті: Қайта жеткізу немесе алып кету туралы кеңес бермес бұрын хабарланған келесі қадамды тексеріңіз.
• Жіберушіге қайтару: Операциялық тексеруді бастаңыз. Саясатыңыз нақты рұқсат етпесе, тек жалпы бақылау белгісіне сүйеніп автоматты түрде қайтарым жасамаңыз.
• Тасымалдаушы хабарлаған жоғалу немесе зақым: Істі талап-арызға жауапты тұлғаға бағыттап, оқиға дәлелдерін сақтаңыз. Талап-арыз бойынша шешімдерді жалпы кешігуді анықтаудан бөлек ұстаңыз.

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

«Жаңарту жоқ» жағдайын бөлек қарастырыңыз

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

Әмбебап таймер қолданбай, әрекетсіздік шектерін қызметке, бағытқа, жеткізу кезеңіне және бизнес міндеттемесіне қарай анықтаңыз. Қабылдау сканері ешқашан жасалмаған сәлемдемені желіге кіргеннен кейін жаңартылуы тоқтаған сәлемдемеден ажыратыңыз. Тарихи дәлел шектеулі болса, шекті жоғалды деп жариялау үшін емес, тексеруді бастау үшін пайдаланыңыз.

Өзгермеген іс ашық тұрған кезде қайталама ескертулерді басыңыз. Жаңа дәлел пайда болғанда, келісілген кейінгі әрекет орындалмағанда немесе клиентке жеткізу міндеттемесі араласуды талап еткенде эскалация жасаңыз.

Интеграцияның тұрақтылығын жеткізу тиімділігінен бөлек бақылаңыз

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

• Сұрау тұрақтылығы: Аутентификация сәтсіздіктерін, күту уақыттарының асып кетуін, жылдамдық шектеуі жауаптарын, сервер қателерін және қолданбалық деңгейдегі бас тартуларды бақылаңыз.
• Вебхук тұрақтылығы: Тексеру сәтсіздіктерін, растау кідірісін, сақтау сәтсіздіктерін, қайталама жеткізулерді және өңдеу қателерін бақылаңыз.
• Өңдеу тұрақтылығы: Кезек жасын, өңделмеген оқиғаларды, сәйкестендіру сәтсіздіктерін және хабарландыру сәтсіздіктерін бақылаңыз.
• Бақылау жаңалығы: Соңғы бастапқы оқиғадан бері өткен уақытты соңғы сәтті қабылдаудан бері өткен уақыттан бөлек өлшеңіз.
• Операциялық нәтижелер: Шешілмеген ерекше жағдайларды, жауапты тұлғаға тағайындауға кеткен уақытты және мерзімі өткен кейінгі әрекеттерді бақылаңыз.

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

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

Клиент хабарландыруларын қоспас бұрын ақау жағдайларын тексеріңіз

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

• Қайталанған вебхук клиентке арналған бір жоспарланған хабарландыруды жасайды.
• Кеш келген ескі оқиға ағымдағы күйді қате алмастырмайды.
• Белгісіз күй сақталып, белгіленеді, жеткізілді күйіне үнсіз сәйкестендірілмейді.
• Тұрақты сақтаудың сәтсіздігі сәтті растауға әкелмейді.
• Уақытша кейінгі жүйе үзілісі оқиғаларды қайта өңдеуге қолжетімді күйде қалдырады.
• Түзетуден кейін келген жеткізілді оқиғасы тексеруге жарамды болып қалады.
• Бірнеше сәлемдемесі бар тапсырыс тек бір сәлемдеме жеткізілгенде толық жеткізілді деп белгіленбейді.
• API үзілісі инженерлік топқа ескерту жібереді, бірақ клиенттерге сәлемдемелері кешігіп жатыр деп автоматты түрде хабарламайды.

Шығарылым критерийі операциялық бірізділік болуы керек: жөнелту жазбасы, клиент хабарламасы және қолдау әрекеті бірдей негізгі дәлелдерге сәйкес келуі тиіс. Вебхуктің сәтті жауабы ғана жеткізу тәжірибесінің жұмыс істеп тұрғанын дәлелдемейді.

Жиі қойылатын сұрақтар

HTTP 200 сәлемдеменің жеткізілгенін білдіре ме?

Жоқ. Ол сұраудың HTTP деңгейінде сәтті орындалғанын білдіреді. API бизнес нәтижесі мен жөнелту күйі өрістерін бөлек оқыңыз. Вебхук үшін сәтті растау физикалық жеткізуді емес, хабарландырудың қабылданғанын білдіреді.

Бақылау жаңартулары үшін вебхуктарды немесе сауал жіберуді пайдалануым керек пе?

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

«Жеткізілді» күйінен кейін бақылау күйі неге өзгеруі мүмкін?

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

Ерекше жағдай туралы ескерту қаншалықты жылдам жіберілуі керек?

Шұғылдықты қажет әрекетке және расталған мерзімге негіздеңіз. Алушының әрекетін талап ететін мәселе ақпараттық кешігуден өзгеше өңделуі тиіс. Өңдеу жылдамдығы кеш жарияланған тасымалдаушы оқиғасының орнын толтыра алмайды, сондықтан бастапқы және қабылдау уақыт белгілерін де сақтаңыз.

Клиенттер тасымалдаушының бастапқы күйін көруі керек пе?

Әдетте клиенттер түсіндірілмеген кодтан гөрі анық түсіндірме мен қолдау көрсетілетін келесі қадамнан пайда көреді. Қолдау және аудит мақсаттары үшін бастапқы мәліметтерді сақтаңыз. Күйді ешқашан бастапқы оқиға қолдайтыннан күштірек уәдеге айналдырып жеңілдетпеңіз.

Дереккөздер

• RFC 9110: HTTP Semantics — 200 және 202 қоса алғанда, HTTP күй кодтарының мағыналарына арналған анықтамалық.
• OWASP REST Security Cheat Sheet — API және вебхук соңғы нүктелеріне қатысты қауіпсіздік нұсқаулары.
• 17TRACK Tracking API — талқыланған бақылау интеграциясы нұсқасына арналған ресми өнім анықтамасы.
• 17TRACK API Documentation — провайдерге тән интеграция талаптарына арналған ресми анықтамалық; осы нұсқаулықтағы мысал схемалар мен жұмыс процесі жөніндегі ұсыныстар бұл келісімді алмастырмайды.