Skip to main content
Басты бетБлогНұсқаулықтарAPI арқылы бақылау нөмірін қалай тіркеуге болады: сұрау өрістері, тасымалдаушы кодтары және жауаптар

API арқылы бақылау нөмірін қалай тіркеуге болады: сұрау өрістері, тасымалдаушы кодтары және жауаптар

17TRACK

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

API сұрауының өрістері арқылы бақылау нөмірін қалай тіркеуге болады

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

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

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

Қолданбаңызда мына үш оқиғаны бөлек ұстаңыз:

  • Жөнелтілім жасалды: тасымалдау жүйеңіз бақылау нөмірін тағайындады.
  • Тіркеу қабылданды: бақылау қызметі жөнелтілімді бақылауға қабылдады.
  • Бақылау ақпараты алынды: тасымалдаушы оқиғалары бақылау қызметі арқылы қолжетімді болды.

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

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

API шақыруын жазбас бұрын сұрау өрістерін дайындаңыз

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

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

Бақылау нөмірін идентификатор ретінде қарастырыңыз

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

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

Тапсырыс сілтемелерін жөнелтілім идентификаторларынан бөлек ұстаңыз

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

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

Дұрыс тасымалдаушы кодын таңдаңыз

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

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

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

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

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

Мысал: 17TRACK тіркеу сұрауын жіберу

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

curl --request POST \
  --url 'https://api.17track.net/track/v2.2/register' \
  --header "17token: ${TRACKING_API_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "number": "YOUR_TRACKING_NUMBER"
    }
  ]'

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

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

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

Жауапты үш деңгейде оқыңыз

Сенімді жауап өңдегіші үш бөлек сұраққа жауап береді: сұрау қызметке жетті ме, қызмет операцияны қабылдады ма және әрбір жөнелтіліммен не болды?

1. HTTP және тасымалдау нәтижесі

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

2. Сұрау деңгейіндегі нәтиже

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

Сандық қолданба коды HTTP күй коды сияқты мағына береді деп болжамаңыз. Олар әртүрлі қабаттарға жатады және бөлек түсіндірілуі керек.

3. Жөнелтілім деңгейіндегі нәтиже

Топтамалық тіркеу кезінде жіберілген әрбір элементті есепке алыңыз. Жауап қабылданған және қабылданбаған жөнелтілімдерді ажыратуы мүмкін; талдағышыңыз таңдалған нұсқаға арналған нақты құжатталған схеманы ұстануы керек. Бір элемент сәтті болғаны үшін бүкіл топтаманы тіркелген деп белгілемеңіз.

Провайдер жауаптарын өзіңіздің тұрақты қолданба күйлеріңізге қалыпқа келтіріңіз. Мысалы, дерекқорыңызда accepted, rejected және uncertain күйлері болуы мүмкін. Бұл ұсынылатын ішкі күйлер, 17TRACK жауабының нақты мәндері емес. Әзірлеушілер сәйкессіздіктерді зерттей алуы үшін провайдердің бастапқы жауабын тиісті сақтау және қолжетімділік саясатына сай сақтаңыз.

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

Шексіз цикл жасамай қайта әрекет жасауды өңдеңіз

Қайта әрекет жасау саясаты тек ерекше жағдайдың орын алуына емес, қатенің түріне байланысты болуы керек.

  • Жарамсыз енгізу: қайта әрекет жасамас бұрын өрісті түзетіңіз. Өзгертілмеген жарамсыз сұрауды қайталау көмектесуі екіталай.
  • Аутентификация қатесі: тіркелгі деректері мен тіркелгі конфигурациясын тексеріңіз. Бірдей сәтсіз топтаманы қайта-қайта жібермеңіз.
  • Жиілік шектеуі: құжатталған шектеулерді және қолданылатын қайта әрекет нұсқауларын орындаңыз. Бірден параллель қайталаулардың орнына шектеулі кідірісті пайдаланыңыз.
  • Уақытша қызмет қатесі: әрекет саны мен уақыт бюджеті белгіленген шекте қайта әрекет жасаңыз.
  • Жіберуден кейінгі күту уақыты: бірінші әрекет сәтсіз болды деп есептемес бұрын, құжатталған API тәртібі арқылы жөнелтілімнің тіркелу күйін салыстырып тексеріңіз.
  • Қайталануға қатысты жауап: жөнелтілімнің бұрын тіркелгенін және қолданба жазбаңызбен дұрыс байланыстырылғанын тексеріңіз.

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

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

Тіркеуді бақылау жаңартуларынан бөлек бақылаңыз

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

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

Өндірістік ортадағы практикалық тексеру мына сұрақтарға жауап беруі керек:

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

Электрондық коммерция операцияларында операциялық тапсыру API шақыруының өзі сияқты маңызды. Әзірлеушілер тасымалдау және талдау қателеріне жауапты болуы керек; тасымалдау немесе орындау топтары қате жапсырмаларды, тасымалдаушы сәйкестендірулерін және жетіспейтін жөнелтілім ақпаратын зерттей алуы керек.

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

Бірінші тасымалдаушы сканерлеуінен бұрын бақылау нөмірін тіркей аламын ба?

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

Әрқашан тасымалдаушы кодын беруім керек пе?

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

Неліктен API HTTP сәтті жауабын қайтарды, бірақ жөнелтілім сәтсіз болды?

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

Тіркеу сұрауының күту уақыты аяқталғанда не істеуім керек?

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

Тіркеу бақылау хабарландыруларын автоматты түрде баптай ма?

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

Дереккөздер

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