Towary w Comarch Optima przez REST API — endpointy, pola, stany, sync

Co to jest towar w Comarch Optima

Kartoteka towarów w Optimie (Handel → Towary) przechowuje wszystko, co firma sprzedaje, kupuje lub wykorzystuje — fizyczne towary, usługi, produkty złożone z komponentów.

Optima API udostępnia 25 endpointów pokrywających:

• CRUD pojedynczo i batch (do 100 create/update, do 500 read),
• stany magazynowe per magazyn + agregaty,
• cenniki (pobierane razem z towarem albo osobno przez endpoint cenników),
• atrybuty standardowe i zależne od kontrahenta (B2B pricing),
• dodatkowe jednostki miary (opakowania, palety),
• incremental sync z kursorem — unikalny endpoint, nie ma go dla innych encji.

Przykład: utworzenie towaru z cenami

curl -X POST https://optima.twoja-firma.pl/api/towary/ \
  -H "X-Api-Key: <klucz>" \
  -H "X-Optima-Firma: FIRMA_GLOWNA" \
  -H "Content-Type: application/json" \
  -d '{
    "kod": "LAPTOP-LEN-X1",
    "nazwa": "Laptop Lenovo ThinkPad X1 Carbon",
    "nazwaFiskalna": "Laptop ThinkPad X1",
    "jm": "szt",
    "stawka": 23,
    "ean": "5901234567890",
    "grupa": "KOMPUTERY/LAPTOPY",
    "typ": 0,
    "produkt": 0,
    "numerKat": "20Y400ABPB",
    "wagaKG": 1.13,
    "url": "https://sklep.firma.pl/laptop-lenovo-thinkpad-x1",
    "opis": "Laptop biznesowy 14 cali, Intel Core i7, 16GB RAM, 512GB SSD",
    "ceny": [
      { "numer": 1, "wartoscNetto": 5900.00, "waluta": "PLN" },
      { "numer": 2, "wartoscNetto": 5500.00, "waluta": "PLN" }
    ]
  }'

Odpowiedź HTTP 201 zawiera pełny TowarDto — Optima nadaje id, weryfikuje stawkę VAT, waliduje unikalność kodu, przelicza ceny brutto na podstawie stawki.

Przykład: incremental sync

Twój system sklepu internetowego synchronizuje katalog co 15 minut. Pierwsze wywołanie pobiera wszystko, kolejne — tylko zmienione:

# Pierwsza synchronizacja (od początku)
curl "https://optima.../api/sync/towary?since=1970-01-01T00:00:00Z&limit=500" \
  -H "X-Api-Key: <klucz>" -H "X-Optima-Firma: FIRMA"

# Zwraca: { items: [...500...], cursor: "eyJpZCI6MTIzNDV9", hasMore: true }

# Kolejna strona
curl "https://optima.../api/sync/towary?cursor=eyJpZCI6MTIzNDV9"

# ... aż hasMore: false

# Potem — tylko zmiany od ostatniego sync
curl "https://optima.../api/sync/towary?since=2026-04-18T10:00:00Z"

Kursor zwraca się w odpowiedzi; używasz go zamiast offset dla kolejnej strony. To gwarantuje spójność nawet jeśli towary zmieniają się podczas iteracji (klasyczny problem z offset-based pagination w systemach live).

Przykład: stany magazynowe batch dla synchronizacji

Sklep internetowy ma 2000 aktywnych SKU i potrzebuje aktualizować dostępność co kilka minut:

curl -X POST https://optima.../api/towary/stany/batch/read \
  -H "Content-Type: application/json" \
  -d '{"kody": ["LAPTOP-LEN-X1", "LAPTOP-LEN-X2", ...] }'

Odpowiedź (max 500 pozycji na request, więc 2000 = 4 requesty):

{
  "items": [
    {
      "kod": "LAPTOP-LEN-X1",
      "stany": [
        {
          "magazynId": 1,
          "magazynSymbol": "GŁÓWNY",
          "magazynNazwa": "Magazyn główny",
          "czyAgregat": false,
          "ilosc": 15,
          "rezerwacje": 3,
          "braki": 0,
          "dostepne": 12,
          "zamowienia": 50
        },
        {
          "magazynId": null,
          "czyAgregat": true,
          "ilosc": 25,
          "dostepne": 22
        }
      ]
    }
  ]
}

Do sklepu wysyłasz dostepne (12 szt na magazyn główny, 22 szt agregat wszystkich magazynów), nie ilosc — inaczej pokażesz klientom produkty, których nie możesz zrealizować (bo są już zarezerwowane pod inne zamówienia).

Przykład: ceny per kontrahent (B2B)

Kluczowy klient ma negocjowaną cenę na laptopa — niżej niż standardowy cennik:

curl -X PUT https://optima.../api/towary/LAPTOP-LEN-X1/atrybuty/CENA_SPEC/kontrahenci \
  -H "Content-Type: application/json" \
  -d '{"kontrahentKod": "BIGCORP", "wartosc": "5200.00"}'

Warunek: atrybut CENA_SPEC musi być w Optimie zdefiniowany jako zależny od kontrahenta (Ogólne → Definicje atrybutów → flaga „zależny od kontrahenta”). Inaczej PUT zwróci 400.

Przy wystawianiu faktury dla BIGCORP Optima podstawia ten atrybut (jeśli Twoja integracja go używa przy wyliczaniu ceny). Standard to raczej cenniki (Cenniki API), ale atrybuty dają elastyczność dla specjalnych przypadków poza cennikiem.

Wydajność

• Pobieranie pojedyncze (GET): < 100 ms typowo
• Batch read 500 towarów: ~500 ms — 2 s (SQL-backed)
• Create pojedynczo: ~0,5 — 2 s (COM Save + walidacja)
• Create batch 100: ~5 — 20 s (jedna sesja COM, jeden Save)
• Sync z kursorem 500 rekordów: < 1 s (SQL przyrostowy)

Dla katalogów powyżej 10k SKU praktycznym wzorcem jest:

1. Initial full sync — /api/sync/towary + paginacja kursorem, ~2-5 min dla 50k SKU
2. Incremental sync — co 5-15 minut, pobiera 10-500 rekordów
3. Push-based stany — /api/towary/stany/batch/read co 1-5 minut dla aktywnych SKU, wypychanie do sklepu

Versync automatyzuje ten wzorzec out-of-the-box (konfigurujesz raz, działa w tle z retry, monitoring, alertami przy dryfie).

Kiedy towar, kiedy usługa

W CreateTowarRequest pole typ decyduje o zachowaniu:

• 0 (towar) — wpływa na stany magazynowe, wymaga magazynu, generuje WZ/PZ przy sprzedaży/zakupie
• 1 (usługa) — bez stanów, bez magazynu; faktura nie generuje dokumentu wydania
• 2 (produkt) — towar złożony z komponentów (receptura). Wymaga produkt=1 i zdefiniowanych składników osobno

Wybór typu ma konsekwencje księgowe (schematy dekretacji) i nie jest zmienialny po utworzeniu. Dla e-commerce sprzedającego fizyczne produkty = zawsze 0. Dla SaaS/usług fakturowanych = 1. Dla firm produkcyjnych z własną recepturą = 2.