Како да интегрирате API за следење на пратки во вашата е-продавница
За да интегрирате API за следење на пратки во вашата е-продавница, поврзете го системот за нарачки со давателот на услугата за следење, испраќајте ги податоците за пратката и превозникот преку безбедно барање од страна на серверот, зачувувајте ги нормализираните настани за следење и прикажувајте го добиениот статус во интерфејсите за корисници и поддршка. Сигурната имплементација е повеќе од додавање поле за број на следење: таа мора да се справи со изборот на превозник, ажурирањата на статусот, исклучоците при испорака, повторните обиди, приватноста и начинот на кој клиентите навистина ги користат информациите по купувањето.
Овој водич објаснува практичен пристап кон интеграцијата за сопственици на продавници, развивачи и оперативни тимови. Како референтна точка ја користи официјалната документација за Tracking API на 17TRACK, но истите принципи на планирање важат и при оценување на друг давател на услуги со поддршка за повеќе превозници.
Одлучете што треба да постигне интеграцијата
Започнете со деловниот резултат, а не со API-крајната точка. Повеќето продавници сакаат да го намалат бројот на прашања „Каде е мојата нарачка?“, да им овозможат на купувачите јасен преглед на испораката и да им помогнат на оперативните тимови да ги идентификуваат доцните пратки пред клиентот да се пожали. Овие цели бараат различни податоци и работни текови.
- Видливост за клиентите: прикажете тековен статус на пратката, проценети информации за испораката кога се достапни, детали за превозникот и најновиот значаен настан.
- Оперативна видливост: овозможете му на персоналот да ги пронаоѓа доцните, заглавените, вратените или пратките со исклучоци кај различни превозници.
- Автоматизирана комуникација: активирајте одобрени известувања по е-пошта, SMS или на друг начин кога пратката ќе достигне дефинирана состојба.
- Конзистентност на податоците: претворете ги различните ознаки на настани од превозниците во помал број статуси што вашата продавница може сигурно да ги користи.
Дефинирајте ги овие резултати пред да изберете метод на имплементација. API за следење може да обезбеди податоци за пратката, но не одлучува автоматски кои настани заслужуваат известување до клиентот или како вашата продавница треба да се справи со проблем со адресата.
Изберете ја соодветната архитектура за интеграција
Типичната архитектура има четири слоја: платформата за трговија, услугата за интеграција, давателот на услугата за следење и искуството наменето за клиентите. Услугата за интеграција може да биде бекенд-апликација, систем за управување со нарачки или serverless работен тек. Одржувањето на оваа логика на серверот обично е побезбедно отколку поставувањето на API-пристапните податоци во кодот на прелистувачот.
Основниот тек изгледа вака:
- Платената нарачка се исполнува и добива број за следење и превозник.
- Вашиот бекенд ги испраќа деталите за пратката до давателот на услугата за следење.
- Давателот враќа идентификатор за следење или податоци за следење според дизајнот на својот API.
- Вашиот систем ја зачувува референцата од давателот и ги мапира настаните на пратката во интерни статуси.
- Закажан процес за ажурирање или поддржано известување за настан го освежува статусот на пратката.
- Вашата продавница, страницата за нарачки, алатките за поддршка и услугата за известувања ги читаат податоците од вашата нормализирана база на податоци.
Не дозволувајте секое прикажување на страница да повикува кон превозникот или API-то за следење. Таквиот дизајн може да создаде бавно корисничко искуство, дуплирани барања, проблеми со ограничувањата на стапката и неконзистентни резултати. Зачувајте ја последната прифатена состојба на следење во вашата база на податоци и освежувајте ја преку контролирани задачи во заднина или преку поддржаниот механизам за ажурирање на давателот.
Потврдете ја документацијата на давателот пред кодирањето
Пред имплементацијата, прегледајте ја официјалната API-документација на давателот за автентикација, формати на барања, полиња во одговорите, поддржани превозници, однесување при грешки, механизми за ажурирање и барања за сметката. 17TRACK обезбедува посебна страница за производот Tracking API и документација за развивачи. Сметајте ги тие страници за авторитетен извор за тековното однесување на API-то, наместо да се потпирате на примери преземени од форуми или стари упатства за интеграција.
Од документацијата направете кратка листа со барања:
- Како се издаваат, чуваат, ротираат и отповикуваат API-пристапните податоци?
- Дали барањето бара код на превозник, или услугата може да го идентификува превозникот преку бројот за следење?
- Кои полиња во одговорот ја идентификуваат пратката, статусот, локацијата, временските ознаки и пораката за исклучок?
- Како се испорачуваат асинхроните ажурирања, ако сметката ги поддржува?
- Кои се документираните ограничувања на барањата, правилата за наплата, очекувањата за времето на истекување и кодовите за грешки?
- Како треба да се постапува со дуплирани броеви за следење, неважечки броеви, непознати превозници и испорачани пратки?
Не заклучувајте дека одредена функција постои само врз основа на името на производот. На пример, „во реално време“ може да опишува позиционирање на производот, а не гаранција дека секој настан од превозникот ќе се појави веднаш. Вашата имплементација треба да објасни дека скенирањата од превозникот може да доцнат и дека API не може да создаде скенирање што превозникот не го пријавил.
Подгответе ги податоците за нарачката и пратката
Најсоодветниот момент за создавање на следењето обично е исполнувањето на пратката, а не создавањето на нарачката. Нарачката може да биде платена, но сè уште да не е спакувана, а бројот за следење може да биде генериран пред превозникот да ја прифати пратката. Одлучете кој настан во вашиот работен тек за исполнување треба да го создаде записот за следење.
Најмалку, вашиот интерен запис за пратката треба да ги разликува следните вредности:
- Интерен ID на нарачката и ID на исполнувањето
- Број за следење
- Име на превозникот или код на превозникот
- Земја или регион на дестинација, кога е оперативно неопходно
- ID за следење од давателот или референца за претплата, ако е вратена
- Тековен нормализиран статус
- Временска ознака на последниот настан и временска ознака на последната синхронизација
- Необработен одговор од давателот или контролирана референца за ревизија
Чувајте ги податоците за нарачката и пратката одделно. Една нарачка може да содржи повеќе пакети, поделени пратки или различни превозници. Претпоставката дека една нарачка има еден број за следење често не функционира кога магацинот ги испраќа производите одделно.
Користете идемпотентен процес. Ако системот за исполнување повторно го испрати истото барање, интеграцијата треба да ја ажурира постојната пратка наместо да создава дуплирани претплати или дуплирани пораки до клиентите. Практичен клуч за идемпотентност може да ги комбинира вашиот интерен ID на исполнувањето, идентификаторот на превозникот и бројот за следење, согласно сопствените барања на давателот.
Нормализирајте ги статусите на превозниците за клиентите
Превозниците користат различни ознаки и низи на настани. Вашата продавница треба да одржува мал интерен модел на статуси, како што се Информациите се примени, Во транзит, На испорака, Испорачано, Исклучок и Вратено. Зачувајте го оригиналниот настан од превозникот за персоналот за поддршка, но користете го нормализираниот статус за логиката на продавницата.
Правилата за нормализација треба да бидат експлицитни. Настанот „етикетата е создадена“ не треба да се прикажува како доказ дека пакетот се движи. „Испорачано“ треба да се третира како настан пријавен од превозникот, а не како гаранција дека клиентот физички го пронашол пакетот. Исклучокот не треба тивко да се претвора во „во транзит“ само затоа што пратката можеби ќе продолжи подоцна.
Исто така, дефинирајте приоритет на статусите и постапување при назадување. Доцнењето на податоците од превозникот може да предизвика настаните да пристигнат по погрешен редослед. Кога е можно, споредете ги временските ознаки на настаните, запишете го необработениот настан и избегнувајте да замените понова состојба „испорачано“ со постара состојба „во транзит“. Ако временските ознаки недостасуваат или се нејасни, означете го записот за претпазливо ажурирање наместо да измислувате редослед.
Изградете го текот на барањата од страна на серверот
Вашиот бекенд треба да ги потврди влезните податоци за исполнувањето пред да повика кон давателот на услугата за следење. Проверете дали бројот за следење е присутен, отстранете ги случајните празни места, потврдете го очекуваниот формат каде што е соодветно и уверете се дека вредноста на превозникот е прифатлива. Не отфрлајте невообичаени, но валидни броеви за следење само затоа што не се совпаѓаат со тесен локален образец.
Текот на барањето независен од давателот може да се прикаже вака:
receive fulfillment event
validate order and shipment fields
check for an existing idempotency key
send the documented tracking request from the server
store the provider response and internal shipment record
queue a refresh or process the supported update event
publish only approved fields to the storefrontКористете кратки временски ограничувања, ограничени повторни обиди и експоненцијално зголемување на интервалот за привремени грешки. Не повторувајте го секое барање при секоја грешка. Неуспехот на автентикацијата, невалидното барање или неподдржаниот превозник обично бараат исправка, а не повторени повици. Евидентирајте ID за корелација, исход на барањето и категорија на грешката од давателот, но избегнувајте запишување API-клучеви, целосни адреси на клиенти или непотребни лични податоци во дневниците на апликацијата.
Чувајте го одговорот од давателот одделно од моделот наменет за клиентите. Така полесно ќе можете да го смените давателот, да исправите правило за мапирање и да ги ограничите информациите изложени преку јавна страница за нарачки.
Дизајнирајте го искуството за следење на клиентите
Страницата за следење треба брзо да одговори на три прашања: која е тековната состојба, што се случило последно и што треба да направи клиентот следно? Прикажете ја референцата на нарачката, бројот на пратката во форма што ја почитува приватноста, името на превозникот, времето на последниот настан и јасно објаснување за исклучоците.
Не прикажувајте празна временска линија како да станува збор за технички неуспех. Пред првото скенирање од превозникот, објаснете дека информациите за испораката се примени и дека движењето можеби сè уште не е видливо. За исклучок, обезбедете објаснување на разбирлив јазик само кога изворните податоци го поддржуваат. Ако превозникот пријави проблем со адресата, поврзете го корисникот со процесот за поддршка или со дејството од корисничката служба што вашата компанија навистина може да го обезбеди.
За продавници изградени на Shopify или друга платформа за трговија, проверете како платформата ги изложува настаните за исполнување, корисничките сметки, страниците за статус на нарачки и шаблоните за известувања. Официјалната документација за развивачи на Shopify вклучува ресурси за webhooks и податоци за исполнување. API-јата на платформите и документацијата со верзии може да се менуваат, затоа потврдете ја верзијата што ја користи вашата апликација пред работата за продукција.
Користете ги известувањата внимателно
Настаните на пратката се корисни активатори, но испраќањето порака за секое скенирање од превозникот може да создаде замор од известувања. Дефинирајте деловни правила, како известување при создавање на пратката, значаен напредок во транзитот, испорака во тек, испорака и избрани исклучоци. Потиснете ги дупликатите и додајте минимален интервал за повторени пораки за доцнење.
Одделете ги оперативните предупредувања од известувањата до клиентите. На тимот за поддршка можеби ќе му треба информација дека пратката не се променила неколку дена, додека клиентот можеби треба да добие порака само кога превозникот ќе пријави конкретен исклучок. Временскиот праг треба да го одразува нивото на услугата, дестинацијата, превозникот и методот на испорака, наместо универзален број без оперативна основа.
Тестирајте со реални сценарија за испорака
Успешниот одговор за еден број за следење не е доволен за продукциско пуштање. Направете тест-матрица што вклучува повеќе превозници, земји, типови пратки и состојби на настани. Тестирајте најмалку:
- Ново создадена пратка без скенирање од превозникот
- Нормална пратка во транзит
- Пратка на испорака
- Испорачана пратка
- Исклучок или настан поврзан со адресата
- Вратена пратка
- Невалиден број за следење
- Дуплиран настан на исполнување
- Одговор од давателот со доцнење или истек на времето
- Настан пристигнат по погрешен редослед
Мерете повеќе од достапноста на API-то. Проверете дали е ажурирана точната нарачка, дали клиентот гледа разбирлив јазик, дали се потиснуваат дуплираните известувања и дали персоналот за поддршка може да го идентификува оригиналниот настан од превозникот. Прво спроведете ограничено пуштање, задржете оперативна резервна опција и следете ги категориите на грешки по објавувањето.
Безбедност, приватност и одржување
Чувајте ги пристапните податоци во управувач на тајни или заштитена променлива на околината, а не во кодот на темата, мобилниот код, системот за контрола на изворниот код или барањата од прелистувачот. Ограничете го пристапот до податоците за пратките според улогата, користете HTTPS и проверете колку долго се задржуваат необработените одговори и полињата поврзани со клиентите.
Редовно прегледувајте ја документацијата на давателот и верзијата на API-то на вашата платформа за трговија. Поддршката за превозници, имињата на настаните, барањата за автентикација и однесувањето на webhook-овите на платформата може да се променат. Правилата за мапирање на статуси чувајте ги во конфигурација, документирајте ги претпоставките зад нив и овозможете повторно обработување или усогласување на пратка без испраќање нова порака до клиентот.
API-то на 17TRACK е релевантна опција за оценување кога на вашата продавница ѝ е потребна посветена интеграција за следење кај повеќе превозници. Соодветниот избор сепак зависи од превозниците што ги користите, земјите во кои испорачувате, однесувањето на ажурирањата документирано за вашата сметка, очекуваниот обем на барања и оперативните контроли што му се потребни на вашиот тим. Потврдете ги овие точки во официјалната документација и во контролирано тестирање на концептот пред да се определите за продукциски дизајн.
ЧПП
Дали следењето треба да се создаде кога се поставува нарачката?
Обично не. Создадете го или активирајте го записот за пратката кога вашиот работен тек за исполнување има превозник и број за следење. Неговото создавање при наплатата може да создаде записи за нарачки што подоцна се откажани, неисполнети или поделени.
Дали API за следење може да гарантира информации за испорака во реално време?
Не. Ниту едно API не може да гарантира дека секое скенирање од превозникот ќе биде веднаш видливо. Давателот зависи од податоците на превозникот, а системите на превозниците може да пријавуваат настани со доцнења или празнини. Прикажувајте ги временските ознаки и јазикот на статусите точно и избегнувајте ветување за точно време на освежување, освен ако релевантната документација и договорот за услугата го поддржуваат тоа ветување.
Дали прелистувачот треба директно да го повикува API-то за следење?
Во повеќето имплементации, не. Користете интеграција од страна на серверот за да останат заштитени пристапните податоци, да може одговорите да се нормализираат, повторните обиди да се контролираат и податоците наменети за клиентите да се филтрираат. Продавницата обично треба да чита одобрена верзија на пратката од вашата апликација.
Како треба продавницата да постапува со повеќе пакети во една нарачка?
Моделирајте го секое исполнување или пакет како одделна пратка, а притоа задржете го ID-то на матичната нарачка. Страницата на нарачката може да прикажува целосен преглед и одделни временски линии за секој пакет. Така се избегнува сокривање на доцниот пакет зад статусот „испорачано“ за друг пакет.
Кој е првиот продукциски показател што треба да се следи?
Следете го целосниот тек од создавањето на исполнувањето до точно ажурирање видливо за клиентот. Самото успешно API-барање не е доволно. Следете ги дуплираните записи, застарените пратки, немапираните настани, неуспешните известувања и процентот на пратки за кои е потребна рачна исправка.
