Контролен списък с документация за USPS API за интеграция на 17TRACK за обработка на поръчки и връщания

Надеждна интеграция на USPS с 17TRACK трябва да бъде планирана като два свързани, но отделни работни потока: документацията на USPS определя данните и услугите, насочени към превозвача, докато 17TRACK може да предостави по-широк слой за проследяване на пратки между различни превозвачи. За изпълнението и връщанията екипът по внедряването трябва да провери удостоверяването, идентификаторите на пратките, съпоставянето на събитията, отговорностите за тарифите и етикетите, поведението при периодично извличане или известия, обработката на грешки и границите между изходящата доставка и обратната логистика, преди да напише продукционен код.

Този контролен списък е предназначен за разработчици, екипи по електронна търговия и собственици на решения, които свързват данни за пратки, свързани с USPS, със система за управление на поръчки, складов работен процес, проследяване за клиенти или процес за връщания. Той не предполага, че всяка възможност на USPS API е достъпна чрез 17TRACK или че API за проследяване сам по себе си създава етикети, закупува пощенски услуги или управлява физически връщания.

1. Първо определете границите на интеграцията

Започнете, като документирате какво се очаква да прави всяка система. Документацията на USPS описва услугите на USPS и интерфейсите, достъпни за одобрен интегратор. Документацията на 17TRACK Tracking API е от значение, когато приложението се нуждае от неутрален спрямо превозвача работен процес за проследяване или единен интерфейс за събитията на пратките. Страницата на продукта 17RETURNS е от значение, когато проектът включва и управление на връщанията в електронната търговия. Това са свързани случаи на употреба, но не са взаимозаменяеми.

• USPS: потвърдете кои функции, насочени към превозвача, са необходими, като проследяване, услуги за адреси, ценообразуване, информация за услуги или други документирани API.
• 17TRACK Tracking API: проверете как номерата за проследяване на USPS се изпращат, заявяват, актуализират и представят в нормализирания модел на събитията на приложението.
• Платформа за изпълнение: определете системата, отговорна за разпределянето на наличностите, освобождаването на поръчките, създаването на етикети, закупуването на пощенски услуги, складовото потвърждение и създаването на пратки.
• Работен процес за връщания: определете кой одобрява връщането, генерира инструкции или етикети за връщане, записва върнатия пакет и взема решение за възстановяване на сумата или замяна.

Следователно първото архитектурно решение не е „кой endpoint трябва да извикаме?“, а „коя система притежава всяко бизнес действие?“. API за проследяване на превозвач може да подобри видимостта, без да бъде системата за запис на данните за изпълнението или връщанията.

2. Проверете актуалната документация за разработчици на USPS

Използвайте информацията за USPS Web Tools и API като отправна точка, след което следвайте актуалната документация за разработчици и специфичните за продуктите препратки, посочени от USPS. Избягвайте копирането на endpoint, метод за удостоверяване, име на поле или известие за прекратяване от стар пример с код, без да проверите текущия му статус.

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

• Точният продукт или продукти на USPS API, които са необходими.
• Текущият базов URL и подробностите за средите за тестване и продукция.
• Процесът на регистрация, идентификационните данни на приложението и разрешеното използване на тези идентификационни данни.
• Потокът за удостоверяване, срокът на валидност на токените, обхватите и изискванията за ротация на идентификационните данни, ако са документирани за избрания API.
• Задължителните заглавки, типовете съдържание, форматите на заявките, форматите на отговорите и идентификаторите на версиите.
• Поддържаните операции и всички ограничения, основани на акаунт, услуга, география или тип данни.
• Ограниченията на честотата, насоките за изчакване, известията за поддръжка и документираните отговори при грешки.
• Условията, регулиращи съхранението, показването, повторното използване и разпространението на данните от отговорите на USPS.

Ако дадено изискване не е посочено в официалната документация, отбележете го за директно потвърждение с USPS или съответния представител на акаунта. Не приемайте, че стар пример за USPS Web Tools представлява текущия API, и не приемайте, че функция, описана в един продукт на USPS, е налична в друг.

3. Създайте контролен списък за удостоверяване и сигурност

Удостоверяването трябва да се тества отделно от бизнес логиката. Екипът трябва да може да отмени и замени идентификационните данни, без да променя кода на приложението или да прекъсва несвързани функции за проследяване.

1. Съхранявайте клиентските тайни, API ключовете, токените и сертификатите в управлявано хранилище за тайни, а не в изходния код или клиентско приложение.
2. Потвърдете дали избраният USPS API използва метода за удостоверяване, описан в актуалната документация. Реализирайте документирания поток точно, включително заявките за токени, обхватите, изтичането и поведението при обновяване или повторно удостоверяване.
3. Използвайте отделни идентификационни данни или среди, когато USPS го позволява, така че тестовият трафик да не се смесва с продукционния.
4. Ограничете достъпа до адресни данни на клиенти, данни за пратки и информация за връщания според ролите, които се нуждаят от тях.
5. Маскирайте идентификационните данни и ненужната лична информация в журналите на приложението.
6. Записвайте неуспешните удостоверявания с идентификатор за корелация, но избягвайте записването на тайни или пълни чувствителни полезни товари.
7. Тествайте поведението при изтичане на токен, отмяна на идентификационни данни, повторно изпращане на заявка или временно недостъпен сервиз за удостоверяване.

При интеграция с 17TRACK поддържайте концептуално отделни идентификационните данни за превозвача и тези за 17TRACK, освен ако съответната документация изрично не определя друга схема. Не трябва да се приема, че заявка за проследяване, маршрутизирана през 17TRACK, предоставя достъп до пощенски услуги, акаунт или услуги за етикети на USPS.

4. Потвърдете идентификаторите и собствеността върху данните

Идентичността на пратката често е източник на дублирани поръчки и прекъснати връзки към връщанията. Създайте карта на полетата, преди да свържете системите. Най-малкото разграничете следните стойности:

Бизнес стойност	Въпрос за внедряването	Точка за проверка
ID на поръчката	Кой запис в търговската или OMS система притежава поръчката?	Една поръчка може да съдържа множество пакети.
ID на изпълнението	Кое действие на склада или 3PL е освободило пратката?	Не го заменяйте с номер за проследяване.
Номер за проследяване	Кой идентификатор се изпраща към USPS или 17TRACK?	Проверете формата, назначаването на превозвач и обработката на дубликати.
ID на връщането	Кое разрешение или дело за връщане притежава пратката?	Пратката за връщане не трябва да презаписва изходящата пратка.
ID и времеви печат на събитието	Как се обработват повтарящи се или закъснели събития?	Определете правила за подреждане, часова зона и идемпотентност.

По възможност запазвайте оригиналното събитие на превозвача и нормализирания вътрешен статус. Нормализиран статус като „в транзит“ е полезен за онлайн магазините, но оперативните екипи може да се нуждаят от оригиналния текст на събитието от USPS, местоположението и часа на събитието за разследване.

5. Проектирайте приемането на проследяване и съпоставянето на статуси

Преди да свържете реален трафик, избройте състоянията от жизнения цикъл, от които бизнесът действително се нуждае. Типичните състояния могат да включват етикетът е създаден, приета, в транзит, подготвена за доставка, доставена, изключение при доставката и връщане към подателя. Точният речник на събитията на USPS и събитията, предоставяни чрез 17TRACK, трябва да бъдат проверени в съответната документация и тестовите отговори; не създавайте съпоставяния само по имената на статусите.

За всяко събитие определете:

• Изходната система и оригиналния код или описание на събитието.
• Нормализирания вътрешен статус.
• Дали събитието е видимо за клиента, само за операциите или и за двете.
• Дали може да придвижи поръчката напред, да спре SLA, да задейства известие или да отвори случай за изключение.
• Дали по-късно събитие може да го коригира или замени.
• Как се обработват дублирани и неправилно подредени събития.

Решете също как новите номера за проследяване ще влизат в системата. Пратка може да бъде създадена, преди да се появи първото сканиране от превозвача. Приложението трябва да различава „номерът за проследяване е регистриран“ от „превозвачът е приел пакета“, вместо да представя несканирана пратка като вече движеща се в мрежата.

6. Решете между периодично извличане и известия

Внедряването трябва да документира как се получава новата информация за проследяване. Ако избраният продукт на USPS или 17TRACK поддържа механизъм за известия, проверете в официалната документация неговия модел на абонамент, формат на доставяне, поведение при повторен опит, метод за подписване или проверка и ограниченията. Ако е необходимо периодично извличане, определете интервала, условията за спиране, стратегията за обратно изчакване и обработката на пратки без ново събитие.

Не извличайте данни агресивно само защото клиент обновява страницата за проследяване. Използвайте сървърно хранилище за събития или кеш, когато е подходящо, прилагайте експоненциално обратно изчакване при временни грешки и направете приемането идемпотентно. Неуспешна заявка не трябва да създава втора пратка, второ връщане или дублирано известие към клиента.

Оперативните известия трябва да обхващат неуспешни удостоверявания, продължителни отговори за ограничаване на честотата, неправилно форматирани отговори от превозвача, неуспешна обработка на събития и увеличаване на пратките, които остават неразрешени. Наблюдението трябва да показва както състоянието на API, така и състоянието на бизнеса: успешният HTTP отговор не означава непременно, че пратката е свързана с правилната поръчка.

7. Разделете изпълнението от връщанията

Изходящото изпълнение и връщанията споделят данни за пратките, но имат различни бизнес правила. Изходящото изпълнение обикновено започва с поръчка и завършва с доставка или изключение. Връщането започва с решение на клиента или търговеца, може да изисква разрешение и завършва с проверка на получаването, възстановяване на сумата, замяна или друго решение.

При интеграция за връщания документирайте следните решения, преди да добавите проследяване на превозвача:

• Кои причини за връщане се приемат и кой ги одобрява?
• Етикетът за връщане генерира ли се от платформата за доставки на търговеца, работен процес, свързан с USPS, система на трета страна за връщания или друг доставчик?
• Как номерът за проследяване на връщането се свързва с оригиналната поръчка, без да заменя номера за проследяване на изходящата пратка?
• Кое събитие се счита за „връщането е в транзит“, „връщането е доставено“ или „получено за проверка“?
• Може ли връщане да бъде доставено в склад, но да остане в изчакване, докато артикулът бъде проверен?
• Какво се случва, когато клиент изпрати неоторизиран пакет или използва друг превозвач?

17RETURNS може да е подходящ, когато проектът се нуждае от специализиран работен процес за управление на връщанията, докато API на 17TRACK е подходящ за видимостта на пратките. Потвърдете актуалната продуктова документация, преди да възложите на който и да е продукт функция като генериране на етикети, разрешаване на възстановяване на суми, приемане в склад или управление на акаунт на превозвач.

8. Тествайте интеграцията с реалистични сценарии

Тестът по щастливия път за една доставена пратка не е достатъчен. Създайте тестова матрица, която включва:

1. Валиден номер за проследяване на USPS без скорошно събитие.
2. Пратка с множество събития, получени в неправилен ред.
3. Повтарящи се събития за доставка или изключение.
4. Невалиден, неправилно изписан или неподдържан идентификатор.
5. Пакет, върнат към подателя.
6. Изходяща пратка и пратка за връщане, свързани с една и съща поръчка.
7. Изтичане на времето за API, отговор за ограничаване на честотата, неуспешно удостоверяване и неправилно форматиран отговор.
8. Пратка, чието назначение на превозвач първоначално е неизвестно или изисква потвърждение.
9. Страница, видима за клиента, която получава ново събитие, докато оперативен потребител редактира поръчката.

За всеки сценарий запишете очаквания резултат в базата данни, съобщението към клиента, оперативното действие, поведението при повторен опит и одитната следа. Тествайте със синтетични или разрешени данни и потвърдете, че личните адреси и данните за контакт не се разкриват в журналите или публичните страници за проследяване извън одобрената бизнес цел.

9. Проверка на готовността за продукция

Преди стартирането отговорникът за действието трябва да може да отговори на пет практически въпроса: Коя система създава пратката? Коя система притежава номера за проследяване? Коя система изпраща известията към клиентите? Коя система управлява случая за връщане? Кой екип разследва липсващо или противоречиво събитие?

Завършете проверката едва след като прегледате актуалната документация на USPS, избраната документация за 17TRACK API и всички специфични за продукта условия или оперативни насоки. Поддържайте версиониран запис на препратките към endpoint-и, съпоставянията на полета, доказателствата от тестове, собствениците на идентификационните данни, контактите за ескалация и предположенията, които изискват директно потвърждение. Преглеждайте записа отново, когато се промени версия на API, работен процес на превозвача, складов процес или политика за връщания.

Често задавани въпроси

Може ли 17TRACK да замени USPS API за всяка функция по изпълнението?

Не трябва да се прави такова предположение. 17TRACK може да бъде оценен като слой за проследяване, но функциите, насочени към USPS, като ценообразуване, услуги за адреси, пощенски услуги или други операции на превозвача, трябва да бъдат потвърдени спрямо съответната продуктова документация и изискванията за акаунта. Видимостта на проследяването не е същото като закупуването на етикет или изпълнението на поръчка.

Необходими ли са ми интеграции и с USPS, и с 17TRACK?

Не винаги. Ако приложението се нуждае само от тясно дефинирана функция на USPS, директната интеграция с USPS може да е подходяща. Ако се нуждае от нормализирано проследяване между множество превозвачи или от неутрален спрямо превозвача работен процес за проследяване, 17TRACK може да е от значение. Решението трябва да следва необходимите възможности, модела на собственост и потока на данните, а не само номера за проследяване.

Трябва ли номерът за проследяване на връщането да замени номера за проследяване на изходящата пратка?

Не. Съхранявайте връщането като отделна пратка или движение за връщане, свързано с оригиналната поръчка и записа за изпълнението. Така се запазва историята на изходящата доставка и връщането може да има собствени събития, изключения и оперативен резултат.

Как трябва да се обработват липсващите събития за проследяване?

Определете документирана политика за повторни опити и ескалация. Липсващо събитие може да отразява нормалното време за обработка от превозвача, невалиден идентификатор, грешка при приемането или забавяне от страна на превозвача. Избягвайте да обозначавате пратка като изгубена само защото един опит за периодично извличане не е дал ново събитие.

Къде трябва да се съхраняват идентификационните данни за USPS?

Използвайте управлявано сървърно хранилище за тайни и ограничете достъпа според ролята. Никога не поставяйте идентификационни данни в JavaScript на онлайн магазина, код на мобилен клиент, публични хранилища или журнали. Потвърдете актуалните изисквания на USPS за удостоверяване и управление на идентификационни данни преди внедряване в продукция.

Източници

• USPS Web Tools and APIs — официална отправна точка на USPS за информация относно бизнес API.
• 17TRACK Tracking API Documentation — официална документация за интеграцията с 17TRACK API.
• 17RETURNS — официална информация за продукта за случаи на употреба, свързани с управлението на връщания.
• 17TRACK API — официален преглед на продукта за сценарии с API за проследяване.