Technologia

Integracje przez API: jak połączyć stronę, sklep lub panel z ERP, CRM, księgowością i płatnościami

Mapa danych, webhooki, synchronizacja, kolejki, idempotencja, obsługa błędów i bezpieczeństwo kluczy: co musi działać, zanim integracja trafi na produkcję

DualFroz - VulCode CEO·2 października 2026·19 min czytania

Integracja przez API działa dobrze, gdy dla każdej informacji wiadomo trzy rzeczy: który system jest jej źródłem, kto ją przesyła i co się dzieje, gdy przesłanie się nie uda. Samo połączenie sklepu z ERP, CRM, programem księgowym czy operatorem płatności to zwykle kilka wywołań API. Większość pracy i większość awarii dotyczy sytuacji, których nie widać na pokazie: zdarzenia dostarczonego dwa razy, odpowiedzi, która nie przyszła, i systemu, który akurat przechodzi aktualizację.

Przykłady techniczne opieramy na publicznej dokumentacji operatora płatności Stripe, bo opisuje te zachowania wprost. U innych dostawców szczegóły wyglądają inaczej, ale problemy są te same.

W skrócie

Zacznij od mapy danych: dla każdego pola jeden system źródłowy, kierunek przepływu i dopuszczalne opóźnienie.
Webhook to sygnał, a nie gwarancja. Potrafi przyjść dwa razy i w innej kolejności, a jego podpis trzeba sprawdzić.
Między systemami powinna stać kolejka. Zamówienie zapisuje się od razu, a wysyłka do ERP odbywa się w tle, z ponowieniami.
Operacja tworząca dokument musi być idempotentna, inaczej ponowienie po przekroczeniu czasu tworzy podwójne faktury.
Klucze API trzymaj poza kodem, osobno dla każdego środowiska, z minimalnymi uprawnieniami i planem wymiany.
Integracja bez monitoringu i raportu rozbieżności psuje się po cichu.

Mapa danych: od czego zacząć integrację API z ERP i CRM

Pierwszym produktem projektu integracji nie jest kod, tylko tabela. Dla każdego rodzaju danych wpisujesz system, który jest źródłem prawdy, kierunek przepływu i moment, w którym dane mają trafić na drugą stronę. Dla sklepu połączonego z ERP, CRM, księgowością i operatorem płatności mogłaby wyglądać tak:

Przykładowa mapa danych

Dane	Źródło prawdy	Kierunek i moment
Kartoteka towarów: nazwa, kod, stawka VAT	ERP	Z ERP do sklepu, po każdej zmianie albo cyklicznie
Opisy marketingowe i zdjęcia	Sklep	Zostają w sklepie
Stany magazynowe	ERP	Z ERP do sklepu, często, a sklep rezerwuje sztuki przy zamówieniu
Ceny	ERP	Z ERP do sklepu, razem z datą obowiązywania
Zamówienia	Sklep	Ze sklepu do ERP, po potwierdzeniu płatności
Status płatności	Operator płatności	Od operatora do sklepu przez webhook
Faktury	ERP albo program księgowy	Do sklepu wraca numer i dokument dla klienta
Zapytania z formularzy	Strona	Ze strony do CRM, od razu
Status realizacji i numer przesyłki	ERP albo system kurierski	Do sklepu, a stamtąd powiadomienie do klienta

Najważniejsza zasada mapy: jedno źródło prawdy na pole, a nie na rekord. Ten sam klient istnieje we wszystkich systemach, ale adres dostawy zmienia on sam w koncie sklepu, warunki handlowe ustala się w ERP, a opiekuna handlowego przypisuje w CRM. Jeśli dwa systemy mogą edytować to samo pole, trzeba z góry ustalić regułę rozstrzygania konfliktu. Domyślna reguła "ostatni zapis wygrywa" po cichu kasuje zmiany, które ktoś zrobił w drugim systemie kilka minut wcześniej.

Drugim elementem mapy jest dopuszczalne opóźnienie. Opis produktu może pojawić się w sklepie po godzinie, stan magazynowy przy szybko schodzącym towarze powinien być aktualny w ciągu minut, a status płatności w ciągu sekund. Od tej liczby zależy wybór techniki wymiany danych, a więc i koszt integracji.

Trzecim elementem jest tabela powiązań identyfikatorów. Zamówienie ma swój numer w sklepie, inny w ERP i jeszcze inny u operatora płatności. Integracja przechowuje te powiązania w jednym miejscu, bo bez nich nie da się odpowiedzieć na proste pytanie, która faktura należy do którego zamówienia.

Webhook, odpytywanie API czy wymiana plików

Wybór sposobu wymiany danych zależy od tego, co potrafi system po drugiej stronie, i od dopuszczalnego opóźnienia z mapy danych.

Sposoby wymiany danych

Sposób	Kiedy pasuje	Na co uważać
Webhook, czyli system źródłowy sam wysyła zdarzenie na Twój adres	Płatności, zmiany statusów, wszystko, na co trzeba zareagować szybko	Duplikaty, kolejność zdarzeń, publiczny adres i weryfikacja podpisu
Odpytywanie API w stałym odstępie	System nie wysyła webhooków albo dane zmieniają się w przewidywalnym rytmie	Limity zapytań, opóźnienie równe odstępowi, potrzebny filtr "zmienione od"
Wymiana plików CSV lub XML	Starsze systemy, duże paczki danych przetwarzane w nocy	Brak potwierdzenia dla pojedynczych rekordów, format dat i kodowanie znaków
Agent zainstalowany obok systemu	ERP działający na serwerze w biurze, bez API dostępnego z internetu	Kolejny element do aktualizowania i monitorowania

Ostatni wiersz dotyczy firm, w których system sprzedażowo-magazynowy działa lokalnie. Agent to mały program na tym samym serwerze, który czyta i zapisuje dane w ERP przez interfejs przewidziany przez producenta, a z internetem łączy się sam, połączeniem wychodzącym. Dzięki temu nie trzeba otwierać portów do serwera w biurze. Przed wyceną zapytaj dostawcę ERP, jaki interfejs programistyczny udostępnia i czy dostęp do niego wymaga dodatkowej licencji albo modułu.

Przy wymianie plików kłopoty zwykle sprawia format, a nie sama wymiana. Daty w różnych zapisach, przecinek albo kropka w kwotach, kodowanie znaków inne niż UTF-8, przez które polskie litery zamieniają się w krzaczki. Import pliku powinien sprawdzać te rzeczy przed zapisem i odrzucać cały plik z czytelnym raportem, zamiast wczytywać połowę.

W praktyce sposoby się łączy. Webhook daje szybki sygnał, a cykliczne uzgadnianie, na przykład co noc, jest siatką bezpieczeństwa, która wyłapuje wszystko, co sygnał zgubił.

Webhooki: co obsłużyć, zanim przyjdzie pierwsza płatność

Dokumentacja Stripe dotycząca odbierania webhooków dobrze pokazuje, czego trzeba się spodziewać po każdym nadawcy zdarzeń. Stripe zaznacza, że to samo zdarzenie może czasem dotrzeć więcej niż raz, że nie gwarantuje dostarczania zdarzeń w kolejności, w jakiej powstały, i że przy nieudanym dostarczeniu ponawia próby w trybie produkcyjnym do trzech dni, z rosnącymi odstępami. Zaleca też, żeby endpoint szybko zwracał kod 2xx, zanim zacznie jakąkolwiek złożoną logikę, na przykład oznaczanie faktury jako opłaconej w systemie księgowym.

Z tych zachowań wynika lista obowiązkowa dla każdego odbiornika webhooków:

Sprawdź podpis

Nadawca podpisuje treść wspólnym sekretem, na przykład funkcją HMAC z SHA-256, jak robi to Stripe. Podpis liczy się z surowej treści żądania, zanim framework ją przetworzy, a porównuje funkcją odporną na ataki czasowe.

Odrzuć stare zdarzenia

Znacznik czasu w podpisanej treści chroni przed ponownym odtworzeniem przechwyconego żądania. Biblioteki Stripe domyślnie dopuszczają różnicę 5 minut.

Zapisz identyfikator zdarzenia

Zdarzenie o znanym identyfikatorze potwierdzasz kodem 200 i niczego nie robisz drugi raz.

Odpowiedz szybko, przetwarzaj w tle

Odbiornik tylko zapisuje zdarzenie i zadanie do wykonania. Właściwa praca odbywa się w kolejce.

Nie polegaj na kolejności

Jeśli zdarzenie "opłacone" przyjdzie przed "utworzone", pobierz aktualny stan obiektu z API, zamiast budować go z historii zdarzeń.

Uzgadniaj stan cyklicznie

Ponowienia nadawcy kiedyś się kończą. Awarię dłuższą niż okno ponowień wyłapie tylko porównanie stanu po obu stronach.

Poniższy przykład dla Node.js i Express 5 łączy kroki od pierwszego do czwartego. Nazwy nagłówków są umowne, bo każdy nadawca ma własne. Zapis zdarzenia i zadania odbywa się w jednej transakcji bazy danych, więc nie ma stanu, w którym zdarzenie jest zapisane, a zadania brak.

webhook.ts · ts

import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";
import { Pool } from "pg";

const app = express();
const db = new Pool(); // dane połączenia ze zmiennych PGHOST, PGUSER, PGPASSWORD, PGDATABASE
const secret = process.env.WEBHOOK_SECRET ?? "";
const toleranceSec = 300;

app.post("/webhooks/payments", express.raw({ type: "*/*" }), async (req, res) => {
  const body = req.body.toString("utf8");
  const timestamp = req.header("x-webhook-timestamp") ?? "";
  const signature = Buffer.from(req.header("x-webhook-signature") ?? "", "hex");
  const expected = createHmac("sha256", secret).update(`${timestamp}.${body}`).digest();
  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) <= toleranceSec;

  if (signature.length !== expected.length || !timingSafeEqual(signature, expected) || !fresh) {
    res.sendStatus(400);
    return;
  }

  const event = JSON.parse(body);
  const client = await db.connect();
  try {
    await client.query("BEGIN");
    const saved = await client.query(
      "INSERT INTO webhook_events (event_id, type, payload) VALUES ($1, $2, $3) ON CONFLICT (event_id) DO NOTHING",
      [event.id, event.type, event],
    );
    if (saved.rowCount === 1) {
      await client.query("INSERT INTO jobs (kind, ref_id) VALUES ('payment_event', $1)", [event.id]);
    }
    await client.query("COMMIT");
  } catch (err) {
    await client.query("ROLLBACK");
    throw err;
  } finally {
    client.release();
  }
  res.sendStatus(200);
});

app.listen(3000);

Kolumna event_id w tabeli webhook_events ma ograniczenie unikalności. Przykład uruchomiliśmy na Node.js 22, Express 5 i PostgreSQL 17: powtórzone zdarzenie zostawia jeden wiersz w każdej tabeli, zły podpis albo stary znacznik czasu dają odpowiedź 400, a przy niedostępnej bazie nadawca dostaje 500 i ponawia próbę później. Tak ma być: błąd po naszej stronie powinien skutkować ponowieniem, a nie zgubionym zdarzeniem.

Dwie rzeczy, których nie widać w kodzie. Przekierowanie przeglądarki klienta na stronę "dziękujemy za płatność" nie jest potwierdzeniem płatności, bo klient może zamknąć kartę przed powrotem, a adres powrotu da się otworzyć ręcznie. Status zamówienia zmienia dopiero zdarzenie od operatora albo odpytanie jego API. Druga sprawa: sekret do weryfikacji podpisu też się wymienia. Stripe pozwala przy wymianie utrzymać stary sekret aktywny do 24 godzin, żeby zdążyć wdrożyć nowy.

Kolejka między systemami: zamówienie nie czeka na ERP

Najprostsza integracja wysyła zamówienie do ERP w chwili, w której klient klika "zamawiam". Działa, dopóki ERP odpowiada szybko. Gdy ERP przechodzi aktualizację albo wolno odpowiada, klient widzi błąd albo kręcące się kółko, a zamówienie może zostać zapisane w sklepie bez odpowiednika w ERP.

Rozwiązaniem jest kolejka. Sklep zapisuje zamówienie i w tej samej transakcji dopisuje zadanie "wyślij do ERP". Osobny proces pobiera zadania i wysyła je dalej. Gdy ERP nie odpowiada, zadanie czeka i jest ponawiane, a klient o niczym nie wie. Ten wzorzec bywa nazywany skrzynką nadawczą (transactional outbox) i jest dokładnie tym, co robi przykład z poprzedniej sekcji po stronie odbioru.

Ponowienia muszą mieć rosnące odstępy i niewielki losowy rozrzut, żeby po awarii setki zadań nie uderzyły w ERP w tej samej sekundzie. Muszą też mieć limit. Zadanie, które wyczerpało próby, trafia na listę błędów w panelu, z opisem zrozumiałym dla człowieka i przyciskiem "ponów" po poprawieniu przyczyny.

Nie każdy błąd zasługuje na ponowienie. Podział wygląda zwykle tak:

Rodzaje błędów w integracji

Rodzaj błędu	Przykład	Co robić
Przejściowy	Przekroczony czas, odpowiedź 502 lub 503	Ponowić z rosnącym odstępem
Limit zapytań	Odpowiedź 429 Too Many Requests	Odczekać, a jeśli serwer podał nagłówek Retry-After, to tyle, ile wskazuje
Błąd danych	Brak towaru o danym kodzie w ERP, niepoprawny NIP, odpowiedź 400 lub 422	Nie ponawiać, przekazać człowiekowi z opisem
Autoryzacja	Odpowiedź 401 po wygaśnięciu tokenu	Odświeżyć token raz, przy kolejnym błędzie podnieść alarm
Nieznany wynik	Połączenie zerwane po wysłaniu żądania	Sprawdzić stan w systemie docelowym albo ponowić z kluczem idempotencji

Kod 429 i możliwość dołączenia do niego nagłówka Retry-After opisuje RFC 6585. Publiczne API zwykle mają limity zapytań, które dają o sobie znać w najgorszym momencie: przy pierwszym imporcie całej kartoteki albo na koniec miesiąca, gdy ruszają procesy rozliczeniowe. Pełna synchronizacja powinna sama pilnować tempa.

Idempotencja: ponawianie bez podwójnych faktur

Operacja jest idempotentna, jeśli wykonana kilka razy daje ten sam skutek co wykonana raz. Ustawienie statusu na "wysłane" jest idempotentne. Utworzenie faktury nie jest: każde wywołanie tworzy nowy dokument.

Typowy scenariusz: integracja wysyła do ERP żądanie utworzenia faktury, ERP ją tworzy, ale odpowiedź nie dociera, bo połączenie zostało zerwane. Integracja widzi przekroczony czas i ponawia żądanie. W ERP są teraz dwie faktury do jednego zamówienia, a ktoś w księgowości będzie je wyjaśniał.

Są trzy sposoby, żeby tego uniknąć, i dobra integracja używa tylu, ile pozwala system po drugiej stronie.

Klucz idempotencji. Część API przyjmuje w żądaniu unikalny klucz i przy powtórce z tym samym kluczem zwraca wynik pierwszego wywołania zamiast wykonywać operację ponownie. Stripe opisuje to szczegółowo: zapisuje kod i treść odpowiedzi na pierwsze żądanie z danym kluczem, także gdy był to błąd 500, porównuje parametry kolejnych żądań z pierwotnymi i zwraca błąd, gdy się różnią, a klucze mogą być usuwane po co najmniej 24 godzinach. Zaleca też losowe klucze, na przykład UUID w wersji 4, bez danych osobowych w środku. Nagłówek Idempotency-Key był opisywany w projekcie standardu IETF, ale projekt wygasł w 2026 roku bez publikacji jako RFC. Każde API ma więc własne zasady: czy w ogóle obsługuje klucze, jak długo je pamięta i co zwraca przy powtórce.

Najpierw szukaj, potem twórz. Jeśli API nie obsługuje kluczy, integracja zapisuje numer zamówienia ze sklepu w polu dokumentu przeznaczonym na numer zewnętrzny, a przed utworzeniem dokumentu sprawdza, czy taki już istnieje. Żeby to działało, zadania dotyczące jednego zamówienia nie mogą wykonywać się równolegle, bo dwa procesy mogą jednocześnie nie znaleźć dokumentu i oba go utworzyć.

Deduplikacja po stronie odbiorcy. To, co robi przykład z webhookiem: identyfikator zdarzenia zapisany z ograniczeniem unikalności. Ta sama technika działa przy imporcie plików, gdzie każdy wiersz ma identyfikator z systemu źródłowego.

Osobną sprawą są kwoty. Pieniądze w integracji przechowuje się jako liczby całkowite w groszach albo w typie dziesiętnym, nigdy jako liczby zmiennoprzecinkowe, bo te nie zapisują dokładnie większości ułamków dziesiętnych. Do tego sklep i ERP mogą liczyć VAT różnymi metodami, na przykład od cen netto albo od cen brutto, albo zaokrąglać na każdej pozycji zamiast na całym dokumencie. Wtedy suma faktury różni się od kwoty zamówienia o grosz lub dwa, a uzgadnianie płatności zaczyna zgłaszać rozbieżności. Metodę liczenia trzeba ustalić na etapie mapy danych.

Synchronizacja danych: stany, ceny, usunięcia i konflikty

Synchronizacja przyrostowa pobiera tylko rekordy zmienione od ostatniego przebiegu. Jest szybka i oszczędza limity zapytań, ale ma dwie słabości. Pierwsza to granica czasu: rekord zmieniony w trakcie przebiegu albo zapisany z opóźnionym znacznikiem czasu może wypaść między dwa okna. Dlatego kolejny przebieg zaczyna się nieco wcześniej, niż skończył się poprzedni, a powtórnie pobrane rekordy obsługuje się idempotentnie. Druga słabość to usunięcia. Jeśli API nie zgłasza usuniętych rekordów, przyrostowa synchronizacja ich nie zobaczy i towar wycofany w ERP zostanie w sklepie.

Obie słabości łata okresowe pełne uzgadnianie. Raz na dobę integracja porównuje listy identyfikatorów, stany i sumy kontrolne po obu stronach i tworzy raport rozbieżności. Raport, który codziennie pokazuje zero, jest najlepszym dowodem, że integracja działa, a rozbieżności powyżej ustalonego progu powinny wysyłać powiadomienie, bo raportu nikt nie czyta codziennie.

Stany magazynowe wymagają osobnej uwagi, bo między dwoma przebiegami synchronizacji ten sam towar może się sprzedać w sklepie internetowym i w sklepie stacjonarnym. Pomagają trzy rzeczy: rezerwacja sztuk w chwili złożenia zamówienia, częstsza synchronizacja dla towarów o małym stanie i bufor bezpieczeństwa, czyli pokazywanie w sklepie o kilka sztuk mniej, niż jest w magazynie. Wielkość bufora to decyzja biznesowa, nie techniczna.

Daty przesyłaj zawsze ze strefą czasową, w formacie ISO 8601 z przesunięciem względem UTC. Data zapisana bez strefy działa poprawnie przez większą część roku i psuje się dwa razy w roku, przy zmianie czasu, a także wtedy, gdy jeden z serwerów stoi w innej strefie niż drugi.

Polskie realia: KSeF, biała lista VAT i dane z rejestru REGON

Integracje z księgowością w Polsce w 2026 roku nie kończą się na programie księgowym. Według harmonogramu Ministerstwa Finansów wystawianie faktur w Krajowym Systemie e-Faktur jest obowiązkowe od 1 lutego 2026 roku dla przedsiębiorców, których sprzedaż w 2024 roku przekroczyła 200 mln zł z podatkiem, a od 1 kwietnia 2026 roku dla pozostałych. Do końca 2026 roku poza KSeF mogą jeszcze wystawiać faktury podatnicy, u których łączna wartość sprzedaży dokumentowanej fakturami nie przekracza 10 000 zł z podatkiem w miesiącu. Odbieranie faktur przez KSeF jest obowiązkowe od 1 lutego 2026 roku. Faktury dla konsumentów nie muszą trafiać do KSeF, choć mogą.

Dla integracji oznacza to, że faktura sprzedażowa ma swój numer nadawany przez KSeF i ten numer warto przechowywać przy zamówieniu, a faktury kosztowe mogą trafiać do systemu firmy prosto z KSeF, zamiast przez skrzynkę mailową. Jak podejść do samego połączenia z KSeF, opisaliśmy w tekście KSeF: integracja z systemem.

Przy klientach i dostawcach biznesowych przydają się dwa publiczne źródła danych:

API Wykazu podatników VAT, czyli białej listy. Pozwala sprawdzić status podatnika VAT i numer rachunku po NIP lub REGON. Według Ministerstwa Finansów metoda "search" pozwala na 100 zapytań dziennie o maksymalnie 30 podmiotów naraz, a metoda "check" na sprawdzenie 5000 podmiotów. Po wyczerpaniu limitu dostęp może zostać zablokowany do północy. Wyniki warto więc przechowywać i nie sprawdzać tego samego kontrahenta przy każdym zamówieniu.
API REGON prowadzone przez GUS. Pozwala wyszukać dane firmy po numerze REGON, NIP lub KRS, na przykład żeby uzupełnić formularz rejestracji klienta biznesowego po wpisaniu NIP. Według portalu API GUS usługa i dane są bezpłatne, a klucz produkcyjny podmioty komercyjne otrzymują po zgłoszeniu do GUS.

Bezpieczeństwo kluczy API i tokenów

Klucz API do ERP albo do operatora płatności daje dostęp do danych i pieniędzy firmy, więc traktuje się go jak hasło administratora. W praktyce sprowadza się to do kilku zasad:

Poza kodem i repozytorium. Klucze trafiają do zmiennych środowiskowych albo menedżera sekretów. Klucz raz wpisany do repozytorium uznaje się za ujawniony, nawet po usunięciu, bo zostaje w historii zmian.
Nigdy w przeglądarce ani w aplikacji mobilnej. Wszystko, co trafia do kodu frontendu, jest publiczne. Wywołania wymagające tajnego klucza idą przez serwer, a w przeglądarce może działać tylko klucz, który dostawca wprost przeznaczył do użytku publicznego.
Osobne klucze dla środowisk i integracji. Klucz testowy nie działa na produkcji, a wyciek klucza jednej integracji nie otwiera pozostałych.
Minimalne uprawnienia. Jeśli integracja tylko czyta stany magazynowe, jej klucz nie powinien móc tworzyć dokumentów.
Plan wymiany. Spisana procedura: kto wymienia klucz, gdzie go podmienia i jak sprawdza, że wszystko działa. Pisze się ją, zanim będzie potrzebna.
Czyste logi. Logi integracji nie zawierają kluczy, tokenów ani pełnych danych osobowych. Do diagnozy wystarczą identyfikatory i kody błędów.

Wiele CRM-ów i systemów chmurowych zamiast stałego klucza używa protokołu OAuth 2.0. Integracja dostaje wtedy krótko żyjący token dostępu i token odświeżania, który trzeba bezpiecznie przechowywać. Aktualne zalecenia zbiera RFC 9700 ze stycznia 2025 roku. Wynika z niego między innymi, że nie wolno używać przepływu, w którym aplikacja zbiera login i hasło użytkownika, a tokeny dostępu powinny być ograniczone do konkretnego serwera zasobów. W codziennej pracy najważniejsze jest co innego: token odświeżania może przestać działać, na przykład gdy ktoś w CRM odbierze integracji dostęp. Integracja musi wtedy podnieść alarm, a nie po cichu przestać synchronizować.

Integracje przenoszą też dane osobowe klientów. Jeśli dostawca CRM albo firma, która buduje i utrzymuje integrację, przetwarza te dane w Twoim imieniu, potrzebna jest umowa powierzenia przetwarzania z art. 28 RODO, a zabezpieczenia muszą odpowiadać ryzyku, czego wymaga art. 32. Do tego dochodzi zasada minimalizacji: do CRM wysyłasz tylko te pola, których handlowiec naprawdę potrzebuje, a nie całe zamówienie z adresem i historią płatności.

Testy i odbiór integracji

Integracji nie sprawdza się jednym udanym zamówieniem. Sprawdza się ją scenariuszami awarii, bo to one zdarzą się na produkcji. Przed odbiorem warto przejść przez taką listę na środowisku testowym operatora płatności i na testowej kopii bazy ERP:

Podwójne zdarzenie

Ten sam webhook wysłany dwa razy tworzy jedno zadanie i jeden dokument.

Odwrócona kolejność

Zdarzenie "opłacone" przed "utworzone" daje poprawny stan końcowy.

Niedostępny system docelowy

ERP wyłączony na godzinę: zamówienia czekają w kolejce i po włączeniu przechodzą bez duplikatów.

Przekroczony czas po wysłaniu

Ponowienie nie tworzy drugiej faktury.

Limit zapytań

Odpowiedzi 429 spowalniają integrację, ale jej nie zatrzymują.

Błędne dane

Zamówienie z towarem bez odpowiednika w ERP trafia na listę błędów z czytelnym opisem.

Wygasły dostęp

Odebranie uprawnień w CRM podnosi alarm w ciągu ustalonego czasu.

Raport rozbieżności

Rekord zmieniony ręcznie po jednej stronie pojawia się w raporcie po najbliższym uzgadnianiu.

Po odbiorze integracja potrzebuje monitoringu, który mówi o niej, a nie tylko o serwerze. Cztery liczby wystarczą na początek: długość kolejki, wiek najstarszego oczekującego zadania, liczba błędów w ostatniej godzinie i czas ostatniej udanej synchronizacji w każdym kierunku. Szersze zasady obserwowania systemu po starcie opisaliśmy w tekście po wdrożeniu: monitoring i utrzymanie.

Uruchomienie na produkcji zaczyna się zwykle od importu początkowego, a dopiero potem włącza się bieżącą wymianę. Kolejność ma znaczenie: jeśli najpierw włączysz webhooki, a import zrobisz później, część zdarzeń dotyczyć będzie rekordów, których jeszcze nie ma.

Jak przygotować zapytanie o integrację

Wycenę integracji najbardziej przyspiesza konkret o systemach po obu stronach. Przygotuj:

Nazwy i wersje systemów oraz informację, czy działają w chmurze, czy na serwerze w firmie.
Dostęp do dokumentacji API i do środowiska testowego, jeśli dostawca je udostępnia, a także informację, czy API wymaga dodatkowej licencji.
Mapę danych z tej strony, choćby w wersji roboczej: co płynie dokąd, kto jest źródłem prawdy i jakie opóźnienie jest akceptowalne.
Wolumeny, czyli liczbę zamówień dziennie, towarów w kartotece i klientów w CRM, a także szczyty, na przykład okres przedświąteczny.
Osobę od błędów, czyli kto w firmie będzie obsługiwał listę zadań, które nie przeszły, i poprawiał dane źródłowe.

Jeśli dane, które mają płynąć między systemami, żyją dziś w arkuszu, zacznij od jego uporządkowania. Jak to zrobić i kiedy arkusz warto zastąpić panelem, opisaliśmy w tekście panel zamiast arkusza. Gdy integracja jest częścią nowego produktu, w pierwszej wersji często wystarczy eksport do pliku, a pełna integracja dochodzi po sprawdzeniu, że produkt jest potrzebny, o czym piszemy w tekście MVP: jak zbudować pierwszą wersję.

Najczęstsze pytania o integracje przez API

Ile kosztuje integracja przez API?

Zależy od liczby systemów, kierunków przepływu i jakości API po drugiej stronie. Jednokierunkowe przesyłanie zapytań z formularza do CRM to inny projekt niż dwukierunkowa synchronizacja stanów, cen i zamówień z ERP zainstalowanym w biurze. Rzetelną wycenę dają dopiero mapa danych i dokumentacja API, dlatego pytamy o konkretne nazwy systemów, a nie o ogólną "integrację z księgowością".

Czy da się zintegrować sklep z ERP zainstalowanym na serwerze w biurze?

Tak, zwykle przez agenta zainstalowanego obok ERP, który sam łączy się z serwerem sklepu. Warunkiem jest interfejs programistyczny udostępniany przez producenta ERP. Jeśli go nie ma, zostaje wymiana plików, o ile system potrafi je eksportować i importować.

Co jest lepsze: webhook czy odpytywanie API?

Najczęściej oba naraz. Webhook daje szybką reakcję, a odpytywanie albo nocne uzgadnianie wyłapuje zdarzenia, które nie dotarły. Jeśli system nie wysyła webhooków, zostaje odpytywanie z filtrem "zmienione od".

Jak szybko dane pojawią się w drugim systemie?

Tak szybko, jak ustalicie w mapie danych. Webhooki docierają krótko po zdarzeniu, a dane wymieniane przez odpytywanie z opóźnieniem równym odstępowi między zapytaniami. Krótszy odstęp oznacza szybsze zużywanie limitów.

Co się stanie, gdy dostawca zmieni API?

Dostawcy zwykle wersjonują API i zapowiadają wycofanie starszych wersji. Konto deweloperskie załóż na firmowy adres, który ktoś czyta, a w integracji wskazuj wersję API wprost, jeśli dostawca na to pozwala.

Czy wystarczy gotowa wtyczka albo platforma integracyjna?

Często tak, zwłaszcza dla popularnych par systemów i standardowych przepływów. Przed wyborem sprawdź, czy wtyczka obsługuje Twoją mapę danych, w tym pola niestandardowe, jak raportuje błędy, czy ma ponowienia i ile kosztuje przy Twoim wolumenie. Własna integracja ma sens wtedy, gdy przepływ jest nietypowy albo gdy gotowe narzędzie nie daje kontroli nad błędami.

Od czego zacząć

Zacznij od mapy danych: wypisz, jakie informacje przepisujesz dziś ręcznie między systemami, który system powinien być ich źródłem i jak szybko muszą trafić na drugą stronę. Już ta tabela pokaże, czy potrzebujesz pełnej integracji, czy wystarczy eksport pliku raz dziennie.

Integracje i automatyzacje to jedna z naszych usług. Zakres opisujemy na stronie Integracje i Automatyzacje, a przebieg współpracy na stronie jak pracujemy. Po oddaniu projektu dostajesz pełne prawa do kodu i dokumentację, więc integrację może dalej utrzymywać Twój zespół albo inny wykonawca. Jeśli masz już listę systemów, napisz do nas.

Czy ten wpis był przydatny?