Przejdź do treści

InventoryDocument

InventoryDocument (dokument ruchu magazynowego) to zasób reprezentujący zmianę stanu magazynowego: zmianę ilości, własności i/lub lokalizacji. Jeden dokument = jeden ruch (GR — goods receipt, GI — goods issue, przesunięcie, korekta) z nagłówkiem (movementType, effectiveDate, opcjonalnie fromLocation/toLocation na nagłówku) i pozycjami zagnieżdżonymi w position[] (§2a). Kierunek zmiany wynika z pól from/to i znaku quantity. Wzorowany na SAP (Material Document), Oracle (inventory transactions), D365 (InventMovement).

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

1. Zakres i zastosowanie

InventoryDocument = jeden dokument ruchu: movementType (CodeableConcept), effectiveDate (data obowiązywania), position[] (pozycje zagnieżdżone w dokumencie, §2a). Opcjonalnie na nagłówku: fromLocation, toLocation (gdy wspólne dla wszystkich pozycji), participant (magazyn lub miejsce składowania jako Location, dostawca/odbiorca jako Party), relatedDocument (faktura, dokument korygowany).

  • GR (goods receipt) — movementType = receipt; ilość na pozycji dodatnia. Dostawca w participant, faktura zakupu w relatedDocument.
  • GI (goods issue) — movementType = issue; pozycje z fromLocation; ilość na pozycji ujemna. Miejsce składowania odbiorcy w participant.
  • Przesunięcie — movementType = transfer; pozycje z fromLocation i toLocation.
  • Korekta — movementType = adjustment; pozycje z jedną lokalizacją i quantity (delta); dokument korygowany w relatedDocument.

Relacja do DocumentReference: Ruch magazynowy (GR/GI itd.) jest wyłącznie InventoryDocument. DocumentReference nie modeluje przyjęć ani wydań.

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 dokumentu ruchu: id dokumentu (rozchody, przesunięcia, korekty) albo id i numer przyjęcia — osobne przestrzenie wdrożeniowe, system z NamingSystem
movementType 0..1 CodeableConcept receipt, issue, transfer, adjustment — system https://api-erp.kamsoft.pl/vs/warehouse/inventory-document-movement-type
effectiveDate 0..1 date Data obowiązywania ruchu (dzień przyjęcia/wydania/przesunięcia)
fromLocation 0..1 Reference(Location) Magazyn źródłowy (gdy wspólny dla wszystkich pozycji)
toLocation 0..1 Reference(Location) Magazyn docelowy (gdy wspólny dla wszystkich pozycji)
participant 0..* Reference(Location / Party) Uczestnicy: miejsca składowania (Reference do Location), dostawca (Reference do Party)
relatedDocument 0..* Reference(Invoice / InventoryDocument) Powiązane dokumenty: faktura zakupu przy przyjęciu, dokument korygowany przy korekcie
position 0..* struktura pozycji (§2a) Pozycje ruchu zagnieżdżone w dokumencie

Schemat nie wymaga żadnego pola. type (z DomainResource) niesie rodzaj dokumentu w systemie https://api-erp.kamsoft.pl/vs/warehouse/inventory-document-type; API emituje kody receiving-documents, issue-document, movement-document, issue-adjustment, których opublikowany słownik dziś nie zawiera (publikuje m.in. receipt, issue, movement). comment niesie symbol dokumentu ze źródła. status nie jest dziś wypełniany; filtr status używa systemu https://api-erp.kamsoft.pl/vs/warehouse/inventory-document-status.

Słownik inventory-document-movement-type publikuje też kody production, reservation, queue, proforma, collective, inventory-diff; API emituje wyłącznie cztery wymienione w tabeli. Dokumenty przyjęcia (type=receipt) niosą kod receipt w systemie https://api-erp.kamsoft.pl/vs/warehouse/inventory-movement-type (adres w rejestrze, słownik nieopublikowany).

2a. Pozycja (position[], struktura zagnieżdżona)

Pozycje są częścią dokumentu: nie mają własnego endpointu ani tożsamości poza dokumentem. Pozycja rozszerza DomainResource (ma m.in. status, attribute).

Nazwa Kard. Typ Opis
identifier 0..* Identifier Identyfikator pozycji nadany przez magazyn: system = source-position-id
positionNo 0..1 integer Numer pozycji w dokumencie (od 1)
product 0..1 Reference(ProductDefinition) Produkt
quantity 0..1 Quantity Delta ilości (value ze znakiem: + receipt, − issue; unit/code = jednostka miary magazynu, system https://api-erp.kamsoft.pl/vs/warehouse/unit-of-measure)
fromLocation 0..1 Reference(Location) Lokalizacja źródłowa (miejsce składowania lub magazyn)
toLocation 0..1 Reference(Location) Lokalizacja docelowa
basedOn 0..* Reference Realizowane pozycje zapotrzebowań (§2b)

status pozycji wg słownika inventory-document-position-status (buffer, not-buffer); dziś nie jest wypełniany. attribute[] pozycji (system https://api-erp.kamsoft.pl/vs/warehouse/inventory-document-position-attribute-type, adres w rejestrze, słownik nieopublikowany) niesie m.in. from-location-id, to-location-id, price, price-gross, value, value-gross, tax-rate, based-on-position.

2b. Powiązanie z zapotrzebowaniem (basedOn)

basedOn[] wskazuje pozycje PurchaseRequisition realizowane przez pozycję rozchodu: Reference.type = PurchaseRequisitionPosition, Reference.identifier = { "system": "source-purchase-requisition-position-id", "value": "<id pozycji>" }. Wartość to identyfikator pozycji zapotrzebowania nadany po stronie magazynu; zasób PurchaseRequisition nie publikuje go w treści pozycji, więc dopasowanie wymaga wiedzy o identyfikatorach źródłowych. Kierunek powiązania jest jeden: realizacja → żądanie. Nie ma parametru wyszukiwania po basedOn.

3. Operacje

Metoda Ścieżka Opis
GET /v1/inventory-documents?type=… Lista dokumentów ruchu wybranego rodzaju
POST /v1/inventory-documents?type=…\|intents Rejestracja nagłówka zapotrzebowania (tor przejściowy; docelowo POST /v1/purchase-requisitions)

3.1. GET /v1/inventory-documents

Parametr Format Opis
type system\|value (wymagany) system = https://api-erp.kamsoft.pl/vs/warehouse/inventory-document-type; value ∈ receipt, issue-document, movement-document, issue-adjustment. Wartość intents zwraca 400 (przeniesione do /v1/purchase-requisitions)
identifier system\|value Identyfikator dokumentu w przestrzeni urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>
owner system\|value Firma (przestrzeń identyfikatora strony)
attribute code\|value (wiele) Filtry źródłowe, m.in. warehouse-id, organization-unit-integration-id (tylko receipt)
status system\|value System https://api-erp.kamsoft.pl/vs/warehouse/inventory-document-status (tylko receipt)
fromLocation, participant system\|value Miejsce składowania źródłowe / uczestniczące (rozchody, przesunięcia, korekty)
issueDateFrom, issueDateTo date Zakres dat wystawienia
count, offset integer Paginacja (domyślnie 20 / 0)

Odpowiedź 200: { "items": [InventoryDocument…], "nextToken": null }.

3.2. POST /v1/inventory-documents

Obsługiwany jest wyłącznie type=<system>|intents; inne wartości zwracają 501. Dane przekazuje się w parametrach zapytania, nie w treści:

Parametr Opis
identifier system\|value — identyfikator nagłówka zapotrzebowania nadawany przez nadawcę (wymagany; przestrzeń system wskazuje wtedy instalację rejestrującą nagłówek, rejestracja zasobu)
attribute symbol\|<symbol jednostki> (wymagany), warehouse-id\|<id> (wymagany), mpk-code\|…, document-symbol\|…, employee-integration-id\|…
owner, description, realizationDate, creationDate, status opcjonalne

Odpowiedź 200 z listą utworzonych nagłówków PurchaseRequisition (bez koperty items).

4. Zgodność z systemami ERP

System Odpowiednik Uwagi
SAP Material Document (MIGO), Movement Type (101, 201, 301) Dokument = ruch; movement type definiuje efekt (+/- qty, z/do lokacji).
Oracle MTL_MATERIAL_TRANSACTIONS, transaction_type_id Transakcja = zmiana stanu; typ = receipt, issue, transfer.
D365 InventMovement, WHS – movement type Ruch z typem; from/to location, quantity.
Workday Inventory adjustment / transfer Operacja na stanie z kierunkiem zmiany.

Model kanoniczny: InventoryDocument z movementType i position[] (fromLocation, toLocation, quantity jako delta) pokrywa dokument ruchu w SAP, Oracle, D365.

5. Odniesienia