Przejdź do treści

SalesOrder

SalesOrder (zamówienie odbiorcy) to zasób reprezentujący zamówienie złożone przez odbiorcę na dostarczenie towarów lub usług. Zawiera identyfikatory, rodzaj (oferta / zamówienie), datę wystawienia, odbiorcę, pozycje zamówienia, wartość oraz status realizacji. Jest dokumentem źródłowym dla wydania magazynowego (InventoryDocument, movementType = issue) i faktury dla odbiorcy (Invoice). Identyfikacja przez Identifier, odbiorca przez PartyRole, pozycje przez strukturę zagnieżdżoną. Wzorowany na SAP (Sales Order, SO), UBL 2.3 (Order). Odpowiednik po stronie sprzedaży dla PurchaseOrder.

Rozszerza DomainResource. Zasób w standardzie Kamsoft.FAIR (Fast Adaptive Interoperable Resources).

1. Zakres i zastosowanie

SalesOrder = jeden dokument handlowy reprezentujący zamówienie od odbiorcy. Status realizacji nagłówka i pozycji oraz ilość zrealizowaną nadaje system prowadzący — API udostępnia je wyłącznie do odczytu.

Typowe scenariusze:

  • przekazanie zamówienia odbiorcy z systemu zewnętrznego (sklep internetowy, system odbiorcy, CRM) do systemu prowadzącego,
  • przekazanie oferty (type = offer), która po akceptacji staje się zamówieniem,
  • korekta danych nagłówka lub pozycji przed realizacją (ilość, cena, termin dostawy),
  • śledzenie statusu realizacji zamówienia i stopnia realizacji pozycji (position[].fulfilledQuantity).

2. Zawartość (struktura)

Oprócz elementów DomainResource (id, resourceType, meta, owner[], comment, category[], status, type, contained[], attribute[]):

Nazwa Kard. Typ Opis
identifier 0..* Identifier Identyfikatory zamówienia — §2a
issueDate 0..1 date Data wystawienia zamówienia
party 0..* Reference(PartyRole) Strony zamówienia: odbiorca (profil CustomerRole, role = customer); w POST wymagany
position 0..* SalesOrderPosition (§2b) Pozycje zamówienia (towar, ilość, cena)
amount 0..1 Money Kwota zamówienia (w odczycie wartość brutto)
expectedDeliveryDate 0..1 date Oczekiwana data dostawy
relatedDocument 0..* Reference(InventoryDocument/Invoice) Powiązane dokumenty — wydania magazynowe (movementType = issue) realizujące zamówienie/faktury; tylko do odczytu

Pola dziedziczone istotne dla zamówienia:

Nazwa Kard. Typ Opis
type 0..1 CodeableConcept Rodzaj dokumentu; słownik wholesale/sales-order-type (offer oferta, order zamówienie); w POST wymagany
status 0..1 CodeableConcept Status realizacji zamówienia; słownik wholesale/sales-order-status (open otwarte, not-fulfilled niezrealizowane, part-fulfilled częściowo zrealizowane, fulfilled zrealizowane). Tylko do odczytu
attribute 0..* Attribute code + value[]; system wholesale/sales-order-attribute-type: warehouse (valueReference → Location, magazyn / oddział realizujący zamówienie)
owner 0..* Reference(Party) Firma prowadząca zamówienie (NIP, system https://gov.pl/nip)
meta 0..1 Meta added (utworzenie), lastModified (modyfikacja), profile w zapisie

2a. Identyfikatory

Rodzaj identyfikatora niesie Identifier.system — przestrzeń instalacji urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz> publikowana jako NamingSystem — zob. Identyfikacja i parametry wdrożenia.

Przestrzeń (klucz) Znaczenie Klucz referencyjny Skąd system
SalesOrder.Id Id zamówienia odbiorcy; używany w parametrze identifier operacji GET i PATCH tak NamingSystem; urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>
SalesOrder.Number Numer zamówienia (np. ZO/2026/001) nie NamingSystem; urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>.1

2b. SalesOrderPosition

Pozycja zamówienia odbiorcy (referencja na produkt, ilość, cena). Pozycje są częścią zamówienia: nie mają własnego endpointu; w zapisie pozycję wskazuje positionNo.

Nazwa Kard. Typ Opis
positionNo 0..1 integer Numer pozycji (od 1), unikalny w zamówieniu; w PATCH wskazuje pozycję do zmiany
product 0..1 Reference(ProductDefinition) Produkt/usługa (identifier w przestrzeni ProductDefinition.Id); brak, gdy pozycja nie wskazuje asortymentu
name 0..1 string Nazwa pozycji
description 0..1 string Opis pozycji
quantity 0..1 Quantity Ilość zamówiona (unit = nazwa jednostki)
fulfilledQuantity 0..1 Quantity Ilość zrealizowana, może być częściowa. Tylko do odczytu
unitPrice 0..1 Money Cena jednostkowa netto (currency = waluta zamówienia)
amount 0..1 Money Wartość pozycji (w odczycie brutto, a gdy brak — netto × ilość)
vatRate 0..1 CodeableConcept Stawka podatku VAT; słownik vat-rate
status 0..1 CodeableConcept Status realizacji pozycji; słownik wholesale/sales-order-position-status (kody jak w statusie nagłówka). Tylko do odczytu
deliverySchedule 0..* DeliveryScheduleLine (date, quantity) Harmonogram dostaw
meta 0..1 Meta Metadane pozycji (added, lastModified)

3. Operacje i parametry wyszukiwania

Metoda Ścieżka Opis
GET /v1/sales-orders Wyszukiwanie zamówień odbiorców
POST /v1/sales-orders Utworzenie zamówienia (nagłówek z pozycjami)
PATCH /v1/sales-orders?identifier=system\|value Zmiana nagłówka i pozycji zamówienia

Zgodnie z konwencjami technicznymi nie ma tras z {id} ani osobnych tras dla pozycji: zamówienie wskazuje parametr identifier, a pozycje są częścią treści zasobu.

3.1. Błędy

Błędny format parametru lub niepoprawna treść zapisu → 400 Problem Details (type = http://hl7.org/fhir/issue-type#invalid); przestrzeń identyfikatora spoza miejsca prawdy profilu → 404.

4. Zgodność z systemami ERP

System Odpowiednik Uwagi
SAP Sales Order (SO), tbl. VBAK (header) + VBAP (position) SalesOrder = struktura VBAK/VBAP; status realizacji ≈ VBUK/VBUP
UBL 2.3 Order Wspólna struktura buyer, seller, lines
D365 Sales Order, tbl. SalesTable (header) + SalesLine (lines) Header + lines

5. Odniesienia