Skip to main content
ДомаБлогВодичиКако да ги користите API-јата за следење на пратки за испраќање проактивни известувања за испорака

Како да ги користите API-јата за следење на пратки за испраќање проактивни известувања за испорака

17TRACK

За испраќање проактивни известувања за испорака со API за следење пратки, поврзете го секој пакет со неговата нарачка, внесувајте ги ажурирањата за следење, претворете ги тие ажурирања во настани релевантни за клиентите и активирајте пораки преку вашата услуга за известувања по е-пошта, SMS или во апликација. Поставете издржлива редица и проверки за дупликати помеѓу влезните податоци за следење и излезните пораки, за повторените или задоцнетите ажурирања да не создаваат збунувачки известувања.

Како да користите API за следење пратки за испраќање проактивни известувања за испорака

Овој водич е наменет за програмери и тимови за е-трговија и оперативно работење кои го градат тој процес. Целта не е да се проследува секое скенирање од превозникот. Целта е да им кажете на клиентите кога се случува значајна промена, што значи таа промена и дали треба да преземат нешто.

Дизајнирајте го процесот на известување пред да го поврзете API-то

API-то за следење пратки обезбедува информации за следењето; вашата апликација одлучува како да ги користи. Третирајте ги видливоста на пратките и комуникацијата со клиентите како одделни одговорности, дури и ако избраната услуга ги нуди и двете.

Практичната архитектура има шест фази:

  1. Поврзување со нарачката: поврзете ги бројот за следење и идентификаторот на превозникот, каде што е потребно, со интерна евиденција на пратката.
  2. Регистрација на следењето: испратете ја или регистрирајте ја пратката според барањата за интеграција на давателот.
  3. Внесување на ажурирањата: примајте повратни повици преку webhook, преземајте ажурирања преку API-барања или комбинирајте ги двата пристапа.
  4. Обработка на настани: проверувајте, нормализирајте, отстранувајте дупликати и проценувајте ги дојдовните настани.
  5. Одлука за известување: изберете дали да известите, кого да контактирате и кој канал и шаблон да ги користите.
  6. Испорака на порака: испратете го известувањето и евидентирајте го одговорот на услугата за пораки.

Чувајте ги информациите за контакт на клиентите во вашиот сопствен систем за нарачки или пораки, освен ако интеграцијата навистина не бара нивно споделување. Услугата за следење обично нема потреба од адресата на е-пошта на клиентот само за вашата апликација да може да поврзе настан за следење со нарачка.

1. Потврдете го договорот за интеграција

Пред да го напишете приемникот, проверете ја документацијата на давателот за автентикација, регистрација на пратки, идентификација на превозникот, поддржани методи за ажурирање, формати на одговори, ограничувања на барањата и постапување со грешки. Кај интеграциите со webhook, проверете и како се автентицираат повратните повици, кој одговор потврдува прием и како се постапува со неуспешните испораки.

За имплементација со 17TRACK, започнете со страницата на API-то за следење на 17TRACK и неговата официјална API документација. Користете го документираниот договор за вашата интеграција, наместо илустративните имиња на полиња во овој водич да ги третирате како полиња за барање или одговор на 17TRACK. Потврдете ги поставувањето на повратните повици, безбедносните барања и ограничувањата специфични за сметката пред имплементацијата.

Изберете го методот за ажурирање според договорот за интеграција:

  • Webhooks: користете повратни повици кога се поддржани и соодветни за вашата инфраструктура. Тие ѝ овозможуваат на апликацијата да ги обработува ажурирањата кога давателот ги испраќа, без постојано да ја бара истата пратка.
  • Периодично проверување: преземајте ги информациите за следење според распоред кога повратните повици не се достапни или не се соодветни. Распоредот нека биде во рамките на документираните ограничувања на барањата.
  • Комбиниран пристап: користете повратни повици за нормална обработка и селективно преземање преку API за усогласување на пратките чии ажурирања изгледаат застарени, ако давателот го поддржува тој процес.

Не им ветувајте на клиентите моментални известувања само затоа што користите webhooks. Вашата апликација не може да пријави настан од превозникот пред податоците за следење од изворот да го направат достапен.

2. Изградете евиденција на пратката што ќе ги издржи реалните нарачки

Користете интерен ID на пратката како примарна референца, а не само бројот за следење. Нарачката може да содржи повеќе пакети, а не треба да се претпоставува дека броевите за следење засекогаш се глобално единствени.

Корисната интерна евиденција вклучува:

  • Интерен ID на нарачката и ID на пратката.
  • Број за следење и идентификатор на превозникот, кога се познати.
  • Референцата на пратката кај давателот, ако е доставена.
  • Тековен нормализиран статус и најнов значаен настан.
  • Време на настанот кај превозникот, вклучувајќи ја временската зона или отстапувањето кога се достапни.
  • Времето кога вашиот систем го примил ажурирањето.
  • Референца до преференциите за комуникација на клиентот.
  • Историја на известувањата и секој активен процес за исклучоци.

Чувајте го времето на настанот одделно од времето на прием. Скенирање што се случило порано може да пристигне по поново скенирање. Ако апликацијата ги подредува настаните само според редоследот на пристигнување, може погрешно да ја врати испорачаната пратка во статус „во транзит“.

Кај поделени нарачки, поврзете ги известувањата со засегнатиот пакет. „Еден пакет од вашата нарачка пристигна“ е попрецизно од „Вашата нарачка пристигна“ кога друг пакет сè уште се движи.

3. Мапирајте ги настаните за следење со одлуките на клиентите

Описите на превозникот се оперативни податоци, а не готови пораки за клиентите. Изградете слој за нормализација што го зачувува оригиналниот настан, а истовремено му доделува интерна категорија што вашите правила за известување можат да ја разберат.

Следните категории се предложени концепти за апликацијата, а не универзален речник на статуси на API:

Интерна категоријаОдлука за известувањеГраница за комуникација
Примени информации за праткатаИспратете ажурирање за подготовка само ако е корисно.Не имплицирајте дека превозникот физички ја презел пратката само врз основа на создавање етикета.
Во транзитРазмислете за известување при првото значајно движење.Потиснете ги рутинските скенирања во објектите, освен ако не го менуваат следниот чекор на клиентот.
На испоракаИзвестете кога поддржан настан го покажува овој статус.Не претворајте го статусот во гарантирано време на пристигнување.
Обид за испорака или потребно преземањеИспратете известување со конкретни инструкции.Вклучете рокови или упатства за преземање само кога се потврдени.
Исклучок при испоракаПроценете ја причината и дали клиентот треба да преземе нешто.Не опишувајте го секој исклучок како изгубен пакет.
ИспорачаноИспратете потврда на ниво на пакет.Не измислувајте примач, место на испорака или доказ за испорака.

Зачувајте ја неизвесноста. Непрепознаен настан треба да влезе во патека за проверка или резервна патека, наместо насилно да се вметне во најблиската позната категорија. Оригиналниот опис нека им биде достапен на службите за поддршка при решавање проблеми.

4. Примајте ажурирања без губење или дуплирање работа

Вашата webhook крајна точка треба да го провери барањето, трајно да го зачува прифатеното ажурирање и да го врати потврдувањето што го бара давателот. Генерирајте пораки асинхроно, наместо да чекате услуга за е-пошта или SMS за време на барањето за повратен повик.

Имплементирајте го документираниот метод на давателот за проверка на повратните повици. Не измислувајте заглавје за потпис и не претпоставувајте дека секој давател ја користи истата шема за автентикација. Исто така, наметнете HTTPS, ограничувања на големината на барањата, проверка на корисниот товар и соодветни контроли на пристап.

Поедноставениот тек на обработка изгледа вака. Ова се операции на ниво на апликација, а не работен пример на SDK:

прими повратен повик
  провери го барањето со користење на документираниот механизам на давателот
  провери го корисниот товар
  атомски зачувај го прифатениот корисен товар и стави го во редица за обработка
  врати го документираното потврдување

обработи го ажурирањето од редицата
  пронајди ја интерната пратка
  нормализирај ги релевантните настани
  игнорирај ги веќе обработените настани
  процени ја хронологијата и преминот на состојбата
  креирај задача за известување ако политиката дозволува
  заедно потврди ги состојбата и задачата

испрати ја задачата за известување
  провери ги преференциите на примачот и правилата за потиснување
  испрати ја пораката до услугата за пораки
  евидентирај го резултатот и повтори само кога е соодветно

Атомските чекори се важни. Ако апликацијата зачува промена на статусот, но се урне пред да ја создаде задачата за известување, клиентот можеби никогаш нема да го добие известувањето. Трансакцискиот outbox е една можност за дизајн: зачувајте ја промената на состојбата и задачата што чека во истата трансакција на базата, а потоа оставете работникот да ја испрати задачата.

Експлицитно постапувајте со непознати референци на пратки. Ставете ги во карантин за истрага или усогласување, наместо да погодувате кој клиент треба да добие известување.

5. Додајте заштита од дупликати и хронолошки проверки

Дизајнирајте го приемникот да толерира повторени повратни повици и повторни обиди на работниците. Претпочитајте стабилен идентификатор на настанот кај давателот кога е документиран. Во спротивно, создајте детерминистички отпечаток на настанот од соодветни полиња, како што се интерниот ID на пратката, кодот на настанот, времето на настанот и локацијата. Тестирајте го тој отпечаток со реални корисни товари пред да се потпрете на него.

Отстранувањето дупликати на настани и потиснувањето известувања решаваат различни проблеми. Отстранувањето дупликати спречува истиот настан да се обработи двапати. Потиснувањето спречува неколку различни скенирања да создадат суштински иста порака за клиентот.

Дефинирајте идентитет на известувањето околу деловниот настан. Потврдата за испорака може да го користи ID-то на пратката и пресвртницата „испорачано“. За обид за испорака може да биде потребен идентитет специфичен за обидот, бидејќи подоцнежен обид може да биде вистински нов настан.

Кај ажурирањата што пристигнуваат по погрешен редослед, споредете ги временските ознаки на настаните и проценете ги дозволените премини на состојбата. Не претпоставувајте дека повратниот повик содржи само ново скенирање; проверете дали неговата документирана структура претставува поединечен настан, снимка или историја. Контрадикторните ажурирања насочете ги кон усогласување, наместо тивко да ги отфрлите сите корекции.

6. Напишете пораки што објаснуваат што следува

Секое известување треба да го наведе релевантниот пакет, потврдената промена и следниот чекор на клиентот. Вклучете безбедна врска за следење и препознатлива референца на нарачката. Избегнувајте откривање целосни адреси или непотребни лични информации во SMS-пораки и прегледи на заклучен екран.

На пример:

  • На испорака: „Вашиот пакет за нарачката {order_reference} е на испорака. Следете го неговото движење тука: {tracking_link}.“
  • Обид за испорака: „Превозникот пријави обид за испорака на вашиот пакет. Проверете ја страницата за следење за достапните следни чекори: {tracking_link}.“
  • Испорачано: „Превозникот го означи вашиот пакет за нарачката {order_reference} како испорачан. Погледнете ги достапните детали за испораката: {tracking_link}.“

Прикажувајте ги местодржачите само од проверени податоци. Ако е достапна и соодветна проценка на испораката за прикажување, означете ја како проценка. Ако недостасува, изоставете ја наместо да измислувате датум.

Кај исклучоците, разликувајте проблем со пратката од задача за клиентот. Прекинот може да бара само објаснување; потврден проблем со адресата може да бара дејство. Не ги испраќајте клиентите на страница за плаќање или поставување документи само врз основа на непроверена содржина за следење во слободен текст.

Избирајте канали според преференциите на клиентите, дозволите за каналите, итноста и применливите правила. Проверете ги барањата за согласност, откажување и периоди без известувања за јурисдикциите и каналите за пораки што ги користите. Известувањата за услугата за испорака чувајте ги одделно од промотивните кампањи, наместо да претпоставувате дека истите дозволи важат за двете.

7. Дефинирајте што се случува кога следењето ќе престане да се ажурира

Проактивната комуникација треба да го опфати и недостигот на напредок, а не само новите настани, но самото молчење не докажува дека пратката е доцнета или изгубена.

Создадете правило за застарено следење со користење на нивото на услугата, маршрутата, последниот значаен настан и секоја поддржана проценка на испораката. Поставете ги праговите врз основа на оперативните податоци и процесот за поддршка, наместо да применувате еден универзален период на чекање за секоја пратка.

Кога ќе се активира тоа правило, проверете дали обработката била пропуштена, усогласете се со изворот за следење каде што е поддржано и одлучете дали да отворите интерна задача за поддршка. Ако го известите клиентот, користете формулација што го одразува она што го знаете: „Не сме добиле ново ажурирање за следење“ се разликува од „Вашиот пакет е изгубен“.

Доделете одговорно лице за нерешените исклучоци. Систем за известување што постојано пријавува проблем без да создава патека до решение може да ја зголеми фрустрацијата на клиентите.

8. Тестирајте го целиот тек пред да овозможите автоматско испраќање

Прво извршете го процесот во режим на набљудување: внесувајте реални или одобрени тест-настани, генерирајте предложени известувања и проверувајте ги резултатите без да контактирате со клиентите.

  • Повторно репродуцирајте идентичен повратен повик и потврдете дека не создава нова порака.
  • Обработете постар настан „во транзит“ по настан „испорачано“ и проверете ја добиената состојба.
  • Тестирајте временски ознаки што недостасуваат, непознати статуси и неправилни корисни товари.
  • Симулирајте дефект на базата пред потврдувањето и дефект на работникот по зачувувањето.
  • Тестирајте истекувања на времето кај услугата за пораки, вклучувајќи неизвесен одговор кога услугата можеби веќе ја прифатила пораката.
  • Потврдете дека поделбата на пратките создава формулации специфични за пакетите.
  • Проверете ги примачите што се откажале, неважечките контактни податоци и постапувањето во периоди без известувања.
  • Потврдете дека врските за следење не откриваат информации за нарачката на друг клиент.

Следете ги прифатените повратни повици, неуспешната обработка, староста на редицата, задачите за известување, потиснувањето дупликати и резултатите од испраќањето пораки. Мерете ја латентноста на обработката од времето на прием во вашиот систем одделно од староста на настанот кај превозникот. Оваа разлика помага да се утврди дали бавното известување било предизвикано од достапноста на податоците од изворот или од вашиот сопствен процес.

Започнете со мал број добро разбрани пресвртници. Проширувајте ги правилата дури откако тимовите за поддршка и операции ќе се согласат дека пораките се точни, применливи и вредни за примање.

Најчесто поставувани прашања

Дали API-то за следење пратки автоматски испраќа е-пошта или SMS-пораки?

Не мора да значи. Пристапот до податоците за следење и испраќањето пораки до клиентите се одделни можности. Проверете го документираниот опсег на услугата. Во прилагодена интеграција, вашата апликација може да ги обработува ажурирањата за следење и да испраќа известувања преку одделна услуга за пораки.

Дали треба да ги известувам клиентите за секое скенирање при следење?

Обично не. Приоритизирајте ги значајните пресвртници и настаните што бараат дејство. Неколку скенирања во објектите може да претставуваат нормален транзит без да го менуваат она што клиентот треба да го знае. Деталната историја чувајте ја на страницата за следење.

Може ли да гарантирам известувања за испорака во реално време?

Може да поставите и следите цел за обработка откако вашиот систем ќе добие ажурирање. Не можете да гарантирате кога превозникот ќе евидентира или објави скенирање. Опишете ја услугата со формулации што ја одразуваат таа зависност.

Како можам да спречам дуплирани пораки за испорака?

Користете трајно отстранување дупликати на настани, одделен идентитет на известувањето за секоја деловна пресвртница и трансакциско создавање задачи. Каде што услугата за пораки поддржува идемпотентност, користете ја како дополнителна заштита. Проверката на дупликати само во меморија нема да преживее рестартирања или повеќе работници.

Што треба да се случи ако превозникот го коригира статусот „испорачано“?

Зачувајте ги двата настани и усогласете ја состојбата на пратката. Ако корекцијата значајно влијае врз клиентот, испратете јасна корекција или насочете го случајот кон поддршка според вашата политика. Не правете го статусот „испорачано“ трајно неповратен само за да го поедноставите кодот.

Извори

Следните официјални ресурси се референци за имплементација на интеграцијата со 17TRACK, разгледана погоре. Интерната шема, правилата за известување и текот на обработката во овој водич се архитектонски препораки, а не цитирани API-договори.

  • API за следење на 17TRACK — официјална почетна точка за проценка на интеграцијата со API-то.
  • Документација за API-то на 17TRACK — референца за форматирањето на барањата специфично за давателот, автентикацијата, операциите за следење и барањата за интеграција.