Faktury sprzedaży w Comarch Optima przez REST API — endpointy, pola, pułapki

Co to jest faktura sprzedaży w Comarch Optima

Faktura sprzedaży (FS) to podstawowy dokument rejestrujący sprzedaż towaru lub usługi klientowi. W Optimie należy do modułu Handel i powstaje w sekcji Handel → Dokumenty → Faktury sprzedaży. Każda FS:

• zmniejsza stan magazynowy towarów (przez powiązany dokument WZ),
• wchodzi do rejestru VAT sprzedaży,
• generuje rozrachunek w module Kasa/Bank (należność od klienta),
• może być wysłana do KSeF.

Optima API ujednolica 7 typów dokumentów handlowo-magazynowych pod jednym wzorcem endpointów — różni się tylko prefiks ścieżki:

Dokumentacja pól i pułapek w większości jest wspólna — na tej stronie pokazujemy szczegóły dla FS, ale wzór ma zastosowanie dla pozostałych 6 typów.

Przykład: utworzenie faktury sprzedaży

Minimalny payload (jedna pozycja, automatyczna numeracja):

curl -X POST https://optima.twoja-firma.pl/api/dokumenty/faktury-sprzedazy/ \
  -H "X-Api-Key: <klucz>" \
  -H "X-Optima-Firma: FIRMA_GLOWNA" \
  -H "Content-Type: application/json" \
  -d '{
    "kontrahentKod": "ACME001",
    "dataDok": "2026-04-18",
    "dataSprzedazy": "2026-04-17",
    "magazynId": 1,
    "bufor": 1,
    "pozycje": [
      {
        "towarKod": "PROD-100",
        "ilosc": 2,
        "cenaNetto": 150.00,
        "stawkaVat": 23
      }
    ]
  }'

Odpowiedź HTTP 201:

{
  "id": 45821,
  "numerPelny": "FS/2026/04/100",
  "typDokumentu": 1,
  "dataDok": "2026-04-18T00:00:00",
  "dataSprzedazy": "2026-04-17T00:00:00",
  "podKod": "ACME001",
  "podNazwa1": "ACME Sp. z o.o.",
  "razemNetto": 300.00,
  "razemBrutto": 369.00,
  "razemVAT": 69.00,
  "waluta": "PLN",
  "bufor": 1,
  "anulowany": false,
  "pozycje": [
    {
      "lp": 1,
      "towarKod": "PROD-100",
      "towarNazwa": "Przykładowy produkt",
      "ilosc": 2.0000,
      "jm": "szt",
      "cenaNetto": 150.00,
      "wartoscNetto": 300.00,
      "wartoscBrutto": 369.00,
      "stawkaVat": 23.00,
      "rabat": 0
    }
  ],
  "atrybuty": []
}

Optima sama policzyła razemNetto, razemBrutto, razemVAT, nadała numerPelny, uzupełniła dane kontrahenta (podNazwa1) i nazwę towaru.

Przykład: faktura z KSeF i split payment

POST /api/dokumenty/faktury-sprzedazy/
{
  "kontrahentKod": "BIGFIRMA",
  "dataDok": "2026-04-18",
  "dataSprzedazy": "2026-04-18",
  "magazynId": 1,
  "formaPlatnosciId": 2,
  "termin": "2026-05-02",
  "splitPay": 1,
  "numerObcy": "ORDER-2026-04-12345",
  "bufor": 0,
  "pozycje": [
    { "towarKod": "USLUGA-IT", "ilosc": 10, "cenaNetto": 500.00, "stawkaVat": 23 }
  ]
}

Ustawienie bufor: 0 powoduje natychmiastowe zatwierdzenie dokumentu — Optima wygeneruje powiązany WZ, dekrety księgowe (jeśli definicja dokumentu ma schemat księgowy) i utworzy rozrachunek.

Przykład: partial update

Faktura jest w buforze, chcesz poprawić termin płatności i dodać uwagi:

curl -X PUT https://optima.twoja-firma.pl/api/dokumenty/faktury-sprzedazy/45821 \
  -H "X-Api-Key: <klucz>" \
  -H "X-Optima-Firma: FIRMA_GLOWNA" \
  -H "Content-Type: application/json" \
  -d '{
    "termin": "2026-05-15",
    "uwagi": "Klient prosił o wydłużony termin"
  }'

Pola pominięte = bez zmian. Jeśli faktura jest zatwierdzona (bufor=0), PUT zwróci 400.

Wydajność i architektura

Dokumenty handlowe nie mają endpointa POST /batch — w przeciwieństwie do kontrahentów, towarów czy cenników. Powód: każda FS wymaga osobnej sesji z pełną walidacją biznesową (VAT, KSeF, split pay, fiskalizacja), a batching nie daje istotnego zysku bo i tak każdy dokument wymaga osobnego zapisu.

W typowym wdrożeniu osiągasz 1–3 FS/sekundę. Dla większych wolumenów (e-commerce w szczycie, hurt) stosuje się:

• kolejki (RabbitMQ, Azure Service Bus, Redis Streams) — zamówienie ze sklepu wpada na kolejkę, worker tworzy FS w swoim tempie,
• Versync — silnik orkiestracji od WebArm, który obsługuje kolejkowanie, retry, monitoring, dead-letter queue i backpressure out-of-the-box.

Jeśli tworzysz integrację, która ma wolumen poniżej 1000 FS/dzień — wystarczy Optima API + synchroniczny POST po stronie aplikacji. Wyżej — idziesz w asynchroniczność.

Bezpieczeństwo danych

Każda operacja tworzenia/edycji FS przechodzi przez oficjalną warstwę biznesową Optimy, co oznacza:

• walidacja VAT — stawki, split payment, NIP kontrahenta, zgodność z JPK_V7,
• walidacja numeracji — zero duplikatów, zero luk, spójność z definicją dokumentu,
• spójność z pozostałymi modułami — Kasa/Bank, Księga Handlowa, JPK, rozrachunki — wszystko aktualizowane automatycznie,
• zachowanie gwarancji Comarcha — identycznie jakbyś zapisał dokument w oknie Optimy.

Dodatkowo po każdym POST/PUT endpoint robi weryfikację zapisu — czyta właśnie zapisany dokument i porównuje z requestem (sprawdza m.in. czy nazwy towarów w pozycjach się zgadzają). Jeśli coś się nie pokrywa — 400. Błąd lepszy niż cichy dryf.