Kontrahenci w Comarch Optima przez REST API — endpointy, pola, pułapki

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.

W interfejsie Optimy kontrahenci siedzą w: Ogólne → Kontrahenci. Przez Optima API nigdy nie piszesz bezpośrednio do bazy danych. Zamiast tego używasz HTTP — a API wywołuje pod spodem oficjalną warstwę biznesową Optimy, która robi dokładnie to, co operator klikający „Zapisz” w oknie kartoteki.

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

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
  }'

Z pełnym adresem, atrybutami i domyślnym cennikiem:

{
  "kod": "ACME001",
  "nazwa1": "ACME Sp. z o.o.",
  "nazwa2": "Oddział Łódź",
  "nip": "5732233120",
  "nipKraj": "PL",
  "email": "[email protected]",
  "telefon1": "+48 42 123 45 67",
  "grupa": "KLUCZOWI",
  "rodzaj": 1,
  "cennik": 3,
  "termin": 14,
  "formaPlatnosciId": 2,
  "adres": {
    "ulica": "Piotrkowska",
    "nrDomu": "100",
    "miasto": "Łódź",
    "kodPocztowy": "90-001",
    "kraj": "Polska",
    "wojewodztwo": "łódzkie"
  },
  "atrybuty": [
    { "kod": "SEGMENT", "wartosc": "Premium" }
  ]
}

Odpowiedź (HTTP 201 Created): pełny obiekt KontrahentDto z polami nadanymi przez Optimę (id, pola computed nazwaPolaczona, nipPelny).

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:

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 — orkiestracja synchronizacji

Optima API daje Ci endpointy. Versync 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 — API Optima wystarczy. Jeśli zarządzasz synchronizacją dla wielu klientów albo chcesz silnik, który nie wymaga kodowania pipeline’u od zera — zobacz Versync.

Dlaczego przez oficjalną warstwę Optimy

Optima API 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.

Dodatkowo po każdym zapisie Optima API 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.