Skip to main content
Басты бетБлогНұсқаулықтарЖөнелтілімдерді қадағалау API интерфейстерін жеткізу туралы алдын ала хабарландырулар жіберу үшін қалай пайдалану керек

Жөнелтілімдерді қадағалау API интерфейстерін жеткізу туралы алдын ала хабарландырулар жіберу үшін қалай пайдалану керек

17TRACK

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

Проактивті жеткізу хабарламаларын жіберу үшін Shipment Tracking API қалай пайдаланылады

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

API-ді қоспас бұрын хабарлама жіберу жұмыс процесін жобалаңыз

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

Практикалық архитектура алты кезеңнен тұрады:

  1. Тапсырыспен байланыстыру: қажет болған жағдайда бақылау нөмірі мен тасымалдаушы идентификаторын ішкі жөнелтілім жазбасына байланыстырыңыз.
  2. Бақылауды тіркеу: жөнелтілімді провайдердің интеграция талаптарына сәйкес жіберіңіз немесе тіркеңіз.
  3. Жаңартуларды қабылдау: webhook callback-терін қабылдаңыз, API сұраулары арқылы жаңартуларды алыңыз немесе екі тәсілді біріктіріңіз.
  4. Оқиғаларды өңдеу: кіріс оқиғаларды тексеріңіз, қалыпқа келтіріңіз, қайталанатындарын алып тастаңыз және бағалаңыз.
  5. Хабарлама туралы шешім: хабарлама жіберу керек пе, кімге хабарласу керек және қай арна мен үлгіні пайдалану керегін таңдаңыз.
  6. Хабарламаны жеткізу: хабарламаны жіберіп, хабарлама қызметінің жауабын тіркеңіз.

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

1. Интеграция келісімшартын растаңыз

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

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

Жаңарту әдісін интеграция келісімшартына сәйкес таңдаңыз:

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

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

2. Нақты тапсырыстарға төтеп беретін жөнелтілім жазбасын жасаңыз

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

Пайдалы ішкі жазба мыналарды қамтиды:

  • Ішкі тапсырыс ID-сі мен жөнелтілім ID-сі.
  • Бақылау нөмірі және белгілі болса, тасымалдаушы идентификаторы.
  • Провайдер берген жөнелтілім сілтемесі.
  • Ағымдағы қалыпқа келтірілген күй және соңғы маңызды оқиға.
  • Қолжетімді болса, уақыт белдеуі немесе ығысуы көрсетілген тасымалдаушы оқиғасының уақыты.
  • Жүйеңіздің жаңартуды қабылдаған уақыты.
  • Клиенттің коммуникация параметрлеріне сілтеме.
  • Хабарлама тарихы және кез келген белсенді ерекше жағдай жұмыс процесі.

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

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

3. Бақылау оқиғаларын клиент шешімдерімен сәйкестендіріңіз

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

Төмендегі санаттар — ұсынылатын қолданбалық ұғымдар, әмбебап API күй сөздігі емес:

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

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

4. Жұмысты жоғалтпай немесе қайталамай жаңартуларды қабылдаңыз

Webhook endpoint-іңіз сұрауды тексеріп, қабылданған жаңартуды сенімді түрде сақтап, провайдер талап ететін растауды қайтаруы керек. Callback сұрауы кезінде email немесе SMS қызметін күтпей, хабарлама жасауды асинхронды түрде орындаңыз.

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

Жеңілдетілген өңдеу ағыны мынадай:

receive callback
  verify request using documented provider mechanism
  validate payload
  persist accepted payload and enqueue processing atomically
  return documented acknowledgment

process queued update
  find internal shipment
  normalize relevant events
  ignore already-processed events
  evaluate chronology and state transition
  create notification job if policy permits
  commit state and job together

send notification job
  check recipient preferences and suppression rules
  submit message to messaging service
  record result and retry only when appropriate

Атомарлық қадамдар маңызды. Қолданбаңыз күй өзгерісін сақтап, хабарлама тапсырмасын жасамай тұрып істен шықса, клиент ескертуді ешқашан алмауы мүмкін. Транзакциялық outbox — бір нұсқа: күй өзгерісі мен күтілетін тапсырманы бір дерекқор транзакциясында сақтап, кейін worker-ге тапсырманы жіберуге мүмкіндік беру.

Белгісіз жөнелтілім сілтемелерін нақты өңдеңіз. Қай клиентке хабарлау керегін болжаудың орнына оларды тексеруге немесе салыстырып тексеруге оқшаулаңыз.

5. Қайталанудан қорғау мен хронологиялық тексерулерді қосыңыз

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

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

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

Реті бұзылған жаңартулар үшін оқиға уақыттарын салыстырып, рұқсат етілген күй ауысуларын бағалаңыз. Callback тек жаңа сканды қамтиды деп есептемеңіз; оның құжатталған құрылымы жеке оқиғаны, snapshot-ты немесе тарихты білдіре ме, тексеріңіз. Қарама-қайшы жаңартуларды барлық түзетулерді үнсіз жоюдың орнына салыстырып тексеруге жіберіңіз.

6. Келесі не болатынын түсіндіретін хабарламалар жазыңыз

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

Мысалы:

  • Жеткізуге шықты: «{order_reference} тапсырысына арналған сәлемдемеңіз жеткізуге шықты. Оның қозғалысын мына жерден бақылаңыз: {tracking_link}.»
  • Жеткізу әрекеті жасалды: «Тасымалдаушы сәлемдемеңізді жеткізу әрекеті жасалғанын хабарлады. Келесі қолжетімді қадамдарды бақылау бетінен тексеріңіз: {tracking_link}.»
  • Жеткізілді: «Тасымалдаушы {order_reference} тапсырысына арналған сәлемдемеңіз жеткізілді деп белгіледі. Қолжетімді жеткізу мәліметтерін көріңіз: {tracking_link}.»

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

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

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

7. Бақылау тоқтап қалған кезде не болатынын анықтаңыз

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

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

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

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

8. Автоматты жіберуді қоспас бұрын толық жолды тексеріңіз

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

  • Бірдей callback-ті қайта ойнатып, оның тағы бір хабарлама жасамайтынын растаңыз.
  • Жеткізілген оқиғадан кейін бұрынғы жолдағы оқиғаны өңдеп, нәтижелік күйді тексеріңіз.
  • Уақыт белгілері жоқ, белгісіз күйлерді және қате payload-тарды сынаңыз.
  • Растауға дейінгі дерекқор ақауын және сақтаудан кейінгі worker ақауын модельдеңіз.
  • Хабарлама қызметі хабарламаны қабылдап қойған болуы мүмкін белгісіз жауапты қоса, хабарлама тайм-ауттарын тексеріңіз.
  • Бөлінген жөнелтілімдер сәлемдемеге тән мәтін жасайтынын растаңыз.
  • Хабарламадан бас тартқан алушыларды, жарамсыз байланыс деректерін және тыныш уақытты өңдеуді тексеріңіз.
  • Бақылау сілтемелері басқа клиенттің тапсырыс ақпаратын ашпайтынын растаңыз.

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

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

FAQ

Shipment tracking API email немесе SMS хабарламаларын автоматты түрде жібере ме?

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

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

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

Жеткізу туралы хабарламаларға нақты уақыт режимінде кепілдік бере аламын ба?

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

Жеткізілді деген қайталанатын хабарламалардың алдын қалай аламын?

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

Тасымалдаушы жеткізілді деген күйді түзетсе не болуы керек?

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

Дереккөздер

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

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