Comarch Optima API: kontrahenci, endpointy REST, pola i synchronizacja

Co to jest kontrahent w Comarch Optima

Kontrahent w Optimie to dowolny podmiot zewnętrzny, z którym firma prowadzi obrót: klient (odbiorca), dostawca albo jedno i drugie. W module Handel kontrahent jest wymagany do każdego dokumentu sprzedaży i zakupu. W module Kasa/Bank — do każdej płatności i rozrachunku. W Księdze Handlowej — do analityki kosztów i przychodów.

Automatyzacja procesów w tej encji przyspiesza sprzedaż, fakturowanie, rozrachunki i księgowanie, bo jeden zapis kontrahenta może od razu zasilić dokumenty handlowe, płatności i raporty. W interfejsie Optimy kontrahenci siedzą w: Ogólne → Kontrahenci. Przez Optima API od WebArm nigdy nie piszesz bezpośrednio do bazy danych. Zamiast tego używasz HTTP — a serwer Optima API wywołuje pod spodem oficjalną warstwę biznesową Optimy, która robi dokładnie to, co operator klikający „Zapisz” w oknie kartoteki. WebArm utrzymuje kompatybilność Optima API z każdą nową wersją Comarch ERP Optima — Twoja integracja kontrahentów nie ląduje w ślepej uliczce przy upgrade.

Kiedy użyć API kontrahentów w Comarch Optima

Hasło Comarch Optima kontrahenci API dobrze opisuje sytuację, w której zewnętrzny system musi odczytywać lub zapisywać kartotekę klientów, dostawców, odbiorców B2B albo płatników bez ręcznego klikania w Optimie. Najczęściej chodzi o integrację CRM, sklepu internetowego, panelu B2B, WMS, marketplace albo drugiego systemu ERP.

Najważniejsza decyzja wdrożeniowa brzmi: który system jest źródłem prawdy dla danych kontrahenta. Jeśli źródłem jest sklep lub CRM, Optima API przyjmuje nowe dane przez POST /api/kontrahenci/ i aktualizacje przez PUT /api/kontrahenci/{kod}. Jeśli źródłem jest Comarch ERP Optima, zewnętrzny system powinien pobierać dane po kodzie, ID lub paczkami przez batch/read, a konflikty rozwiązywać w warstwie integracyjnej. Wybór źródła prawdy oznacza, że to ten system decyduje o ostatecznym kształcie danych w całym procesie integracji.

W praktyce API kontrahentów rzadko działa samotnie. Ten sam proces dotyka zwykle zamówień, faktury sprzedaży, dokumentów handlowych, towarów, płatności, rachunków bankowych i stanów magazynowych. Dlatego wdrożenie Web API powinno od razu określać, które dane idą z e-commerce do Optimy, które wracają z Optimy do CRM, a które są tylko odczytywane do raportów i monitoringu.

Takie Web API porządkuje integrację z innymi aplikacjami: e commerce, CRM, WMS, panelem B2B albo systemem zewnętrznym, umożliwiając wymianę danych pomiędzy systemami za pomocą API. W module Handel ten sam kontrahent pojawia się później na fakturach sprzedaży, dokumentach magazynowych, płatnościach i dokumentach handlowych, więc przed wdrożeniem trzeba ustalić także datę dokumentu, datę operacji, stawkę VAT, rachunki bankowe oraz reguły księgowe.

Nie jest to dokumentacja Comarch ERP XL. Jeżeli porównujesz Optimę z Comarch ERP XL, traktuj ten opis jako zakres dla kartoteki kontrahentów w Comarch ERP Optima i dla operacji wykonywanych przez Optima API, a nie jako wspólny kontrakt dla obu systemów.

Potrzeba biznesowa	Endpoint Optima API	Co sprawdzić przed wdrożeniem
Nowy klient z e-commerce trafia do Optimy	POST /api/kontrahenci/	Reguła nadawania kodu, deduplikacja po NIP/e-mail, rodzaj kontrahenta.
CRM aktualizuje dane klienta B2B	PUT /api/kontrahenci/{kod}	Semantyka partial update: pole pominięte i null nie zmieniają wartości, pusty string czyści pole.
Migracja kartoteki klientów z innego ERP	POST /api/kontrahenci/batch	Paczki do 100 rekordów, mapowanie adresów, status błędu per rekord.
Aplikacja B2B pobiera tylko wybranych klientów	POST /api/kontrahenci/batch/read	Lista kodów lub identyfikatorów po stronie aplikacji i zachowanie dla brakujących rekordów.
Segmentacja klientów, limity lub scoring	/api/kontrahenci/{kod}/atrybuty/	Definicje atrybutów w Optimie, format wartości i odpowiedzialność za aktualizację.

Taki zakres odróżnia stronę encji od ogólnego opisu integracji. Tutaj chodzi o konkretny kontrakt REST dla kartoteki kontrahentów: metody HTTP, pola DTO, batch, atrybuty, adres i zachowanie Optimy po zapisie.

Jeżeli firma ma starszą integrację opartą o obiekty COM albo bezpośrednie zapytania do bazy danych SQL, Optima API porządkuje implementację integracji: jedno REST API, jedna autoryzacja, jawne błędy i powtarzalne wykonywanie operacji. SOAP i XML warto zostawić tylko tam, gdzie są już elementem starszego B2B; dla nowych integracji kontrahentów bezpieczniejszy jest kontrakt HTTP/JSON z walidacją Optimy. To ułatwia rozwój automatyzacji, bo aplikacje zewnętrzne nie muszą znać wewnętrznych tabel Comarcha.

Jak synchronizować kontrahentów w systemie Comarch ERP Optima

Synchronizacja kontrahentów w ERP powinna łączyć trzy elementy: stabilny identyfikator klienta, deduplikację po NIP lub e-mailu oraz zapis przez mechanizmy Comarch ERP Optima. Do integracji z Comarch Optima najczęściej wykorzystuje się REST API, webservice albo dedykowaną warstwę pośredniczącą, która odpowiada za autoryzację, mapowanie pól i obsługę błędów. WebArm realizuje to przez Optima API i VerSync: CRM, sklep internetowy, panel B2B albo drugi ERP wysyła zmianę kontrahenta, a warstwa integracyjna decyduje, czy wykonać POST, PUT czy batch update.

Jeżeli szukasz firmy, która pomoże w synchronizacji kontrahentów w ERP, zwróć uwagę nie tylko na samo połączenie systemów. Ważne są konflikty danych, retry błędów, audyt zmian, mapa pól i jasne reguły, który system jest źródłem prawdy. WebArm oferuje usługi integracyjne obejmujące wdrożenie, konfigurację oraz bieżące wsparcie synchronizacji Comarch ERP Optima z innymi systemami. Synchronizację kontrahentów łączy z dokumentami, płatnościami, cennikami i zamówieniami zamiast traktować kartotekę klienta jako izolowaną tabelę.

Scenariusz	Zalecany mechanizm
Nowy klient ze sklepu	POST /api/kontrahenci/ przed utworzeniem faktury lub zamówienia.
Aktualizacja danych z CRM	PUT /api/kontrahenci/{kod} z partial update i kontrolą pól pustych.
Import wielu klientów	POST /api/kontrahenci/batch do 100 rekordów w jednym żądaniu.
Deduplikacja	Odczyt kandydatów, porównanie NIP/e-mail i zapis atrybutu kontrolnego.
Stała synchronizacja	Pipeline VerSync: webhook, kolejka, retry, logi i monitoring.

Struktura zasobów

• /api/kontrahenci/ — create, create-batch, read-batch, update-batch
• /api/kontrahenci/{kod} — get, update, delete pojedynczego kontrahenta
• /api/kontrahenci/id/{id} — get po wewnętrznym ID Optimy
• /api/kontrahenci/{kod}/atrybuty/ — lista i ustawianie atrybutów
• /api/kontrahenci/{kod}/atrybuty/{atrybutKod} — usunięcie pojedynczego atrybutu

Lista wszystkich endpointów z opisami — w sekcji Endpointy powyżej.

Przykład: utworzenie kontrahenta i dokumentów powiązanych

Minimalny payload (tylko wymagane):

curl -X POST https://optima.twoja-firma.pl/api/kontrahenci/ \
  -H "X-Api-Key: <klucz>" \
  -H "X-Optima-Firma: FIRMA_GLOWNA" \
  -H "Content-Type: application/json" \
  -d '{
    "kod": "ACME001",
    "nazwa1": "ACME Sp. z o.o.",
    "nip": "5732233120",
    "nipKraj": "PL",
    "rodzaj": 0
  }'

Po utworzeniu kontrahenta ten sam proces może od razu przejść do dokumentów powiązanych: faktury sprzedaży, zamówienia, płatności albo dokumentu magazynowego. W praktyce najważniejsze jest zachowanie tego samego kodu kontrahenta, NIP-u i reguł płatności w całym przepływie.

Rozszerzony payload kontrahenta zwykle obejmuje:

Obszar danych	Przykładowe pola	Uwagi wdrożeniowe
Identyfikacja	kod, nazwa1, nazwa2, nip, nipKraj	Kod jest kluczem biznesowym, a NIP służy głównie do deduplikacji.
Kontakt i adres	email, telefon1, ulica, miasto, kodPocztowy	Adres jest obiektem zagnieżdżonym; integracja musi mapować go świadomie.
Rozliczenia	cennik, termin, formaPlatnosciId, rachunekNr	Te pola wpływają na faktury sprzedaży, dokumenty handlowe i rozrachunki.
Atrybuty	segment, limit, źródłoDanych	Atrybuty lepiej aktualizować osobnym endpointem, jeśli zmieniają się niezależnie od kartoteki.

Odpowiedź (HTTP 201 Created): pełny obiekt KontrahentDto z polami nadanymi przez Optimę (id, pola computed nazwaPolaczona, nipPelny) oraz wartościami, które Optima mogła uzupełnić po walidacji.

Przykład: aktualizacja z partial update

Chcesz zmienić tylko email i wyczyścić domyślny rachunek:

curl -X PUT https://optima.twoja-firma.pl/api/kontrahenci/ACME001 \
  -H "X-Api-Key: <klucz>" \
  -H "X-Optima-Firma: FIRMA_GLOWNA" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "rachunekNr": ""
  }'

Semantyka pól:

Wartość w JSON	Znaczenie
pole pominięte	Brak zmiany
null	Brak zmiany
"" (pusty string)	Wyczyść pole (gdzie to dozwolone — np. rachunekNr, email, url)
konkretna wartość	Ustaw na tę wartość

To jest kluczowa różnica względem większości REST API, gdzie null i "" traktowane są tak samo.

Przykład: batch create 100 kontrahentów

POST /api/kontrahenci/batch
{
  "items": [
    { "kod": "K0001", "nazwa1": "Firma A", "nip": "1111111111", "nipKraj": "PL", "rodzaj": 0 },
    { "kod": "K0002", "nazwa1": "Firma B", "nip": "2222222222", "nipKraj": "PL", "rodzaj": 0 },
    ...
  ]
}

Limit: 100 pozycji na żądanie. Jedna sesja, jeden zapis — rząd wielkości szybciej niż 100 pojedynczych POST-ów. Odpowiedź zawiera status per pozycję — jeśli 3 się nie uda (np. duplikat kodu), dostaniesz 201 z listą 97 sukcesów i 3 błędów.

Integracja z VerSync od WebArm — orkiestracja synchronizacji

Optima API od WebArm daje Ci endpointy. VerSync od WebArm daje gotowy silnik, który:

• mapuje Twoje pola zewnętrzne (z CRM, sklepu, innego ERP) na strukturę KontrahentDto,
• decyduje, kiedy POST (nowy), a kiedy PUT (aktualizacja),
• obsługuje dedup po NIP, emailu lub custom rule,
• monitoruje konflikty i retry’uje błędy,
• pozwala konfigurować real-time sync (webhook → queue → Optima) albo batch.

Jeśli robisz integrację dla jednego klienta — Optima API od WebArm wystarczy. Jeśli zarządzasz synchronizacją dla wielu klientów albo chcesz silnik, który nie wymaga kodowania pipeline’u od zera — zobacz VerSync od WebArm.

Dlaczego przez oficjalną warstwę Optimy

Optima API od WebArm wymusza zapis przez oficjalną warstwę biznesową Optimy. Mogłoby pisać bezpośrednio do bazy danych — byłoby szybsze. Nie robi tego, bo:

• Walidacja biznesowa — Comarch sprawdza NIP, kody kraju, unikalność, relacje. Bezpośredni zapis to pomija.
• Event handlers — niektóre pola wyzwalają inne zmiany (np. zmiana grupy aktualizuje limity). Bezpośredni zapis to omija.
• Kompatybilność między wersjami — schemat bazy może zmieniać się przy aktualizacjach Optimy. Wykorzystanie oficjalnej warstwy stabilizuje API.
• Gwarancja Comarcha — bezpośredni zapis do bazy powoduje utratę wsparcia Comarcha przy problemach.

Komunikacja z API powinna odbywać się przez HTTPS, a dostęp do firmy i użytkownika powinien być ograniczony tokenem lub kluczem API. Dzięki temu integracja nie udostępnia bezpośrednio serwera SQL, tylko kontrolowany serwer obsługujący API, logi, limity i walidację operacji. Ten sam wzorzec można później wykorzystać do eksportu dokumentów, pobierania PDF-ów albo automatycznego tworzenia dokumentów handlowych powiązanych z kontrahentem.

Dodatkowo po każdym zapisie Optima API od WebArm robi weryfikację zapisu — czyta z Optimy to, co właśnie zapisało, i porównuje z request. Jeśli Optima po cichu zmieniła wartość (np. zignorowała pole rodzaj), zwraca 400 zamiast udawać, że wszystko się powiodło. To kosztuje dodatkowy round-trip, ale chroni przed dryfem między Twoją integracją a stanem w Optimie.