Skip to main content
ДомаБлогВодичиРаботен тек на API-от за следење на пратки: од регистрирање на пратка до преземање на деталите за следење

Работен тек на API-от за следење на пратки: од регистрирање на пратка до преземање на деталите за следење

17TRACK

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

Работен тек на API за следење пратки од регистрација на пратка до преземање

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

Разберете што прави регистрацијата — а што не прави

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

Во вашата апликација одвојте ги следните три исходи:

  • Барањето е примено: API-то вратило одговор на вашето HTTP-барање.
  • Регистрацијата е прифатена: Услугата го прифати поединечниот запис за следење за обработка.
  • Информациите за следење се достапни: Услугата има информации за пратката што вашата апликација може да ги преземе или прими.

Овие исходи не треба да се сведат на едно знаменце „успех“. Прифатен број за следење можеби сè уште нема настани од превозникот. Исто така, успешен HTTP-одговор за пакетно барање не потврдува дека секоја ставка во пакетот е прифатена; проверете ја структурата на резултатот на ниво на апликација дефинирана од провајдерот.

1. Подгответе го идентитетот на пратката и конфигурацијата на API

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

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

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

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

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

2. Регистрирајте ја пратката и зачувајте го резултатот на ниво на ставка

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

Следниот псевдокод ја прикажува низата на апликацијата. Имињата на функциите се илустративни; тие не се API-крајни точки или SDK-методи.

shipment = load_internal_shipment(shipment_id)
validate_tracking_input(shipment)

result = tracking_adapter.register(shipment)

if result.item_accepted:
    save_registration_result(shipment_id, result)
elif result.outcome_unknown:
    schedule_registration_reconciliation(shipment_id)
else:
    save_registration_error(shipment_id, result)
    route_for_retry_or_correction(result)

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

Обработувајте ги пакетните испраќања поединечно

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

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

Третирајте ги истекувањата на времето како непознат исход

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

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

3. Овозможете да пристигнат првите информации за следење

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

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

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

  1. Потврдете дека поединечната регистрација е прифатена.
  2. Споредете го испратениот број за следење со записот за исполнување.
  3. Проверете го мапирањето на превозникот и сите документирани дополнителни барања за пребарување.
  4. Проверете ја сопствената страница за следење на превозникот за истата пратка.
  5. Ако превозникот има настани, а вашата интеграција нема, проверете ги одговорите при преземање и контактирајте го API-провајдерот со дијагностички информации од кои се отстранети чувствителните податоци.

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

4. Преземајте ги деталите за следење и правилно толкувајте ги

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

Вашата апликација треба да разликува три слоја информации:

  • Резиме на пратката: Вкупната состојба што се користи во контролните табли, страниците на нарачките и оперативните филтри.
  • Историја на настани: Поединечните набљудувања, вклучувајќи описи на настаните, временски ознаки и локации кога се доставени.
  • Метаподатоци за преземањето: Кога апликацијата ги примила или презела информациите и дали барањето завршило успешно.

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

Одвојте го времето на настанот од времето на преземањето

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

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

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

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

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

5. Одржувајте ги записите ажурирани преку polling или webhooks

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

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

Ако користите webhooks, проверувајте ги дојдовните барања со документираниот механизам за верификација на провајдерот. Зачувајте ги или трајно ставете ги во редица прифатените пораки пред да потврдите прием според webhook-договорот, а потоа обработувајте ги настаните асинхроно.

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

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

6. Претворете ги информациите за следење во безбедни деловни дејства

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

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

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

Примена на работниот тек со интеграција на 17TRACK

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

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

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

Проверки пред лансирање што спречуваат скапи грешки

  • Прифатен, но празен запис: Интерфејсот покажува дека информациите за следење се во исчекување, а не дека пакетот се движи.
  • Мешан резултат од пакет: Секоја пратка добива сопствен зачуван исход.
  • Истекување на времето по испраќањето: Работникот го усогласува неизвесниот резултат наместо да претпостави неуспех.
  • Повторен настан: Временската линија на пратката и известувањето до клиентот остануваат без дупликати.
  • Постар настан примен подоцна: Настанот се зачувува без слепо заменување на поново резиме.
  • Недостапна надворешна услуга: Страницата за клиентот може да го прикаже последниот зачуван резултат со соодветна ознака за свежина.
  • Неточно мапирање на превозникот: Записот може да се коригира преку документирана постапка за обновување.
  • Поделена нарачка: Секој пакет ја задржува сопствената состојба на следење и историја на настани.
  • Изложување акредитиви или payload: Логовите содржат дијагностички референци без откривање тајни или непотребни лични информации.

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

ЧПП

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

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

Зошто деталите за следење се празни по успешна регистрација?

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

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

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

Дали треба да користам polling или webhooks?

Користете го механизмот што одговара на документираниот API-договор и вашите оперативни барања. Polling бара контролиран распоред на барања. Webhooks бараат безбеден, траен приемник и обработка безбедна од дупликати. Кога се поддржани, ажурирањата преку webhooks со насочено усогласување можат да обезбедат практична патека за обновување.

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

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

Извори

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