Како да ги поврзете податоците за следење на пратките со Oms: Мапирање на нарачки и правила за синхронизација
За да ги поврзете податоците за следење на пратките со системот за управување со нарачки (OMS), мапирајте го секој следен пакет со интерен запис за пратка, а потоа поврзете ја пратката со нејзината нарачка и линиите за исполнување. Примајте ги ажурирањата за следење преку поддржаниот интерфејс на давателот, зачувајте ги оригиналните настани и применувајте експлицитни правила за дупликати, задоцнети ажурирања, статусот на пратката и завршувањето на нарачката. Не користете го само бројот за следење како идентификатор на нарачката и не дозволувајте еден настан за испорака автоматски да затвори нарачка со повеќе пакети.
Овој водич е наменет за инженери за интеграција и тимови за е-трговски операции кои ја имплементираат оваа поврзаност. Препорачаниот дизајн ги одвојува набљудувањата на превозникот од деловните одлуки: податоците за следење го опишуваат патувањето на пакетот, додека OMS одлучува што значи тоа патување за исполнувањето, комуникацијата со клиентите и затворањето на нарачката.
Дефинирајте кој систем го поседува секој запис
Пред да изградите API-поврзување, усогласете ја сопственоста со администраторот на OMS, тимот за исполнување и тимот за корисничка поддршка. Во спротивно, технички успешната интеграција сепак може да ги пребрише валидните деловни податоци.
- OMS: Ги поседува нарачките, линиите на нарачките, потребните количини, откажувањата и правилата за завршување на нарачките.
- Систем за исполнување: Ги поседува записите за пратки или пакети што ги создава, вклучувајќи ги распределбите при пакување и доделувањата на етикети. Тоа може да биде самиот OMS или одделен магацински систем.
- Давател на следење: Ги обезбедува набљудувањата за следење и сите класификации на статуси дефинирани од давателот.
- Интеграциски слој: Ги поседува вкрстените референци на идентификаторите, обработката на настани, нормализацијата, обработката на повторни обиди и записите за ревизија на синхронизацијата.
Сметајте ги овие како препорачани граници, а не како претпоставки за вашиот софтвер. Документирајте ги исклучоците. На пример, ако магацинот може да замени етикета за испорака, интеграцијата треба да добие експлицитно ажурирање од тој систем наместо да претпостави дека новонабљудуваниот број го заменува стариот.
Изградете мапирање од нарачка до пакет пред да ги синхронизирате статусите
Практична релација е нарачка → исполнување → пакет → доделување за следење. Вашиот OMS може да користи други имиња или да комбинира некои од овие записи. Зачувајте ги релациите дури и ако структурата на базата на податоци е различна.
Една нарачка може да има повеќе исполнувања, а едно исполнување може да содржи повеќе пакети. Пакетот може да добие и заменско доделување за следење или поврзан идентификатор за последната милја. Овие идентификатори не треба да создаваат дополнителни нарачани количини.
| Запис | Препорачани полиња | Намена |
|---|---|---|
| Нарачка | ID на закупец или продавница, непроменлив OMS ID на нарачката | Ги одвојува трговците и избегнува зависност од прикажаните броеви на нарачки. |
| Исполнување | ID на исполнување, ID на нарачка, ID-ја и количини на распределените линии | Идентификува кои купени артикли се исполнуваат. |
| Пакет | Интерен ID на пакетот, ID на исполнување, распределби на пакетот кога се достапни | Обезбедува стабилен идентитет независен од етикетите за следење. |
| Доделување за следење | ID на доделување, ID на пакет, сметка на давателот, идентификатор на превозникот, број за следење, период на активност | Ги поврзува дојдовните набљудувања за следење со точниот пакет и животниот циклус на доделувањето. |
Поврзувајте ги ажурирањата преку зачувана вкрстена референца
Кога ќе се создаде пратка, зачувајте ги нејзините интерни ID-ја пред да ја регистрирате за следење. Зачувајте го секој ID на записот за следење издаден од давателот и вратен од документираниот процес на регистрација. Ако давателот поддржува референца на трговец, користете непрозирна интерна референца и локално зачувајте го мапирањето.
За дојдовните ажурирања, најпрво разрешете го зачуваниот ID на записот на давателот во рамките на точната сметка на давателот и закупецот. Ако тој идентификатор не е достапен, користете ја документираната комбинација од бројот за следење, идентитетот на превозникот, контекстот на сметката и историјата на доделувањето. Третирајте го ова како стратегија за пребарување, а не како гаранција дека комбинацијата е глобално единствена.
Не поврзувајте според името на клиентот, адресата на е-пошта или неповрзан прикажан број на нарачка. Чувајте ги броевите за следење како низи за да се зачуваат почетните нули. Избегнувајте отстранување знаци или промена на големи и мали букви, освен ако релевантниот договор со превозникот или давателот дозволува таква нормализација.
Ако пребарувањето не врати совпаѓање или врати повеќе можни совпаѓања, ставете го ажурирањето во карантин за истрага. Неразрешениот настан е побезбеден од самоуверено ажурирање на нарачката на погрешен клиент.
Ракувајте со поделени нарачки без измислување распределби на пакети
Разгледајте илустративна нарачка што содржи три единици. Пакетот A носи две единици, а пакетот B една. Испораката на пакетот A значи дека постојат докази за испорака на две единици; тоа не значи дека целата нарачка е испорачана.
Ако системот за исполнување бележи само дека двата пакети припаѓаат на истото исполнување, не измислувајте распределби на ниво на единица. Сè уште можете да пресметате дали сите потребни пакети се испорачани, но известувањето за испорака на ниво на артикл треба да остане недостапно или експлицитно неизвесно додека не постојат податоци за распределба.
Поврзете го API-то за следење преку траен внесувачки слој
Користете цевковод што ја одвојува комуникацијата со давателот од запишувањата во OMS:
Создавање пратка → регистрација за следење → дојдовно ажурирање или закажано преземање → трајно складирање на настанот → мапирање и нормализација → ажурирање на OMS → усогласување
За имплементација со 17TRACK, релевантни почетни точки се страницата на производот Tracking API и официјалната API документација. Потврдете го применливиот интерфејс за регистрација, идентификаторите на превозниците, опциите за доставување ажурирања, барањата за автентикација, дефинициите на статусите и ограничувањата на сметката пред да го имплементирате адаптерот. Моделот на податоци во овој водич е препорака за интеграција, а не тврдење дека 17TRACK ги користи овие имиња на полиња или обезбедува изворен конектор за вашиот OMS.
Ако избраниот давател поддржува webhook-и, автентицирајте ги дојдовните барања користејќи го неговиот документиран механизам и трајно зачувајте ги прифатените пораки пред да ги потврдите. Бавната работа на OMS нека биде надвор од патеката на барањето. Следете го вистинскиот договор на давателот за потврда и повторни обиди наместо да претпоставувате одредено тело на одговор или истек на време.
Ако е потребно периодично преземање, зачувајте го напредокот на преземањето таму каде што API-то го поддржува тоа, контролирајте ја истовременоста и следете ги документираните ограничувања на стапката. Ниту приемот на webhook ниту успешното барање за преземање не докажуваат дека OMS е ажуриран; бележете ги тие исходи одделно.
Дефинирајте правила за синхронизација што издржуваат повторни обиди и задоцнети настани
1. Направете ја обработката идемпотентна
Двократната обработка на истото набљудување не треба да дуплира пратка, двапати да ги зголеми количините или повторно да испрати исто известување до клиентот. HTTP не ја прави произволната POST операција идемпотентна; интеграцијата мора да имплементира заштита од дупликати. RFC 9110 ја објаснува идемпотентноста на HTTP методите.
Користете стабилен ID на настанот од давателот кога е документиран и достапен. Во спротивно, дефинирајте отпечаток од ID-то на доделувањето и релевантните полиња на настанот, како временскиот печат, изворниот статус и локацијата. Документирајте ја можноста за судири или изменети описи на настаните. Зачувајте го необработеното набљудување дури и кога не создава друга акција во OMS.
Заштитете го секој несакан ефект одделно. На пример, запишувањето на статусот во OMS и известувањето по е-пошта имаат потреба од сопствени контроли за дедупликација. Користете трансакциски outbox или еквивалентен траен работен запис за падот на процесот да не остави прифатен настан без закажано ажурирање.
2. Чувајте ги одделно времето на настанот и времето на прием
Времето кога се случил настанот и времето кога вашата интеграција го примила одговараат на различни прашања. Зачувајте ги двете, заедно со оригиналната репрезентација на временскиот печат и секое доставено отстапување на временската зона. Не доделувајте тивко временска зона на магацинот на настан чија временска зона е непозната.
Задоцнетото скенирање во транзит обично треба да ја збогати историјата без да ја замени поновата состојба „испорачано“. Сепак, само временските ознаки не се доволни: давателот може да издаде исправка, а настаните може да имаат нецелосни временски информации. Користете документирани полиња за секвенца или ревизија кога се достапни, заедно со експлицитна политика за исправки.
3. Нормализирајте ги статусите без да ги избришете деталите од изворот
Создадете мал интерен речник што го разбира OMS, како што се: чекање прифаќање од превозникот, во транзит, излезено за испорака, испорачано, исклучок и враќање. Мапирајте ги документираните статуси на давателот во него. Ова се предложени интерни категории, а не универзални дефиниции на превозниците.
Зачувајте го оригиналниот код на статусот, описот, локацијата на настанот, референцата на записот на давателот и верзијата на правилото за мапирање. Немапирана вредност треба да создаде услов за преглед наместо стандардно да се постави како испорачано или неуспешно. Создавањето етикета не треба да се третира како доказ за физичко прифаќање од превозникот, освен ако изворниот настан експлицитно го поддржува тоа толкување.
4. Користете правила за премин, а не едноставно нумеричко рангирање
Состојбите на пратката не се движат секогаш по права линија. По исклучок може да следи нормален транзит, а обидот за испорака не е испорака. Движењето за враќање може да започне по претходен настан за испорака.
- Дозволете исклучокот да се расчисти кога последователните докази покажуваат продолжено движење.
- Спречете обично историско скенирање тивко да ја замени состојбата „испорачано“.
- Дозволете документирана исправка преку контролирана патека за ревизија.
- Следете го движењето за враќање одделно од завршувањето на излезната испорака кога OMS го поддржува тоа.
- Насочете ги двосмислените или противречните докази во оперативна редица.
Верзионирајте ги овие правила. Кога ќе се промени мапирањето, одлучете дали се применува само на новите настани или историските записи бараат контролирана повторна пресметка.
Пресметајте го статусот на нарачката врз основа на потребните обврски за исполнување
Статусот на пакетот и статусот на нарачката треба да бидат одделни полиња. Пакет означен како испорачан обезбедува доказ за тој пакет; завршувањето на нарачката зависи од преостанатите потребни количини и вашата деловна политика.
Корисно стандардно правило е нарачката да се означи како целосно испорачана само кога сите количини за кои е потребна испорака имаат валиден доказ за испорака на ниво на пакет и не остануваат неразрешени потребни распределби. Исклучете ги откажаните количини според правилата за откажување на OMS. Дигиталните артикли, нарачките за лично преземање и другите обврски без испорака обработувајте ги преку нивни сопствени услови за завршување.
Заменските пратки бараат експлицитни релации. Ако изгубениот пакет е заменет, одлучете дали замената ја надминува првичната обврска за испорака. Во спротивно, првичниот пакет може неодредено да го блокира завршувањето или двата пакети може да се бројат кон исполнувањето. Забележете ја одлуката наместо да ја изведувате само од статусот на следење.
Чувајте го завршувањето на испораката одделно од финансиското затворање, подобноста за рефундација и решавањето спорови. Настанот за испорака од превозникот не треба автоматски да одобри рефундација или да го реши барањето на клиентот.
Опоравувајте се од неуспеси без губење на ревизорската трага
Повторувајте ги привремените неуспеси со ограничено зголемување на интервалите и со сите документирани упатства за повторни обиди. Одделете ги привремените дефекти на поврзувањето од невалидни идентификатори, истечени акредитиви, грешки со дозволи и некомпатибилности на шемата. За последните се потребни корективни дејства, а не бесконечни повторни обиди.
Одржувајте редица за неуспешна работа што ги содржи засегнатиот закупец, пакетот, референцата на настанот, обидот за операција, класификацијата на грешката и следното дејство. Евидентирајте доволно контекст за истрага без непотребно копирање податоци за клиентите или акредитиви во дневниците.
Извршувајте усогласување покрај нормалната патека за ажурирање. Прегледајте ги активните пратки со застарени информации за следење, прифатените настани чии запишувања во OMS не успеале, несовпаѓачките набљудувања и разликите меѓу пресметаната состојба на интеграцијата и OMS. Изберете ја зачестеноста на прегледот врз основа на обврските за испорака, ограничувањата на API-то и оперативниот ризик, наместо да применувате произволен универзален распоред.
Доделете сопственост: инженерството се справува со неуспесите при внесување и запишување; операциите за исполнување ги решаваат недостасувачките релации на пакетите; корисничката поддршка ги прегледува исклучоците што бараат комуникација со клиентите. Редица без одговорен сопственик е само место за складирање.
Тестирајте ги мапирањето и деловните правила пред пуштањето
Користете контролирани фикстури и ограничено пуштање во продукција. Тестирајте ги следните случаи и во однос на историјата на настаните и на добиениот запис во OMS:
- Нарачка со еден пакет нормално напредува до испорака.
- Поделена нарачка има еден испорачан пакет и еден што сè уште се движи.
- Истиот настан се прима повеќепати без дуплирани несакани ефекти.
- Постаро скенирање во транзит пристигнува по испораката.
- Непознат превозник или статус влегува во редицата за преглед.
- Етикетата е заменета без создавање друга обврска за исполнување.
- Заменската пратка го надминува првичниот пакет според одобрено правило.
- OMS не е достапен откако настанот е прифатен.
- Процесот се рестартира меѓу запишувањето во OMS и неговата потврда.
- Истиот прикажан број на нарачка постои во две продавници без совпаѓање меѓу закупци.
Пуштете го системот кога секој прифатен настан има следлив исход на обработката, двосмислените совпаѓања не можат автоматски да ги ажурираат нарачките и операторите можат безбедно повторно да ја извршат неуспешната работа. Ова се покорисни критериуми за прифаќање од едноставното покажување дека API-барањето успева.
ЧПП
Можам ли директно да ги поврзам броевите за следење со нарачките?
За строго еднопакетен процес, директната релација можеби првично е доволна. Сепак, користете интерен идентитет на пратката меѓу нарачката и доделувањето за следење. Тој обезбедува патека за миграција за поделени пратки, повторно означување и замени без промена на значењето на записот на нарачката.
Дали интеграцијата треба да користи webhook-и или периодично преземање?
Користете го механизмот за доставување што го поддржува давателот и што е компатибилен со вашата инфраструктура. Webhook-ите можат да го намалат повторливото преземање, додека периодичното преземање може да поддржи процеси засновани на преземање и усогласување кога е достапно. Ниту еден пристап не ја отстранува потребата од трајно складирање, обработка на дупликати и опоравување.
Што треба да се случи кога настанот за следење нема соодветна нарачка?
Зачувајте го во редица за несоодветни настани и истражете го записот за регистрација, контекстот на закупецот, идентитетот на превозникот и времето на создавање на пратката. Не создавајте нарачка или автоматски не прикачувајте го настанот кон веројатен клиент. Повторно обработете го откако ќе се исправи мапирањето.
Дали известувањата за испорака треба да доаѓаат од OMS или од системот за следење?
Изберете еден сопственик за секој тип известување и активирач. Ако два системи можат да испратат иста порака, оневозможете ја едната патека или споделете траен регистар на известувања. Исто така одлучете дали пораката се однесува на еден пакет или на целата нарачка, особено кај поделено исполнување.
Дали статусот „исклучок“ значи дека нарачката не успеала?
Не. Исклучокот е набљудување што бара толкување, а не нужно траен исход. Зачувајте ја причината, следете ги последователните настани и користете ја политиката за ескалација за да одлучите кога операциите треба да интервенираат.
Извори
- 17TRACK Tracking API — официјална референца за производот и почетна точка за интеграцијата со API.
- 17TRACK API documentation — референца за имплементација на договорот специфичен за давателот; проверете ги применливите интерфејси и барањата за сметката пред пуштањето.
- RFC 9110, Section 9.2.2: Idempotent Methods — HTTP семантика што ја поддржува разликата меѓу идемпотентноста на методите и заштитата од дупликати на ниво на апликација.


