Skip to main content
Басты бетБлогНұсқаулықтарAPI-ге жібермес бұрын бақылау нөмірлерін қалай тексеруге болады: ұстануға тиіс 7 ереже

API-ге жібермес бұрын бақылау нөмірлерін қалай тексеруге болады: ұстануға тиіс 7 ереже

17TRACK

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

API-ге жібермес бұрын бақылау нөмірлерін тексеру: 7 ереже

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

Тексеру нені растай алады және нені растай алмайды

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

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

Жеті ереже

1. Мәнді мағынасын өзгертпей қалыпқа келтіріңіз

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

Мүмкін болғанда екі мәнді сақтаңыз: бастапқы енгізу және канондық мән. Бастапқы мән қолдау топтарына деректер сапасына қатысты мәселелерді зерттеуге көмектеседі; канондық мән тексеру мен жіберу үшін пайдаланылады. Идентификаторларды өзгертуі мүмкін түрлендірулерден аулақ болыңыз. Тиісті тасымалдаушы немесе API құжаттамасы мұндай әрекетті нақты қолдамаса, әріптерді сандарға автоматты түрде айналдырмаңыз, екіұшты таңбаларды алмастырмаңыз және барлық тыныс белгілерін алып тастамаңыз.

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

2. Негізгі құрылымдық тексерулерден өтпейтін мәндерді қабылдамаңыз

Тасымалдаушыға тән логиканы қолданбас бұрын, мәннің бар-жоғын және қисынды екенін тексеріңіз. Пайдалы тексерулерге ең аз және ең көп ұзындық, рұқсат етілген таңбалар кластары, сондай-ақ мәннің тек бос орындардан немесе “N/A”, “TBD” не “test” сияқты толтырғыштан тұратынын анықтау жатады. Нақты шектер API келісімшартына немесе тасымалдаушы құжаттамасына негізделуі керек. Мысалдардың көпшілігі қысқа болғандықтан ғана әмбебап ең жоғары шекті ойдан шығармаңыз.

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

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

3. Нөмірдің өзіне ғана болжам жасамай, тасымалдаушы мәнмәтінін пайдаланыңыз

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

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

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

4. Бақылау сомаларын ереже құжатталған кезде ғана қолданыңыз

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

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

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

5. Пішімді тексеруді API жарамдылығынан ажыратыңыз

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

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

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

6. Шектелген енгізулер, қайталануды жою және қауіпсіз қайталап жіберу арқылы API-ді қорғаңыз

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

Бизнес үдерісі қайталап тіркеуді талап етпесе, жібермес бұрын қайталанатындарды жойыңыз. Қайталануды жоюдың пайдалы кілті канондық бақылау нөмірін, тасымалдаушыны, тіркелгіні және жөнелтілім мәнмәтінін қамтуы мүмкін. Дұрыс кілт жұмыс үдерісіңізге байланысты; бір идентификатор кейде әртүрлі қызметтерде немесе бизнес жазбаларында қайта пайдаланылуы мүмкін, сондықтан нөмірдің өзі әрқашан жаһандық бірегей деп есептемеңіз.

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

7. Жіберуден кейін нәтижені растаңыз және қате оң нәтижелерді бақылаңыз

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

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

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

Практикалық тексеру реті

Қолдауға ыңғайлы іске асыруда мына реттілік қолданылуы мүмкін:

  1. Сұрауда жол түріндегі мән мен жарамды бизнес жазбасы бар екенін тексеріңіз.
  2. Бастапқы енгізуді сақтап, құжатталған канондық пішімді жасаңыз.
  3. Бос мәндерді, толтырғыштарды, қауіпті таңбаларды және құжатталған ұзындық ауқымынан тыс мәндерді қабылдамаңыз.
  4. Тасымалдаушыны сенімді тапсырыс деректерінен анықтаңыз немесе нақты қолдау көрсетілетін анықтау ағынын пайдаланыңыз.
  5. Тасымалдаушыға тән синтаксис пен бақылау сомасы ережелерін беделді құжаттама қолдаған жағдайда ғана қолданыңыз.
  6. Соңғы нүкте талаптарын, қайталану күйін және қайталап жіберу жарамдылығын тексеріңіз.
  7. Жіберіңіз, жауапты санаттаңыз, нәтижені сақтаңыз және шешілмеген жазбалар үшін кейінгі әрекетті жоспарлаңыз.

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

Іске асыруды тексеру тізімі

  • Бастапқы нөлдер сақталуы үшін бақылау нөмірлерін жол ретінде сақтаңыз.
  • Аудит мүмкіндігі маңызды болса, бастапқы және канондық мәндерді бөлек сақтаңыз.
  • Тасымалдаушы ережелерін шашыраңқы қатты кодталған шарттар емес, нұсқаланатын конфигурация ретінде жүргізіңіз.
  • Әріптерді, цифрларды, дефистерді, бос орындарды, Unicode ұқсастарын, толтырғыштарды және шекаралық ұзындықтарды тексеріңіз.
  • Қол жетімді болған кезде сенімді тасымалдаушы мәнмәтінін пайдаланыңыз.
  • Тұрақты өрнекпен сәтті сәйкестендіру арқылы жөнелтілімнің бар екенін болжамаңыз.
  • Тұрақты тексеру қателерін уақытша API немесе желі қателерінен бөлек санаттаңыз.
  • Пішім ережелерін немесе сұрау логикасын өзгертпес бұрын провайдер құжаттамасын қарап шығыңыз.

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

Тұрақты өрнек бақылау нөмірін тексере ала ма?

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

Жарамсыз болып көрінетін нөмірді API-ге жіберу керек пе?

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

Жөнелтілімді растау үшін бақылау сомасы жеткілікті ме?

Жоқ. Бақылау сомасы қолданылатын жағдайда тек мәннің математикалық ережеге сәйкес келетінін тексереді. Ол тасымалдаушының нөмірді бергенін немесе сәлемдеменің желіге кіргенін растамайды.

Тасымалдаушы белгісіз болғанда не болуы керек?

Жалпы қауіпсіздік тексерулерін орындап, мүмкін болса, тасымалдаушыны анықтауды нақты қолдайтын API жұмыс үдерісін пайдаланыңыз. Әйтпесе тасымалдаушыны үнсіз болжаудың орнына жазбаны толықтыру немесе қолмен тексеру үшін сақтаңыз.

API қателерін қалай өңдеу керек?

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

Дереккөздер

  • 17TRACK API құжаттамасы — бақылау API әзірлеушілеріне арналған сұраулар мен интеграция бойынша нұсқаулық.
  • 17TRACK бақылау API-і — өнім туралы ресми ақпарат және API қолдану жағдайлары.
  • USPS бақылауы — тасымалдаушының ресми бақылау беті және клиенттерге арналған нұсқаулық.
  • UPS бақылауы — тасымалдаушының ресми бақылау беті.