Контролна листа за документацијата на USPS API за интеграција на исполнување на нарачки и враќања со 17TRACK

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

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

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

Започнете со документирање на тоа што треба да прави секој систем. Документацијата на USPS ги опишува услугите на USPS и интерфејсите достапни за одобрен интегратор. Документацијата за Tracking API на 17TRACK е релевантна кога апликацијата има потреба од работен тек за следење независен од превозникот или од единствен интерфејс за настани на пратките. Страницата на производот 17RETURNS е релевантна кога проектот вклучува и управување со враќања во е-трговијата. Ова се поврзани случаи на употреба, но не се заменливи.

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

Затоа, првата архитектонска одлука не е „кој краен пункт треба да го повикаме?“, туку „кој систем ја поседува секоја деловна активност?“. API за следење на превозник може да ја подобри видливоста без да биде главен систем за исполнување или враќања.

2. Проверете ја актуелната документација за програмери на USPS

Користете ги информациите за USPS Web Tools и API-ја како почетна точка, а потоа следете ја актуелната документација за програмери и референците специфични за производите што ги наведува USPS. Избегнувајте копирање краен пункт, метод на автентикација, име на поле или известување за повлекување од стар примерок на код без проверка на неговиот актуелен статус.

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

• Точниот производ или производи на 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 и сите услови специфични за производот или оперативни упатства. Чувајте верзиониран запис за референците на крајните точки, мапирањата на полињата, доказите од тестирањето, сопствениците на акредитивите, контактите за ескалација и претпоставките што бараат директна потврда. Повторно разгледајте го записот кога ќе се промени верзијата на API, работниот тек на превозникот, магацинскиот процес или политиката за враќања.

ЧПП

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

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

Дали ми се потребни и интеграција со USPS и интеграција со 17TRACK?

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

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

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

Како треба да се обработуваат недостасувачките настани за следење?

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

Каде треба да се чуваат акредитивите на USPS?

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

Извори

• USPS Web Tools и API-ја — официјална почетна точка на USPS за информации за деловни API-ја.
• Документација за 17TRACK Tracking API — официјална документација за интеграција со 17TRACK API.
• 17RETURNS — официјални информации за производот за случаи на употреба поврзани со управување со враќања.
• 17TRACK API — официјален преглед на производот за сценарија со API за следење.