Subiekt nexo API: integracja i automatyzacja bez otwierania Waszego serwera na świat
Subiekt to program, który stoi na komputerze albo serwerze w Waszej sieci, a dane trzyma w bazie Microsoft SQL Server. Nie ma publicznego adresu, pod który scenariusz z chmury mógłby wysłać żądanie. Wchodzimy więc tam, gdzie faktycznie da się wejść: warstwą Sfera dla zapisu i bazą SQL dla odczytu, przez pośrednika działającego w Waszej sieci. Pierwsze przejście robimy na kopii bazy.
- 2 drogi wejściawarstwa Sfera, czyli interfejs programistyczny producenta, albo baza Microsoft SQL Server. Trzecia droga to pośrednik w rodzaju BaseLinkera i plik wymiany, i czasem to ona jest tańsza
- 0 portów otwartych z internetupośrednik w Waszej sieci sam wychodzi na zewnątrz, więc do serwera z Subiektem nie trzeba wpuszczać ruchu z zewnątrz ani wystawiać bazy
- 2 do 4 tygodniod warsztatu do integracji na produkcji, po przejściu całego przepływu na kopii bazy, nie na Waszej bazie produkcyjnej
Problem
Dlaczego Subiekta nie da się spiąć tak, jak usługi z chmury?
Kto integrował kiedyś sklep albo CRM działający w chmurze, ten szuka trzech rzeczy: adresu usługi, tokenu i dokumentacji zasobów. Przy Subiekcie znajdzie co innego. Program jest instalowany lokalnie, w systemie Windows, a jego dane leżą w bazie Microsoft SQL Server na Waszym serwerze. Z punktu widzenia scenariusza w chmurze ten serwer po prostu nie istnieje, bo nie ma adresu, pod który dałoby się wysłać żądanie.
Dlatego integracja z Subiektem zaczyna się od pytania, którego przy usłudze chmurowej nikt nie zadaje: kto i skąd ma się do niego odezwać. Odpowiedź brzmi zawsze podobnie. Potrzebny jest pośrednik działający w tej samej sieci co program: mały serwis na Waszym serwerze albo agent lokalny, który sam wychodzi na zewnątrz i odbiera zadania z kolejki. Bez tego zostaje otwieranie portu i wystawianie bazy do internetu, czego nie robimy.
Drugie pytanie dotyczy tego, czym się do programu odezwać. Producent udostępnia do tego warstwę Sfera, czyli obiektowy interfejs programistyczny, dostępny jako oddzielna licencja, a warianty i wymagania opisuje strona InsERT dla programistów. Druga droga to czytanie danych wprost z bazy SQL. Różnica jest zasadnicza: Sfera zapisuje przez logikę programu, a zapytanie do bazy widzi tylko tabele. Dlatego 1 decyzja z warsztatu, którą drogą idziemy, przesądza potem o połowie ryzyka.
- Scenariusz w chmurze nie ma jak dosięgnąć programu, który stoi w serwerowni
- Nikt w firmie nie wie, czy licencja Sfera jest wykupiona, dopóki ktoś nie sprawdzi
- Dokument wstawiony wprost do tabel wygląda dobrze w bazie i źle w programie
- Po aktualizacji programu zapytanie pisane pod poprzedni schemat bazy przestaje zwracać to samo
- Zestawienie sprzedaży ktoś eksportuje do arkusza ręcznie, raz w tygodniu, od lat
Dlaczego teraz
Sfera, baza SQL albo pośrednik: którą drogą wejść u Was?
Sfera to droga domyślna wszędzie tam, gdzie integracja ma coś ZAPISAĆ. Pracuje na tych samych obiektach, z których korzysta program, więc faktura albo dokument magazynowy powstaje z numeracją, walidacjami i zapisami magazynowymi takimi, jakby wystawił je człowiek przy biurku. Kosztem jest licencja i to, że kod musi działać na Windows, obok programu. Zanim cokolwiek napiszemy, sprawdzamy, co dokładnie obejmuje Wasza licencja.
Baza Microsoft SQL Server to droga do ODCZYTU. Zestawienia sprzedaży, stany, kartoteki, zasilanie hurtowni danych i raportów: to wszystko da się wyciągnąć zapytaniem, bez ruszania czegokolwiek w programie. Robimy to przez widoki tylko do odczytu i osobnego użytkownika bazy z samym prawem SELECT. Zapisu wprost do tabel unikamy, bo omija on logikę programu, a skutki widać dopiero za miesiąc, przy zamknięciu okresu.
Trzecia droga bywa najrozsądniejsza i mówimy o niej wprost, zamiast sprzedawać wdrożenie. Jeśli chodzi o stany i zamówienia z marketplace, dane często wystarcza wystawić przez BaseLinkera albo plik wymiany, bo taka wymiana jest już po obu stronach obsługiwana. Własną integrację budujemy wtedy, gdy potrzebna jest logika mapowania, kilka magazynów naraz albo pola, których gotowa wymiana nie przenosi.
Osobno stoją obowiązki podatkowe. Wysyłkę e-faktur do KSeF i pliki JPK obsługuje moduł producenta w samym programie i nie zastępujemy go własnym kodem. Zakres obowiązku i harmonogram są po stronie Ministerstwa Finansów, na stronie KSeF, a nasza rola kończy się na doprowadzeniu do Subiekta poprawnych danych, z których dokument ma powstać.
Co się zmienia
Co dostaje osoba, która potem to utrzymuje?
Dokumenty powstają tak, jakby wystawił je człowiek
Zapis idzie warstwą Sfera, czyli przez logikę programu: numerację, powiązania z kartoteką i zapisy magazynowe. Księgowa nie dostaje dokumentu, który istnieje w bazie, ale nie zgadza się z magazynem.
Zapis przez obiekty programu, nie wstawka do tabeli
Serwer zostaje zamknięty
Pośrednik działa w Waszej sieci i sam wychodzi na zewnątrz po zadania. Nie trzeba otwierać portu, wystawiać bazy SQL do internetu ani mieć stałego adresu IP w biurze.
0 portów otwartych z internetu do serwera z Subiektem
Odczyt, który nie zwalnia pracy w programie
Dane czytamy widokami tylko do odczytu, osobnym użytkownikiem bazy z prawem SELECT. Ciężkie zapytania na dużej bazie chodzą poza godzinami pracy, żeby nikomu nie zwalniały wystawiania dokumentów.
Użytkownik bazy z samym prawem SELECT, bez prawa zapisu
Aktualizacja programu nie kładzie integracji
Zapytania i mapowania trzymamy w jednym miejscu, spisane, a nie rozsypane po scenariuszach. Przed aktualizacją produkcyjną przepuszczamy je na kopii bazy, więc zmianę w schemacie widzicie przed wdrożeniem, nie po.
Mapowania w jednym pliku, sprawdzane na kopii bazy przed aktualizacją
Pierwszy zapis dopiero po kopii zapasowej
Kolejność jest zawsze ta sama: kopia bazy, środowisko testowe na tej kopii, kopia zapasowa produkcji, dopiero potem pierwszy prawdziwy zapis. Do każdego wdrożenia dokładamy plan wycofania.
Ani jednego zapisu w bazie produkcyjnej przed wykonaniem kopii
Pytania o sprzedaż i magazyn zwykłym zdaniem
„Ile zostało tego towaru”, „które faktury z tego tygodnia są nieopłacone”, „jak szła sprzedaż tej marki w lipcu”. BOND, nasz firmowy agent AI, odpowiada z tych danych bez wchodzenia do programu.
Odpowiedź w 5 do 10 sekund, bez licencji Subiekta dla pytającego
A u Ciebie
Co, jeśli u nas nikt jeszcze nie ruszał Subiekta z zewnątrz?
Cztery zdania, które przy tej integracji słyszymy najczęściej, i to, co na nie odpowiadamy.
Mamy Subiekta GT, nie nexo.
Obie linie mają swoją drogę wejścia i obie obsługujemy: warstwę Sfera po stronie producenta oraz bazę Microsoft SQL Server. Różnice siedzą w szczegółach: inny model obiektów, inny schemat bazy, inne wymagania licencyjne. Dlatego wersję programu i zakres licencji ustalamy na warsztacie, przed wyceną, a nie w trakcie wdrożenia.
Nie damy dostępu do bazy firmie z zewnątrz.
Nie musicie. Zakładacie użytkownika bazy z prawem SELECT do wskazanych widoków, a dane zostają na Waszym serwerze. Pośrednik też stoi u Was i my go tylko konfigurujemy. Do warsztatu wystarcza rozmowa, struktura danych i próbka bez danych osobowych. Po wdrożeniu hasła rotujecie sami.
Nasz serwer stoi w biurze i nie ma stałego IP.
Nie jest potrzebne. Pośrednik w Waszej sieci sam nawiązuje połączenie na zewnątrz i sam odbiera zadania z kolejki, więc ruch idzie w jedną stronę: od Was. Gdy łącze padnie, zadania czekają w kolejce, a po powrocie sieci przepływ nadrabia zaległość, zamiast gubić dokumenty.
Mamy BaseLinkera, on już się z Subiektem dogaduje.
Wtedy mówimy, żeby przy tym zostać, dopóki wystarcza, i nie sprzedajemy wdrożenia obok. Własna integracja ma sens wtedy, gdy potrzebne jest inne mapowanie towarów, kilka magazynów naraz, pola, których gotowa wymiana nie przenosi, albo gdy w grze są systemy poza sprzedażą: CRM, hurtownia danych, agent AI.
- Subiekt i InsERT
- Subiekt nexo, Subiekt GT, warstwa Sfera, baza Microsoft SQL Server
- Pośrednik w Waszej sieci
- mały serwis na serwerze, agent lokalny, kolejka zadań, połączenie wychodzące
- Sprzedaż
- BaseLinker, Allegro, Shopify, WooCommerce, PrestaShop
- Księgowość i fakturowanie
- Fakturownia, iFirma, Comarch Optima, sevDesk
- Warstwa automatyzacji
- n8n, Make, Zapier, własne integracje przez API
- Dane, CRM i praca zespołu
- BigQuery, Google Sheets, bazy SQL, HubSpot, Pipedrive, Slack, Microsoft 365
Operacje na Subiekcie: którą drogą i o czym pamiętać
Siedem operacji, od których zwykle zaczyna się integracja, razem z drogą wejścia i pułapką, która przy każdej wraca najczęściej. Nazw metod ani limitów nie podajemy z pamięci: czytamy je z dokumentacji producenta dla Waszej wersji programu.
| Operacja | Którą drogą | O czym pamiętać |
|---|---|---|
| Odczyt towarów, cen i stanów | widok tylko do odczytu w bazie SQL | przy dużej bazie ciężkie zapytania chodzą poza godzinami pracy, żeby nie zwalniać programu |
| Wystawienie faktury albo dokumentu magazynowego | warstwa Sfera | zapis przez logikę programu, więc numeracja i magazyn zgadzają się z ręcznym wystawieniem |
| Założenie i aktualizacja kontrahenta | Sfera, po sprawdzeniu numeru NIP w bazie | duplikat sprawdzamy przed zapisem, bo dwa razy założony kontrahent rozjeżdża rozrachunki |
| Przyjęcie dostawy z pliku od dostawcy | plik wymiany albo Sfera | kody towarów walidujemy przed zapisem, brakujące trafiają do kolejki ręcznej |
| Zasilenie hurtowni danych sprzedażą | odczyt z bazy SQL, ładowanie przyrostowe | kursor po dacie i identyfikatorze dokumentu, żeby nie ciągnąć całej historii przy każdym uruchomieniu |
| Stany i zamówienia z marketplace | BaseLinker jako pośrednik | często tańsze od własnej integracji, sprawdzamy to przed wyceną wdrożenia |
| Wysyłka e-faktur do KSeF i pliki JPK | moduł producenta w programie | nie zastępujemy go własnym kodem, doprowadzamy tylko poprawne dane do dokumentu |
Pierwsze wdrożenie obejmuje zwykle dwie albo trzy operacje z tej listy. Reszta wchodzi tym samym torem, po pomiarze pierwszych.
Jak to robimy
Pięć kroków od programu w serwerowni do integracji na produkcji
Każdy krok kończy się czymś, co możesz ocenić, zanim zdecydujesz o następnym. Pierwsze trzy nie zmieniają ani jednego rekordu w Waszej bazie produkcyjnej.
Warsztat
Tydzień. Ustalamy cel, a potem twarde fakty: wersja i linia programu, zakres licencji, czy Sfera jest wykupiona, gdzie fizycznie stoi serwer i baza, ile dokumentów na dobę przechodzi przez firmę, kto dziś klika to ręcznie. Wynikiem jest dokument z drogą wejścia i listą operacji, nie kod.
Kopia bazy i środowisko testowe
Odtwarzamy Wasze dane na kopii bazy, osobno od produkcji. Tam sprawdzamy realne kształty: kontrahent bez numeru NIP, towar w kilku magazynach, korekta, dokument w obcej walucie. To one decydują o walidacji, a nie przykłady z dokumentacji.
Pośrednik i pierwsze odczyty
Stawiamy pośrednika w Waszej sieci, z połączeniem wychodzącym i kolejką zadań. Pierwsze przejście jest wyłącznie odczytem: widoki tylko do odczytu, użytkownik bazy z prawem SELECT, zero zapisów. Porównujemy wynik z tym, co pokazuje program.
Pierwszy zapis po kopii zapasowej
Kopia zapasowa bazy produkcyjnej, potem pilot z zapisem na wąskim zakresie: jeden magazyn albo jeden typ dokumentu. Do tego plan wycofania i wyłącznik po Waszej stronie. Dokumenty z pilota sprawdza osoba, która wystawia je dziś ręcznie.
Produkcja, monitoring i procedura na aktualizację
Przełączamy z monitoringiem błędów i kolejką, w której odrzucone zadanie leży razem z danymi i odpowiedzią, gotowe do ponowienia. Zostaje spisana procedura na aktualizację Subiekta: sprawdzenie mapowań na kopii bazy przed podniesieniem wersji. Pomiar po 30 i 90 dniach.
Przed i po
Jak zmienia się dzień osoby, która dziś klika to w Subiekcie
Przedtem
- Zamówienie ze sklepu ktoś przepisuje do Subiekta ręcznie, pozycja po pozycji
- Stany w sklepie zgadzają się z magazynem do pierwszej sprzedaży w dwóch kanałach
- Zestawienie sprzedaży dla zarządu powstaje z eksportu do arkusza, raz w tygodniu
- Pytanie „ile mamy tego towaru” wymaga dostępu do programu i wolnego stanowiska
Po zmianie
- Dokument powstaje w Subiekcie sam, warstwą Sfera, z numeracją i zapisem magazynowym
- Stan idzie z jednego procesu zapisującego, więc nie ma dwóch źródeł prawdy
- Sprzedaż ląduje w hurtowni danych przyrostowo, a raport odświeża się bez człowieka
- Na pytanie o stan i o nieopłacone faktury odpowiada agent AI, w 5 do 10 sekund
Pierwszy przepływ na produkcji zwykle 14 dni po warsztacie, przy szerszym zakresie 2 do 4 tygodni. Liczbę odrzuconych zadań, ponowień i ręcznych korekt oceniamy po 30 i po 90 dniach.
Dla osoby, która to zamawia
Co z tego ma właściciel albo osoba odpowiedzialna za systemy
Subiekt trzyma sprzedaż, magazyn i rozrachunki, więc każdy pomysł na integrację jest dla Ciebie pytaniem o ryzyko, nie o technologię. Brzmi ono tak: co się stanie, gdy integracja zapisze coś nie tak w piątek po południu. Po naszym wdrożeniu odpowiedź jest w procedurze i w kolejce błędów: jest kopia zapasowa, jest wyłącznik, jest plan wycofania i jest osoba u Was, która umie ponowić zadanie.
Druga rzecz dotyczy rozliczenia z decyzji. Pierwsze trzy kroki nie zmieniają w bazie produkcyjnej niczego, a warsztat kończy się dokumentem, który obroni się bez nas. Jeśli po nim okaże się, że cel załatwia gotowa wymiana z BaseLinkerem albo plik, mówimy to wprost. Kończy się wtedy na jednym tygodniu pracy, nie na wdrożeniu.
- Dane i licencja zostają u Was, pośrednik stoi w Waszej sieci
- Pierwsze przejście wyłącznie odczytem, zapis dopiero po kopii zapasowej
- Plan wycofania, wyłącznik i kolejka błędów zostają u Was po wdrożeniu
- Spisana procedura na aktualizację programu, więc integracja nie wisi na jednej osobie
Ile to kosztuje
Warsztat ma cenę jawną, integracja wycenę po nim
Warsztat procesowy kosztuje 2500 zł netto za tydzień. Przy jednej integracji zwykle wystarcza jeden tydzień: ustalenie wersji i licencji, wybór drogi wejścia, lista operacji, projekt pośrednika i plan testów na kopii bazy. Integrację wyceniamy po warsztacie, gdy wiadomo, ile operacji wchodzi w grę, w jakim stanie jest baza i co stoi po drugiej stronie.
Licencję Subiekta i licencję Sfera, jeśli okaże się potrzebna, płacisz InsERT bezpośrednio, według jego cennika. Tak samo koszt scenariuszy w Make albo n8n oraz koszt użycia modeli, gdy dochodzi agent AI. Nie doliczamy prowizji i nie pośredniczymy w tych płatnościach.
Warsztat procesowy
2500 zł netto
za tydzień, przy jednej integracji zwykle jeden
Zamknięta całość. Kończy się dokumentem technicznym, który Wasz programista albo Wasza firma informatyczna zrealizuje bez nas.
- Ustalenie wersji programu, zakresu licencji i drogi wejścia
- Lista operacji do wykonania, z podziałem na Sferę i odczyt z bazy
- Projekt pośrednika w Waszej sieci, bez otwierania portów
- Plan środowiska testowego na kopii bazy i plan wycofania
- Wskaźniki do pomiaru po 30 i 90 dniach
- Najczęściej wybierany
Warsztat i integracja Subiekta
Wycena po warsztacie
zakres wynika z liczby operacji i systemów po drugiej stronie
Najczęściej wybierany wariant. Działający przepływ w 2 do 4 tygodni od warsztatu, sprawdzony najpierw na kopii bazy.
- Wszystko z warsztatu
- Pośrednik w Waszej sieci z kolejką zadań i połączeniem wychodzącym
- Zapis warstwą Sfera, odczyt widokami tylko do odczytu
- Pilot na wąskim zakresie po kopii zapasowej, z wyłącznikiem
- Monitoring, kolejka błędów i procedura na aktualizację programu
- Szkolenie osoby, która ma potem czytać log i ponawiać zadania
Integracja i agent AI
Wycena po warsztacie
dla firm, w których o stany i faktury pyta się codziennie
Wszystko z integracji plus BOND, firmowy agent AI, który odpowiada z tych danych zwykłym zdaniem. Wdrożenie agenta zajmuje około 2 miesiące.
- Wszystko z integracji Subiekta
- Hurtownia danych z dokumentami, stanami i rozrachunkami
- Agent AI odpowiada z tych danych w 5 do 10 sekund
- Alerty o brakach na magazynie i o nieopłaconych fakturach po terminie
- Dostęp dla handlowców i magazynu, bez licencji Subiekta dla każdego
Warsztat kończy się dokumentem, który obroni się bez nas: droga wejścia, lista operacji, projekt pośrednika i plan testów na kopii bazy. Jeśli okaże się, że cel załatwia gotowa wymiana z BaseLinkerem albo plik od dostawcy, mówimy to wprost i pokazujemy, jak to ustawić. Sprawa kończy się wtedy na warsztacie, a nie na integracji, której nie potrzebujecie.
Najczęstsze pytania
Czy Subiekt ma API REST, do którego wyślemy żądanie z chmury?
Nie w tym sensie, w jakim ma je usługa chmurowa. Subiekt jest programem instalowanym lokalnie, a jego dane leżą w bazie Microsoft SQL Server na Waszym serwerze, więc nie ma publicznego adresu, pod który scenariusz z zewnątrz mógłby się odezwać. Dostęp jest lokalny: warstwa Sfera albo baza SQL. Żeby dosięgnął go system z chmury, potrzebny jest pośrednik działający w Waszej sieci.
Czym jest warstwa Sfera i czy potrzebujemy do niej licencji?
Sfera to obiektowy interfejs programistyczny producenta: pozwala programowi z zewnątrz korzystać z tej samej logiki, z której korzysta Subiekt, więc dokumenty powstają z numeracją i zapisami magazynowymi jak przy ręcznym wystawieniu. Jest dostępna jako oddzielna licencja, a szczegóły i warianty opisuje strona InsERT dla programistów. Czy jest w Waszej licencji, sprawdzamy na warsztacie, bo od tego zależy zakres wdrożenia.
Czy można czytać dane wprost z bazy Microsoft SQL Server?
Tak, i przy odczycie to jest nasza droga domyślna. Zakładamy widoki tylko do odczytu i osobnego użytkownika bazy z samym prawem SELECT, bez prawa zapisu. Tak zasilamy hurtownię danych, raporty i agenta AI. Przy dużej bazie ciężkie zapytania planujemy poza godzinami pracy, żeby nie zwalniały wystawiania dokumentów w programie.
Dlaczego nie zapisujecie dokumentów wprost do tabel w bazie?
Bo zapytanie widzi tabele, a nie zasady programu. Wstawka wprost do tabel omija numerację, powiązania z kartoteką, zapisy magazynowe i reguły podatkowe, więc dokument istnieje w bazie, ale nie zgadza się z magazynem ani z rozrachunkami. Skutki widać zwykle po miesiącu, przy zamknięciu okresu, i sprząta je człowiek. Dlatego zapis idzie warstwą Sfera, a baza zostaje do odczytu.
Co się dzieje z integracją po aktualizacji Subiekta?
Nowa wersja programu może zmienić schemat bazy, więc zapytanie napisane pod poprzedni układ tabel przestaje zwracać to samo. Dlatego mapowania i zapytania trzymamy spisane w jednym miejscu, a nie rozsypane po scenariuszach, i przepuszczamy je na kopii bazy przed podniesieniem wersji na produkcji. Ta procedura zostaje u Was razem z wdrożeniem.
Czy trzeba wystawić nasz serwer albo bazę do internetu?
Nie i nie robimy tego. Pośrednik działa w Waszej sieci i sam nawiązuje połączenie na zewnątrz, po zadania z kolejki, więc ruch idzie w jedną stronę i nie trzeba otwierać portu ani mieć stałego adresu IP. Gdy łącze padnie, zadania czekają w kolejce, a po powrocie sieci przepływ nadrabia zaległość.
Kiedy prościej użyć BaseLinkera albo pliku wymiany niż budować integrację?
Gdy chodzi o typową sprzedaż: stany, zamówienia i dokumenty między sklepem, marketplace i Subiektem. Taka wymiana jest już obsługiwana po obu stronach, więc własny kod dokłada koszt bez nowej wartości. Własną integrację budujemy przy innym mapowaniu towarów, kilku magazynach naraz, polach, których gotowa wymiana nie przenosi, albo gdy w grę wchodzą systemy poza sprzedażą: CRM, hurtownia danych, agent AI.
Ile trwa wdrożenie i od czego się zaczyna?
Tydzień warsztatu, a potem 2 do 4 tygodni na integrację, przy czym pierwszy działający przepływ zwykle stoi po 14 dniach od warsztatu. Zaczynamy od kopii bazy i odczytu, bez ani jednego zapisu w produkcji. Pierwszy zapis idzie na wąskim zakresie i dopiero po kopii zapasowej, z planem wycofania.
Sprawdźmy, którą drogą da się wejść do Waszego Subiekta
Bezpłatna konsultacja trwa 30 minut. Mówisz, jaka to wersja programu, gdzie stoi serwer i co ma się dziać automatycznie, a my mówimy, czy droga prowadzi przez Sferę, przez odczyt z bazy, czy przez gotową wymianę z BaseLinkerem. Nie musisz na tym etapie dawać dostępu do bazy ani wysyłać danych.
Prowadzimy najwyżej dwa wdrożenia równocześnie, żeby przy każdym ktoś realnie siedział.
Umów bezpłatną konsultacjęPS. Jeśli ktoś u Was przepisuje zamówienia do Subiekta ręcznie albo eksportuje sprzedaż do arkusza raz w tygodniu, to jest dokładnie ten problem. Dokument może powstawać sam, z numeracją i zapisem magazynowym, a odpowiedź o stan magazynu może przyjść w 5 do 10 sekund. Piszesz do Pawła, założyciela, nie na skrzynkę zbiorczą.