Comarch Optima faktury API: jak zdalnie wystawić fakturę i jak wystawić fakturę sprzedaży

Co to jest faktura sprzedaży w Comarch ERP Optima

Faktura sprzedaży (FS) to podstawowy dokument rejestrujący sprzedaż towaru lub usługi klientowi. W programie Comarch ERP Optima 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 od WebArm ujednolica 7 typów dokumentów handlowych i magazynowych pod jednym wzorcem endpointów. W systemie Comarch ERP Optima odpowiadają im różne rodzaje dokumentów, ale integracja REST pracuje według tego samego modelu — 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. Jeśli faktura powstaje z zamówienia sklepowego, zwykle potrzebujesz też kartoteki kontrahentów w Comarch Optima API, danych z towarów i stanów magazynowych oraz procesu opisanego w przewodniku automatyczne zamówienia ze sklepu do Optimy.

Jak zdalnie wystawić fakturę z Comarch Optima przez API

Zdalne wystawienie faktury z Comarch Optima wymaga warstwy pośredniej, która przyjmie żądanie HTTP, wywoła oficjalną logikę programu i zwróci numer dokumentu. Optima API od WebArm robi to przez POST /api/dokumenty/faktury-sprzedazy/: system sprzedażowy, sklep albo agent AI wysyła JSON, a Comarch ERP Optima nadaje numer, liczy VAT i zapisuje dokument. Tak możesz wystawić fakturę sprzedaży bez ręcznego przepisywania danych do okna programu.

Ten scenariusz jest przydatny, gdy faktura ma powstać bez pracy operatora w oknie Optimy: po zamówieniu w sklepie, po akceptacji płatności, po imporcie sprzedaży z POS albo po zatwierdzeniu usługi w CRM. Jeśli proces uruchamia integracja API, użytkownik nie musi ręcznie pracować w oknie Optimy. Kluczowe jest to, że zapis nie omija logiki programu. API przekazuje operację przez warstwę biznesową Comarch ERP Optima, więc numeracja, rejestr VAT, split payment, kontrahent i magazyn są walidowane tak samo jak przy ręcznym wystawieniu FS.

Najkrótsza ścieżka wygląda tak: aplikacja zewnętrzna ustala kontrahenta, pozycje, formę płatności i magazyn, a automatyzacja usprawnia powtarzalne wystawianie dokumentów; potem wysyła POST /api/dokumenty/faktury-sprzedazy/, a program Comarch ERP Optima zwraca utworzony dokument z numerem, wartościami netto/brutto i statusem bufora.

Jakie dane są potrzebne do wystawienia faktury

Comarch Optima faktury API nie działa jak prosty zapis do tabeli. To wywołanie Web API, które przekazuje dane do programu Comarch ERP Optima i pozwala mu wykonać walidację dokumentu, płatności, towarów, VAT oraz magazynu. Dlatego request powinien zawierać nie tylko pozycje faktury, ale też dane nabywcy, dane odbiorcy, data wystawienia, data płatności i wartości, które mają zostać przeliczone przez system.

Jeżeli wystawienie faktury ma być częścią większego procesu, VerSync może kolejkować żądania, ponawiać błędy i pilnować, aby faktury, płatności oraz statusy sklepu nie rozjechały się między systemami.

Fakturowanie, KSeF i potwierdzenie wystawienia

Fakturowanie przez API powinno być traktowane jako procedura zapisu dokumentów w systemie Comarch ERP Optima, a nie jako proste generowanie pliku. To element szerszej procedury przygotowania firmy do obsługi KSeF i wyjątków procesowych związanych z modułem Faktury. Jeżeli bufor: 0 przejdzie walidację, nowa faktura zostaje zatwierdzona w programie Optima, powstaje rozrachunek, a faktura została wystawiona zgodnie z konfiguracji firmy i definicją dokumentu.

W praktyce proces wystawiania ma kilka punktów kontrolnych:

• przed zapisem sprawdź dane nabywcy, dane odbiorcy, pozycje, numer rachunku i formę płatności,
• przy zatwierdzeniu dokumentu sprawdź, czy faktura sprzedaży wygenerowała powiązania magazynowe oraz należności,
• po wysyłce do Krajowego Systemu e Faktur zapisz numer z systemu KSeF i UPO w dokumencie, a samą wysyłkę oraz status obsługi przez zewnętrzny system monitoruj niezależnie,
• jeżeli inny system robi wizualizację faktury, kod QR lub wydruku, traktuj te elementy jako warstwę prezentacji, a nie jako źródło prawdy dla Comarch ERP,
• przy korekty dokumentu nie edytuj zatwierdzonej FS, tylko obsłuż korektę jako osobny dokument w systemie Comarch ERP Optima.

Dzięki temu można wystawiać faktury sprzedaży automatycznie, ale nadal zachować kontrolę nad tym, co faktycznie zostało zapisane w systemie.

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": []
}

Comarch ERP Optima sama policzyła razemNetto, razemBrutto, razemVAT, nadała numerPelny, uzupełniła dane kontrahenta (podNazwa1) i nazwę towaru. W praktyce właśnie tu widać różnicę między bezpiecznym Web API a zapisem bezpośrednio do bazy danych: program sam sprawdza dokument, a nie tylko przyjmuje rekord. Jeśli integracja ma wystawić fakturę sprzedaży z zamówienia, odpowiedź z API jest potwierdzeniem, że dokument został zapisany w systemie Comarch ERP Optima.

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 — Comarch ERP Optima wygeneruje powiązany WZ, dekrety księgowe (jeśli definicja dokumentu ma schemat księgowy) i utworzy rozrachunek. Etap późniejszego wysyłania do KSeF może być obsługiwany poza API wystawiającym fakturę. Wysyłka do Krajowego Systemu e-Faktur może zostać wykonana później; po pobraniu UPO numer KSeF zapisujesz na fakturze przez PUT.

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. To ograniczenie jest celowe: po zatwierdzeniu dokumentu księgowego lepsza jest korekta niż cicha modyfikacja historii.

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ą w programie Comarch ERP Optima (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 od WebArm — silnik orkiestracji, 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 od WebArm + synchroniczny POST po stronie aplikacji. Wyżej — idziesz w asynchroniczność z VerSync, bo wtedy łatwiej kontrolować cały proces, statusy, płatności i ponowienia po błędach.

Bezpieczeństwo danych

Każda operacja tworzenia/edycji FS przechodzi przez oficjalną warstwę biznesową Comarch ERP Optima, 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 serwer Optima API od WebArm 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.