Przekształcanie dokumentów przez API Subiekta: Jak zautomatyzować workflow od ZK do FS w chmurze

Większość deweloperów integrujących systemy e-commerce lub platformy B2B z systemami ERP traktuje bazę danych jako zbiór płaskich tabel. Kiedy w sklepie internetowym pojawia się zamówienie, ich integrator tworzy dokument w Subiekcie. Kiedy zamówienie zostaje opłacone – tworzy osobną fakturę.

To fundamentalny błąd architektoniczny, który w świecie systemów klasy Enterprise prowadzi do katastrofy: rozjechanych stanów magazynowych, rezerwacji „widmo” i zerwania powiązań relacyjnych między dokumentami.

W profesjonalnych wdrożeniach systemów ERP nie tworzy się faktury „obok” zamówienia. Dokumenty się przekształca. W tym artykule przeanalizujemy, jak zaprojektować i wdrożyć bezbłędne przekształcanie dokumentów przez API Subiekta, mapując standardowe akcje REST na silnik Sfery Nexo za pomocą platformy Subiekt Bridge.

Anatomia prawidłowego Workflow (ZK -> WZ -> FS)

Zanim otworzysz edytor kodu, musisz zrozumieć, jak silnik InsERT Nexo patrzy na cykl życia sprzedaży. Każdy etap ma swój ścisły odpowiednik w logice biznesowej programu:

  1. ZK (Zamówienie od Klienta): Rezerwuje towar na magazynie (skutek magazynowy: odłożony). Nie generuje jeszcze obowiązku podatkowego ani fizycznego ruchu towaru.
  2. WZ (Wydanie Zewnętrzne): Zdjęcia towar z półki magazynowej (skutek magazynowy: wykonany). To moment, w którym kurier odbiera paczkę.
  3. FS (Faktura Sprzedaży) lub PA (Paragon): Dokument handlowy, który wiąże skutek finansowy i podatkowy z wcześniejszym wydaniem magazynowym.

Jeśli Twój system webowy spróbuje po prostu wstawić do bazy INSERT INTO Cenniki/Faktury..., pominiesz rezerwacje, numery partii (kodów partii dostaw), a Subiekt nie powiąże tych dokumentów w module „Śledzenie dokumentów”.

Sfera Nexo jako jedyny gwarant integralności relacji

Przekształcanie dokumentów przez API Subiekta realizowane za pośrednictwem Subiekt Bridge wykorzystuje oficjalny interfejs programistyczny – Sferę Nexo PRO. Dzięki temu Twój kod w PHP, Pythonie czy Node.js wysyła prostego JSON-a, a pod spodem uruchamiane są zaawansowane fabryki obiektów InsERT, takie jak IDokumentyPrzetwarzane czy IPrzetwarzaczDokumentow.

Gdy wywołujesz akcję przekształcenia zamówienia w fakturę końcową, Sfera automatycznie wykonuje następujące operacje:

  • Sprawdza, czy pozycje z zamówienia ZK są dostępne na wybranym magazynie.
  • Przenosi kompletne opisy pozycji, stawki VAT, rabaty oraz powiązane metadane.
  • Zdejmuje rezerwację z ZK i zamienia ją na twardy skutek magazynowy na fakturze (lub powiązanej WZ).
  • Łączy dokumenty relacją natywną – w interfejsie Subiekt Nexo użytkownik widzi drzewo powiązań dokumentu.

Implementacja techniczna: Przekształcanie przez API JSON

W architekturze Subiekt Bridge deweloper nie musi znać niskopoziomowych wskaźników COM systemu Windows. Cały proces sprowadza się do wywołania dedykowanej akcji biznesowej za pomocą metody POST.

Oto jak wygląda modelowy przepływ danych w dojrzałym API.

1. Inicjalizacja zamówienia pierwotnego (POST /api/v1/zamowienia)

Twój system SaaS lub e-commerce (np. IdoSell lub HubSpot) wrzuca do Subiekta zamówienie. System zwraca unikalny identyfikator dokumentu w bazie danych ERP (np. Id: 45012). W tym momencie towar zostaje bezpiecznie zarezerwowany dla tego konkretnego klienta.

2. Wywołanie akcji przekształcenia (POST /api/v1/dokumenty/transform)

Gdy system e-commerce otrzyma potwierdzenie płatności (np. webhook z Stripe/PayU), zamiast budować fakturę od zera, wysyła żądanie transformacji, wskazując dokument źródłowy:

{
  "SourceDocumentId": 45012,
  "TargetDocumentType": "FS",
  "WarehouseId": 100001,
  "PaymentType": "Prepayment",
  "AutoCommitStock": true
}

3. Co w tym momencie robi Subiekt Bridge?

Lokalny agent pobiera żądanie, uruchamia metodę PodajPrzetwarzacz() z menedżera dokumentów Sfery, przekazuje ID zamówienia i jako cel wskazuje encję Faktury Sprzedaży. Sfera weryfikuje parametry i w ułamku sekundy generuje powiązaną fakturę, zwracając jej pełny numer (np. FS 89/05/2026).

Obsługa zaawansowanych scenariuszy e-commerce i B2B

W realnym handlu procesy rzadko są liniowe. Dojrzałe API musi obsługiwać sytuacje niestandardowe, z którymi codziennie mierzą się programiści:

  • Przekształcenia częściowe: Klient zamawia 5 sztuk towaru, ale na magazynie masz tylko 3. Prawidłowo zaimplementowane API pozwala przekształcić ZK do FS tylko dla 3 sztuk, pozostawiając zamówienie ZK jako „w realizacji” dla pozostałych 2 sztuk.
  • Obsługa Kompletów (Zestawów produktów): Jeśli sprzedajesz „Zestaw prezentowy” (komplet w nomenklaturze InsERT), silnik Sfery przy przekształcaniu potrafi automatycznie sprawdzić dostępność wszystkich składników zestawu i odpowiednio złożyć dokument WZ/FS.
  • Automatyczna fiskalizacja: W przypadku transformacji ZK do Paragonu Imiennego (PAi), API pozwala na przekazanie flagi uruchamiającej natywny sterownik urządzenia fiskalnego podłączonego do Subiekta. Paragon drukuje się sam na drukarce fiskalnej w magazynie dokładnie w momencie przetworzenia żądania HTTP.

Jak zoptymalizować wydajność API przy masowym fakturowaniu?

Przekształcanie dokumentów przez API Subiekta to operacja procesowo ciężka dla serwera SQL – uruchamiane są triggery, weryfikowane są tabele rezerwacji i blokad (np. sp_application_lock_acquire). Aby Twój system działał płynnie, zastosuj trzy złote zasady wydajnościowe:

  1. Unikaj odpytywania N+1: Po wykonaniu transformacji nie odpytuj API o szczegóły nowej faktury osobny requestem. Subiekt Bridge w odpowiedzi na żądanie transform od razu zwraca kompletny nagłówek i statusy nowego dokumentu.
  2. Kolejkuj operacje zapisu: Sfera Nexo doskonale radzi sobie z wielowątkowością przy odczycie (GET), ale przy transakcjach zapisu (POST) i blokadach obiektów COM, asynchroniczne uderzanie 50 requestami na sekundę doprowadzi do zakleszczeń (Deadlocks) w SQL. Wdrażaj kolejki po stronie swojej aplikacji SaaS (np. RabbitMQ, Redis) i procesuj transformacje sekwencyjnie.
  3. Wykorzystuj TimeStampy: Sfera implementuje optymistyczne blokowanie współbieżne. Zawsze przekazuj wersję tokenu/timestampu dokumentu, aby mieć pewność, że w czasie, gdy Twój SaaS przetwarzał płatność, pracownik w biurze nie zmodyfikował ręcznie tego samego zamówienia ZK w programie desktopowym.

Podsumowanie

Przekształcanie dokumentów od ZK do FS przy użyciu chmurowego API to fundament nowoczesnej integracji e-commerce. Budując system, który szanuje logikę biznesową i powiązania relacyjne ERP, gwarantujesz swojemu klientowi bezbłędne działanie magazynu, automatyzację pracy księgowości oraz pełną spójność danych. Dzięki narzędziom takim jak Subiekt Bridge, całe to skomplikowane workflow zamykasz w prostych, przewidywalnych żądaniach HTTP JSON.