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

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

17TRACK

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

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

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

Што значи пораката за дупликатна регистрација

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

  • Бројот за следење претходно бил успешно регистриран, а апликацијата повторно го испраќа истото барање за создавање.
  • Двајца работници го испратиле истиот број за следење пред кој било од нив да ја ажурира локалната база на податоци.
  • Настанал прекин на времето откако оддалечената услуга го прифатила барањето, па клиентот повторно испратил барање без да знае дека првиот обид бил успешен.
  • Локалниот систем зачувал различно форматирање за истиот број, како почетни или завршни празни места, неконзистентна големина на буквите или интерпункциски знаци.
  • Бројот за следење бил доделен на погрешен превозник, сметка, нарачка од marketplace или запис за пратка.
  • Бројот постои во оддалечената сметка, но е поврзан со запис што локалниот систем не успеал да го зачува.

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

Прва проверка: дали бројот за следење навистина е ист?

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

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

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

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

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

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

1. Снимете го целосниот контекст на барањето и одговорот

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

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

2. Проверете ја локалната состојба пред да испратите ново барање за создавање

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

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

3. Пребарајте го оддалечениот запис кога API го поддржува тоа

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

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

4. Одлучете дали операцијата е повторување, ажурирање или конфликт

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

Забележана состојбаПрепорачано дејство
Локалниот и оддалечениот запис се совпаѓаатОзначете го барањето како успешно или веќе обработено. Повторно употребете го постојниот запис.
Нема локален запис, но оддалечениот запис се совпаѓа со праткатаУсогласете ја локалната база од оддалечениот резултат, а потоа продолжете со нормалните ажурирања на следењето.
Оддалечениот запис има различен превозник или идентитет на праткаНе препишувајте автоматски. Потврдете ги изворните податоци и ескалирајте го конфликтот.
Барањето сè уште е во тек, а API нуди операција за ажурирањеКористете ја документираната патека за ажурирање, а не второ барање за создавање.
Одговорот е нејасен и нема достапно пребарувањеОставете ја задачата во статус на усогласување и побарајте поддршка од давателот или за сметката пред повторни обиди за создавање.

Спречување дупликатни API-регистрации

Направете ја операцијата за создавање идемпотентна во вашата апликација

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

Користете ограничување за единственост во базата на податоци како последна заштита. Самите проверки на ниво на апликација се ранливи на условна трка: работникот A проверува запис, работникот B проверува запис, а потоа и двајцата внесуваат. Уникатно ограничување или еквивалентен атомски внес спречува двајцата работници да создадат локални записи. Работникот што ќе изгуби треба да го прочита постојниот ред и да продолжи со усогласувањето наместо да пријави фатална грешка.

Одделете го испраќањето од синхронизацијата на статусот

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

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

Контролирајте ја истовременоста

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

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

Мониторинг и оперативни проверки

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

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

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

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

Практичен образец за имплементација

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

key = buildShipmentKey(accountId, carrier, normalizeForComparison(trackingNumber))

local = findByUniqueKey(key)
if local and local.remoteStatus == "registered":
    return markAlreadyProcessed(local)

lock(key)
try:
    local = findByUniqueKey(key)
    if local and local.remoteStatus == "registered":
        return markAlreadyProcessed(local)

    result = queryRemoteRecord(carrier, trackingNumber)
    if result.matchesIntendedShipment:
        return reconcileLocalRecord(key, result)

    if result.notFound:
        created = registerTracking(carrier, trackingNumber)
        return saveRemoteResult(key, created)

    return createManualReview(key, result)
finally:
    unlock(key)

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

Кога да го контактирате давателот на API

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

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

ЧПП

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

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

Може ли истиот број за следење да се користи за повеќе од една нарачка?

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

Што ако мојата база вели дека регистрацијата не успеала, но API вели дека е веќе регистрирана?

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

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

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

Како можам да спречам двајца работници да ја регистрираат истата пратка?

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

Извори