API интеграции: как да свържете сайта, CRM и счетоводния софтуер
API интеграцията позволява на програмите ви сами да си предават данни: поръчката от сайта става клиент в CRM, фактура в счетоводната програма и пратка при куриера, без никой да преписва. Самото програмиране обикновено е по-малката част от работата. По-голямата е да решите коя система за кои данни отговаря, какво задейства всяко прехвърляне и какво става, когато едната страна не работи или откаже данните. Ако прескочите тези въпроси, получавате дублирани клиенти, липсващи фактури и суми, които никога не излизат точно.
Какво всъщност прави една интеграция
API (програмен интерфейс) е описан начин една програма да поиска данни от друга или да ѝ възложи действие. В бизнеса най-често се срещат три схеми:
- Заявки. Вашата система се обръща към другата: „създай пратка“, „какъв е статусът на поръчка 1045“, „колко бройки има на склад“.
- Известия (webhooks). Другата система сама ви съобщава, когато нещо се случи – например потвърдено или възстановено плащане.
- Файлове по график. Едната страна публикува CSV или XML файл (т.нар. фийд), а другата редовно го зарежда – все още често срещано при ценови листи, наличности и каталози.
Куриерските API-та показват добре какви са възможностите. Документацията на Web API на Спиди например описва методи за създаване на пратки, печат на етикети, заявки за взимане, проследяване, изчисляване на цена и проверка на адреси. С тях магазинът може да покаже цената на доставката още при поръчката, да създава товарителницата с едно натискане и автоматично да изпраща на клиента номер за проследяване.
Най-честите връзки в малкия и средния бизнес
| Връзка | Какво се прехвърля | Кога |
|---|---|---|
| Сайт → CRM | Данните от запитването и страницата, от която е дошло | При изпращане на формата |
| Онлайн магазин → куриер | Адрес, данни за пратката, сума на наложения платеж; обратно: номер на товарителница и статус | При потвърдена поръчка; периодична проверка на статуса |
| Онлайн магазин → фактуриране или счетоводство | Клиент, артикули, ДДС, начин на плащане | При платена или изпратена поръчка |
| Платежен доставчик → магазин | Успешно, неуспешно или възстановено плащане | Известие от доставчика |
| Доставчик на стоки → магазин | Цени и наличности | Зареждане на файл по график |
| Вашата база данни → партньори или приложения | Данни от каталога | Заявки към ваше собствено API |
В последния ред вие сте източникът на данни. Каталогът с технически данни за автомобили auto-data.net обслужва от една база данни многоезичния сайт, приложенията за Android и iOS и платено API – описахме го в „Едно API за сайт и мобилно приложение“.
Решете коя система „притежава“ кои данни
Преди да свържете каквото и да е, запишете къде се създава и къде се редактира всеки вид данни:
- Един собственик за всяко поле. Клиентите може да живеят в CRM, цените – в магазина, фактурите – в счетоводната програма. Ако две системи могат да променят едно и също поле, рано или късно ще си противоречат.
- Постоянни идентификатори. Свързвайте записите по номера, които се пазят и от двете страни, например номера на поръчката до номера на фактурата. Свързването по име или имейл води до дублирани клиенти.
- Таблица на полетата. Поле в система А, поле в система Б и нужното преобразуване между тях – ставки на ДДС, мерни единици, валута, формат на адреса, езикови кодове.
Добър пример защо всичко това трябва да е записано изрично е преминаването на България към еврото от 1 януари 2026 г. при фиксиран курс 1,95583 лева за едно евро. Подобна промяна засяга всяка свързана система, която пази цени или суми – магазина, фактурирането, сумата на наложения платеж при куриера. Ако валутата никъде не е посочена, а просто „се подразбира“, разминаванията между системите идват лесно.
Малките разлики във формата също създават изненадващо много проблеми. В мобилното приложение на auto-data.net потребител от Италия установи, че приложението остава на английски, след като езиковите кодове се промениха от „it“ на „it,it-IT,it-CH“. Решението беше кодовете да се нормализират в API-то, така че всеки вариант да води до правилния език. Таблицата на полетата е мястото, където хващате повечето такива случаи, преди да ги открият клиентите.
Еднопосочно или двупосочно, веднага или по график
Еднопосочният поток, например от магазина към счетоводството, е много по-прост от двупосочната синхронизация, защото не са нужни правила коя промяна печели, когато двете страни редактират един и същи запис. Започвайте с еднопосочни връзки, където е възможно.
Не всичко трябва да става мигновено. Наличностите в натоварен магазин трябва да се обновяват често, но фактурите често може да се създават наведнъж в края на деня. По-бързо означава повече движещи се части, затова изберете скоростта, която бизнесът наистина изисква.
Известията в реално време искат внимание. Документацията на Stripe за webhooks е полезен ориентир, дори никога да не ползвате Stripe: програмистите трябва да връщат отговор за успех бързо, преди всякаква сложна обработка – например преди фактурата да бъде отбелязана като платена в счетоводната система – и да обработват входящите събития през опашка, за да не се претовари сървърът при внезапен пик.
Планирайте за грешки, защото ще има
Връзките се прекъсват: другата система е в профилактика, заявката не получава отговор навреме, някое поле е отхвърлено. Добрата интеграция очаква това. Stripe например посочва, че при реална работа опитва да достави едно събитие до три дни, че не гарантира пристигането на събитията в реда, в който са възникнали, и че едно и също събитие понякога може да пристигне повече от веднъж – затова пазете номерата на обработените събития и пропускайте вече видените.
Същото важи и в обратната посока: добре направената интеграция може безопасно да повтори заявка след прекъсната връзка, без да създаде втори запис. Питайте директно: ако връзката прекъсне по средата, може ли да се окажем с две фактури или две товарителници за една поръчка?
Разумният минимум:
- дневник на всяко прехвърляне – изпратени данни и получен отговор;
- автоматично повторение при временни грешки и списък с останалите;
- конкретен човек, който получава известие при натрупани грешки, и бутон „изпрати отново“;
- периодична проверка дали поръчките в магазина съвпадат с фактурите в счетоводството.
Сигурност и лични данни
- Ключовете стоят на сървъра. API ключовете нямат място в браузъра или в кода на мобилно приложение. Дайте на всяка интеграция собствен ключ с възможно най-тесни права, за да може да бъде спрян, без да спре всичко останало.
- Входящите данни не са надеждни по подразбиране. Списъкът OWASP API Security Top 10 (2023) включва „Unsafe Consumption of APIs“ (небезопасно използване на чужди API) и отбелязва, че програмистите са склонни да вярват на данните от външни API повече, отколкото на въведеното от потребителите. Проверявайте ги като попълнена форма.
- Проверявайте известията. Stripe предупреждава, че без такава проверка нападател може да изпраща фалшиви известия, за да предизвика действия като изпълнение на поръчка, и затова подписва всяко събитие, за да може получателят да го провери.
- Знайте къде отиват личните данни. Уверете се, че договорите и политиката ви за поверителност покриват всеки нов поток от данни на клиенти.
- Събирайте данни коректно. Когато нашата търсачка за продукти gega.bg изтегля снимки на продукти от магазини, тя се представя с честен User-Agent и приема спокойно, ако някой магазин блокира роботи.
Интеграциите искат внимание, когато нещо наистина се промени
Работеща интеграция не трябва да се преправя само защото са излезли по-нови инструменти. Тя обаче има нужда от работа, когато другата страна се промени:
- Доставчикът спира стар интерфейс. От 30 септември 2024 г. Спиди спря да поддържа по-старата си уеб услуга и насочва програмистите към своя REST API. Интеграциите, които я използваха, трябваше да бъдат преместени – реална причина за работа.
- Правилата се променят. С пакета на ЕС „ДДС в цифровата ера“ (ViDA) от 1 юли 2030 г. за трансграничните сделки между фирми ще важат изисквания за цифрово отчитане, основани на електронни фактури, а държавите членки вече могат при определени условия да въвеждат задължително електронно фактуриране. Ако продавате на фирми в други държави от ЕС, попитайте доставчика на счетоводния си софтуер как се подготвя за това.
Предвидете малък бюджет за такава работа и се погрижете интеграцията да е документирана.
Готов модул, платформа за интеграции или собствен код?
Готовият модул (плъгин) за платформата на магазина обикновено е най-евтиният вариант, ако покрива процеса ви такъв, какъвто е – проверете какво прави при грешка и дали някой го поддържа. Платформите, които свързват популярни услуги без програмиране, са подходящи за прости потоци с малък обем. Собственият код има смисъл, когато процесът ви е специфичен, обемите са големи, едната страна няма готов модул или ви трябва пълен контрол върху грешките и данните. Често отговорът е комбинация: готов модул за куриера и собствен код за частта от процеса, която е само ваша.
Въпроси, на които да отговорите, преди да започнете
- Кои системи участват и има ли всяка документирано API и тестова среда?
- Кои данни се прехвърлят, в каква посока и коя система е собственик на всяко поле?
- Какво задейства всяко прехвърляне и колко бързо трябва да стане?
- Как се свързват записите между системите?
- Какво става при неуспешно прехвърляне, кой научава и как се изпраща отново?
- На чие име са профилите и ключовете за API? (Вижте „Собственост на сайта: кой контролира домейна, хостинга, кода и профилите“.)
- Колко ще струва работата на интеграцията: такси за API, абонаменти за модули, хостинг и поддръжка?
Още прехвърляте данни между таблици на ръка? Вижте „Кога бизнесът ви е надраснал таблиците в Excel“.
Ако сайтът, CRM, куриерът и счетоводната ви програма не си „говорят“, можем заедно да опишем потоците от данни и да изградим връзките като част от разработката на уеб базиран софтуер. Пишете ни кои системи използвате.