Idempotencja: jedno pole, które oszczędza tydzień tłumaczeń księgowości

Timeout nie znaczy porażka

To jest źródło całego problemu i najczęściej mylone miejsce w integracjach.

Timeout mówi ci tylko tyle, że nie dostałeś odpowiedzi. Nie mówi, że operacja się nie wykonała. ERP mógł przyjąć zamówienie, zapisać dokument, nadać mu numer - i dopiero potem połączenie padło albo odpowiedź nie dotarła. Z twojej strony wygląda to identycznie jak sytuacja, w której nic się nie stało.

Dwa różne stany świata, jedna obserwacja. I musisz podjąć decyzję.

Dwie złe odpowiedzi

Bez idempotencji masz do wyboru dwie strategie i obie są złe.

Ponów. Jeśli dokument powstał, właśnie powstał drugi raz. Klient dostaje dwie faktury na to samo zamówienie, magazyn dostaje dwa polecenia wydania, a księgowość spędza tydzień na wystawianiu korekt i tłumaczeniu kontrahentowi, co się stało. Przy jednym zamówieniu to wpadka. Przy awarii sieci trwającej dwadzieścia minut to czterysta zamówień.

Nie ponawiaj. Jeśli dokument nie powstał, zamówienie klienta zniknęło. Klient jest przekonany, że kupił - w sklepie ma potwierdzenie. W ERP nie ma nic, więc nikt tego nie spakuje i nie wyśle. Dowiadujesz się o tym po tygodniu, telefonem.

Wybór między „podwójna faktura" a „zgubione zamówienie" nie jest wyborem architektonicznym. Jest przyznaniem się, że modelu zabrakło.

Jak to wygląda w praktyce

Rozwiązanie jest banalne i dlatego irytujące, gdy się o nim zapomni.

Sklep nadaje własny, unikalny numer referencyjny zamówienia i wysyła go razem z dokumentem. ERP zapisuje ten numer w polu - własnym, dodatkowym, obojętnie jakim, byle dało się po nim wyszukiwać.

Wtedy obsługa timeoutu przestaje być zgadywaniem i staje się procedurą:

1. Timeout.
2. Zapytaj ERP: masz dokument z referencją SK-2026-04812?
3. Jeśli tak - gotowe, zapisz numer dokumentu, idź dalej.
4. Jeśli nie - ponów bezpiecznie.

To wszystko. Cała idempotencja w tym kontekście to jedno pole i jedno zapytanie sprawdzające. Nie potrzeba do tego transakcji rozproszonych ani żadnej ciężkiej teorii.

Warunek jest jeden: pole musi istnieć po stronie ERP-a. W Subiekcie czy nexo robi się to polem własnym - i to jest jeden z konkretnych powodów, dla których przy integracji z Subiektem wersja rozszerzona bywa wymaganiem, a nie wygodą.

Dlaczego to trzeba ustalić na początku

Bo dopisanie pola własnego do kartoteki, w której leży czterdzieści tysięcy dokumentów, to migracja danych i przestój - a nie poprawka.

I bo bez tego pola retry w kolejce staje się bronią wymierzoną w ciebie. Kolejka z automatycznym ponawianiem plus brak idempotencji to maszyna do produkowania duplikatów, działająca dokładnie wtedy, gdy najbardziej boli - podczas awarii. Ta para musi być zaprojektowana razem, o czym piszę też w tekście o kolejkach.

Pytanie kontrolne, które warto zadać na etapie analizy: czy da się w waszym ERP zapisać przy dokumencie numer nadany przez sklep i potem po nim wyszukać? Jeśli odpowiedź brzmi „nie", właśnie znalazłeś jedno z największych ryzyk projektu - i lepiej wiedzieć o nim w tygodniu drugim niż w dniu, w którym padnie łącze.

Co dalej

• Gdzie zapisać numer referencyjny w polskim ERP: Integracja z Subiekt GT
• Retry bez idempotencji to maszyna do duplikatów: Kolejki RabbitMQ i Redis
• Pełny przegląd integracji: pillar /integracje