Какво е нужно за надеждна API интеграция с плащания, ERP, CRM и резервации

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

#Удостоверяване и пазене на ключовете

Всяка интеграция започва с идентификационни данни и оттам започват и повечето проблеми със сигурността. Най-често се използва API ключ в заглавката на заявката или OAuth 2.0, при който системата ви разменя клиентски идентификатор и таен ключ срещу краткотраен токен за достъп.

• Ключовете не се пазят в кода. Съхранявайте ги в променливи на средата или в специализирано хранилище за тайни, никога в Git хранилището. Ключ, който някога е бил записан там, се смята за изтекъл и трябва да се смени.
• Отделни ключове за тест и за реална работа. Платежните доставчици и много ERP системи предлагат тестова среда. Ползвайте я за разработка и автоматични тестове и направете така, че тестовата среда физически да няма достъп до реалните ключове.
• Минимални права. Ако интеграцията само чете поръчки, ключът ѝ не бива да може да прави възстановяване на плащания.
• Изтичане на токена. Подновявайте OAuth токените преди да изтекат. Ако заявка върне 401, подновете токена веднъж и опитайте още веднъж. Всичко след това е истинска грешка.
• План за смяна. Трябва да е ясно как се подменя ключ без прекъсване на работата и кой има право да го направи.

#Идемпотентност: безопасно повторение на заявка

Да кажем, че онлайн магазинът ви изпраща към платежния доставчик заявка за плащане с карта, а връзката прекъсва, преди да дойде отговор. Плащането може да е минало, а може и да не е. Ако повторите заявката сляпо, клиентът може да бъде таксуван два пъти. Ако не я повторите, поръчката може да остане неплатена, въпреки че парите са изтеглени.

Решението е идемпотентността. За всяка бизнес операция, например за всеки опит за плащане на поръчка, генерирате уникален ключ и го изпращате със заявката. Ако доставчикът получи същия ключ втори път, връща първоначалния резултат, без да изпълнява операцията отново. Stripe и други платежни API поддържат заглавка Idempotency-Key точно за тази цел.

Когато едно API няма такава възможност, същата гаранция се изгражда от ваша страна:

• Запишете операцията в своята база данни с уникален идентификатор преди да се обърнете към външната система.
• Изпращайте своя идентификатор като външна референция, например номера на поръчката във фактурата в ERP.
• Преди повторен опит проверете във външната система дали вече съществува запис с тази референция.

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

#Таймаути, повторни опити и изчакване

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

Повтаряйте само грешките, които имат шанс да минат при втори опит:

Отговор	Повторен опит?	Какво да се направи
Мрежова грешка или таймаут	Да, с ключ за идемпотентност	Изчакване и нов опит
Сървърна грешка 5xx	Да	Изчакване и нов опит
429 Too Many Requests	Да	Изчакване толкова, колкото указва заглавката Retry-After, ако я има
Грешка при валидация 400 или 422	Не	Поправка на данните и известие към отговорник
401 или 403	Веднъж, след подновяване на токена	След това се третира като грешка в настройките

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

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

#Уебкукове: проверка, потвърждение и обработка

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

• Проверявайте подписа. Повечето доставчици подписват всеки уебкук, обикновено с HMAC от суровото тяло на заявката и споделен таен ключ. Изчислявайте подписа върху суровото тяло, преди да парсвате JSON, и сравнявайте за постоянно време.
• Отхвърляйте стари съобщения. Ако подписът съдържа времеви печат, отказвайте събития извън кратък интервал, за да спрете повторно изпратени заявки.
• Отговаряйте бързо. Запишете събитието, върнете отговор 2xx и свършете истинската работа в опашка. При бавен отговор доставчикът приема, че има грешка, и изпраща събитието отново.
• Очаквайте дубликати и разбъркан ред. Уебкуковете могат да дойдат два пъти, със закъснение или не по ред. Пазете идентификатора на събитието, а когато редът има значение, взимайте текущото състояние на обекта от API вместо да разчитате на съдържанието на събитието.
• Не разчитайте само на уебкукове. Ако адресът ви е бил недостъпен един час, част от събитията може никога да не бъдат изпратени отново. Сверяването, описано по-долу, хваща това, което уебкуковете пропускат.

#Версии, логове и известия

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

Ако публикувате собствено API за партньори или мобилно приложение, въведете версии още от първото издание, опишете го с OpenAPI документ и поддържайте старата версия, докато клиентите не преминат към новата.

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

Логовете помагат само ако някой ги чете, затова добавете известия за сигналите, които имат значение:

• Делът на грешките при даден доставчик се вдига над обичайното ниво.
• Опашката с неуспешни задачи не е празна.
• Няма пристигнали уебкукове в период, в който би трябвало да има.
• Сверяването открива разминавания.

#Сверяване на данните и документация

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

Документацията позволява на следващия разработчик или на собствения ви екип след година да поддържа интеграцията. Тя трябва да съдържа поне:

• Кои системи са свързани, в каква посока и какво задейства всяка синхронизация.
• Съответствието на полетата: кое поле при вас в кое поле при тях се превръща, включително мерни единици, валути и часови зони.
• Къде се пазят ключовете (никога самите стойности) и как се сменят.
• Правилата за повторни опити и какво се прави, когато задача попадне в опашката с неуспешни.
• Тестовите акаунти и стъпките за пускане на интеграционните тестове.

Ако поемате интеграция, изградена от някой друг, започнете от този списък. Статията как да поемете сайт или приложение, изградено от друг екип разглежда предаването на проекта като цяло.

#Как може да помогне PN Scripts

PN Scripts свързва платежни доставчици, системи за резервации, ERP и CRM чрез техните API и уебкукове, с повторни опити, логове и известия при неуспешна заявка. Всяка интеграция има автоматични тестове и документация за вашия екип. Как това се вписва в един проект, ще видите на страницата за изработка на уеб приложения.