Przejdź do treści

Przykłady WMS (Warehouse, Location, Inventory, InventoryDocument, PurchaseRequisition, ReturnDocument)

Przykłady zasobów z katalogu WMS: Warehouse i StorageLocation (jako Location), Inventory, InventoryDocument (jedyny zasób na ruch magazynowy: GR — goods receipt, GI — goods issue, przesunięcie, korekta), PurchaseRequisition, ReturnDocument. Standard modeli: Kamsoft.FAIR.

Konwencje wspólne: listy mają kopertę { "items": [...], "nextToken": null } i paginację count/offset; zapis odpowiada kodem 200. Przestrzeń identyfikatorów wewnętrznych to urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz><klucz> jest inny dla każdej kartoteki (lokalizacje, produkty, dokumenty, strony); rodzaj identyfikatora wynika z przestrzeni system. Zob. Identyfikacja i parametry wdrożenia.


1. Warehouse (magazyn) = Location

Magazyn to Location w profilu Warehouse (meta.profile, category = warehouse + rodzaj magazynu). Zob. Warehouse.

GET /v1/locations?profile=https://api-erp.kamsoft.pl/ns/StructureDefinition/Warehouse HTTP/1.1
Host: <base-url>
Authorization: Bearer <token>
Accept: application/json

Element items[]:

{
  "resourceType": "Location",
  "meta": {
    "lastModified": "2025-02-20T10:00:00",
    "profile": ["https://api-erp.kamsoft.pl/ns/StructureDefinition/Warehouse"]
  },
  "identifier": [
    { "system": "urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>", "value": "12" }
  ],
  "name": "Magazyn Główny (MG)",
  "type": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/location-type", "code": "warehouse", "display": "1" }] },
  "category": [
    { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/location-category", "code": "warehouse", "display": "Magazyn" }] },
    { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/location-category", "code": "1", "display": "magazyn leków" }] }
  ],
  "status": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/location-status", "code": "active", "display": "Aktywny" }] },
  "partOf": {
    "type": "Location",
    "identifier": { "system": "urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>", "value": "3" },
    "display": "Oddział Chirurgii (CHIR) [ID:3]"
  },
  "attribute": [
    { "code": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/location-attribute-type", "code": "warehouse-account-fk" }] }, "value": { "valueString": "330-01" } },
    { "code": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/location-attribute-type", "code": "is-accounting" }] }, "value": { "valueString": "1" } },
    { "code": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/location-attribute-type", "code": "zsmopl" }] }, "value": { "valueString": "0" } }
  ]
}

Kod warehouse w type nie jest dziś publikowany w słowniku location-type; display niesie typ magazynu ze źródła. partOf jest pojedynczą referencją (oddział, do którego przypisano magazyn); Location nie ma pola address.


2. StorageLocation (miejsce składowania) = Location

Apteka centralna i oddziały szpitalne to Location w profilu StorageLocation (category = storage-location); managingParty wskazuje jednostkę prowadzącą.

{
  "resourceType": "Location",
  "id": "3",
  "meta": { "profile": ["https://api-erp.kamsoft.pl/ns/StructureDefinition/StorageLocation"] },
  "identifier": [
    { "system": "urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>", "value": "3" }
  ],
  "name": "Oddział Chirurgii",
  "type": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/location-type", "code": "1", "display": "oddział szpitalny" }] },
  "category": [{ "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/location-category", "code": "storage-location", "display": "Miejsce składowania" }] }],
  "managingParty": { "type": "Party", "identifier": { "system": "urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>", "value": "7" } },
  "attribute": [
    { "code": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/location-attribute-type", "code": "organizational-unit-fk-account" }] }, "value": { "valueString": "501-02" } },
    { "code": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/location-attribute-type", "code": "location-symbol" }] }, "value": { "valueString": "CHIR" } }
  ]
}

Miejsce użytkowania środka trwałego (profil UsagePlace) opisują przykłady majątku.


3. Inventory (stan magazynowy)

product → ProductDefinition; location → Location; quantity – ilość z jednostką magazynu.

GET /v1/inventories?location=urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>|12&product=urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>|100 HTTP/1.1
Host: <base-url>
Authorization: Bearer <token>
Accept: application/json
{
  "items": [
    {
      "resourceType": "Inventory",
      "location": {
        "type": "Location",
        "identifier": { "system": "urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>", "value": "12" },
        "display": "Magazyn Główny"
      },
      "product": {
        "type": "ProductDefinition",
        "identifier": { "system": "urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>", "value": "100" }
      },
      "quantity": { "value": 150, "unit": "op.", "code": "5" }
    }
  ],
  "nextToken": null
}

Stan z partią lub numerem seryjnym różni się wyłącznie zawartością attribute[] (kody nadaje wdrożenie); product nadal wskazuje ProductDefinition.


4. InventoryDocument (dokument ruchu magazynowego)

InventoryDocument jest wyłącznym sposobem zapisu przyjęcia (GR) i wydania (GI) oraz przesunięć i korekt — endpoint /v1/inventory-documents. Parametr type jest wymagany i wybiera rodzaj dokumentu: receipt, issue-document, movement-document, issue-adjustment (system https://api-erp.kamsoft.pl/vs/warehouse/inventory-document-type).

movementType (system https://api-erp.kamsoft.pl/vs/warehouse/inventory-document-movement-type): receipt = GR, issue = GI, transfer, adjustment. Kierunek przez fromLocation / toLocation oraz quantity (delta: + przy receipt, − przy issue). Pozycja niesie product, quantity, lokalizacje, attribute[] i basedOn[] — nie ma pola valueReference.

4.1. GR — przyjęcie (type=receipt)

GET /v1/inventory-documents?type=https://api-erp.kamsoft.pl/vs/warehouse/inventory-document-type|receipt&issueDateFrom=2025-02-01&issueDateTo=2025-02-28 HTTP/1.1

Element items[]:

{
  "resourceType": "InventoryDocument",
  "meta": { "added": "2025-02-20" },
  "identifier": [
    { "system": "urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>", "value": "5501" },
    { "system": "urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>", "value": "PZ/2025/001" }
  ],
  "type": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/inventory-document-type", "code": "receiving-documents", "display": "Receiving Documents" }] },
  "movementType": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/inventory-movement-type", "code": "receipt", "display": "Receipt" }] },
  "effectiveDate": "2025-02-20",
  "participant": [
    { "type": "Party", "identifier": { "system": "urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>", "value": "301" } }
  ],
  "relatedDocument": [
    { "type": "Invoice", "identifier": { "system": "urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>", "value": "88012" } }
  ],
  "attribute": [
    { "code": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/inventory-document-attribute-type", "code": "order-number" }] }, "value": { "valueString": "ZAM/2025/17" } },
    { "code": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/inventory-document-attribute-type", "code": "total-gross" }] }, "value": { "valueMoney": { "value": 12345.67, "currency": "PLN" } } }
  ],
  "comment": "Dostawa leków"
}

Przyjęcia zwracają nagłówek dokumentu (dostawca w participant, faktura w relatedDocument); pozycje nie są dziś wypełniane. Kod receipt jest tu podawany w systemie …/vs/warehouse/inventory-movement-type (adres w rejestrze, słownik nieopublikowany).

4.2. GI — rozchód (type=issue-document)

GET /v1/inventory-documents?type=https://api-erp.kamsoft.pl/vs/warehouse/inventory-document-type|issue-document&fromLocation=urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>|3 HTTP/1.1
{
  "resourceType": "InventoryDocument",
  "identifier": [
    { "system": "urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>", "value": "70211" }
  ],
  "type": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/inventory-document-type", "code": "issue-document", "display": "Issue Document" }] },
  "movementType": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/inventory-document-movement-type", "code": "issue", "display": "rozchód" }] },
  "effectiveDate": "2025-02-21",
  "fromLocation": { "type": "Location", "identifier": { "system": "urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>", "value": "12" }, "display": "Magazyn Główny" },
  "participant": [
    { "type": "Location", "identifier": { "system": "urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>", "value": "3" }, "display": "Oddział Chirurgii" }
  ],
  "comment": "RW",
  "position": [
    {
      "identifier": [{ "system": "source-position-id", "value": "900123" }],
      "positionNo": 1,
      "product": { "type": "ProductDefinition", "identifier": { "system": "urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>", "value": "100" }, "display": "Paracetamol 500 mg tabl." },
      "quantity": { "value": -30, "unit": "op.", "system": "https://api-erp.kamsoft.pl/vs/warehouse/unit-of-measure", "code": "op." },
      "fromLocation": { "type": "Location", "identifier": { "system": "urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>", "value": "12" }, "display": "Magazyn Główny" },
      "toLocation": { "type": "Location", "identifier": { "system": "urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>", "value": "3" }, "display": "Oddział Chirurgii" },
      "attribute": [
        { "code": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/inventory-document-position-attribute-type", "code": "price" }] }, "value": { "valueString": "4.20" } },
        { "code": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/inventory-document-position-attribute-type", "code": "based-on-position" }] }, "value": { "valueString": "4411" } }
      ],
      "basedOn": [
        { "type": "PurchaseRequisitionPosition",
          "identifier": { "system": "source-purchase-requisition-position-id", "value": "4411" } }
      ]
    }
  ]
}

basedOn[0] wskazuje pozycję zapotrzebowania identyfikatorem nadanym po stronie magazynu (4411); zasób PurchaseRequisition nie publikuje tego identyfikatora w treści pozycji.

4.3. Przesunięcie (type=movement-document)

{
  "resourceType": "InventoryDocument",
  "identifier": [
    { "system": "urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>", "value": "70340" }
  ],
  "type": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/inventory-document-type", "code": "movement-document", "display": "Movement Document" }] },
  "movementType": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/inventory-document-movement-type", "code": "transfer", "display": "MM (Przychód/Rozchód)" }] },
  "effectiveDate": "2025-02-22",
  "fromLocation": { "type": "Location", "identifier": { "system": "urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>", "value": "12" }, "display": "Magazyn Główny" },
  "toLocation": { "type": "Location", "identifier": { "system": "urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>", "value": "15" }, "display": "Magazyn Materiałów" },
  "comment": "MM",
  "position": [
    {
      "positionNo": 1,
      "product": { "type": "ProductDefinition", "identifier": { "system": "urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>", "value": "100" } },
      "quantity": { "value": 20, "unit": "op.", "system": "https://api-erp.kamsoft.pl/vs/warehouse/unit-of-measure", "code": "op." },
      "fromLocation": { "type": "Location", "identifier": { "system": "urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>", "value": "12" } },
      "toLocation": { "type": "Location", "identifier": { "system": "urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>", "value": "15" } }
    }
  ]
}

4.4. Korekta rozchodu (type=issue-adjustment)

Korekta ilości na jednej lokalizacji; relatedDocument wskazuje dokument korygowany.

{
  "resourceType": "InventoryDocument",
  "identifier": [
    { "system": "urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>", "value": "70402" }
  ],
  "type": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/inventory-document-type", "code": "issue-adjustment", "display": "Issue Adjustment" }] },
  "movementType": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/inventory-document-movement-type", "code": "adjustment", "display": "korekta stanu" }] },
  "effectiveDate": "2025-02-23",
  "fromLocation": { "type": "Location", "identifier": { "system": "urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>", "value": "12" }, "display": "Magazyn Główny" },
  "relatedDocument": [
    { "type": "InventoryDocument", "identifier": { "system": "urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>", "value": "70211" }, "display": "RW" }
  ],
  "comment": "KRW",
  "position": [
    {
      "positionNo": 1,
      "product": { "type": "ProductDefinition", "identifier": { "system": "urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>", "value": "100" } },
      "quantity": { "value": 2, "unit": "op.", "system": "https://api-erp.kamsoft.pl/vs/warehouse/unit-of-measure", "code": "op." },
      "fromLocation": { "type": "Location", "identifier": { "system": "urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>", "value": "12" } }
    }
  ]
}

5. PurchaseRequisition (zapotrzebowanie)

5.1. Odczyt

GET /v1/purchase-requisitions?status=https://api-erp.kamsoft.pl/vs/warehouse/purchase-requisition-status|accepted HTTP/1.1

Element items[]:

{
  "resourceType": "PurchaseRequisition",
  "identifier": [{ "type": { "text": "Purchase Requisition ID" }, "system": "urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>", "value": "2201" }],
  "symbol": [{ "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/purchase-requisition-symbol", "code": "symbol", "display": "ZAP/CHIR/2025/31" }] }],
  "status": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/purchase-requisition-status", "code": "accepted", "display": "Przyjęte" }] },
  "warehouse": { "type": "Location", "identifier": { "system": "urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>", "value": "12" } },
  "owner": [{ "type": "Party", "identifier": { "system": "urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>", "value": "1" } }],
  "participant": [{ "type": "Party", "identifier": { "system": "urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>", "value": "7" } }],
  "issueDate": "2025-02-19T08:30:00",
  "expectedDate": "2025-02-21T00:00:00",
  "note": "Pilne",
  "position": [
    {
      "positionNo": 1,
      "product": { "type": "ProductDefinition", "identifier": { "system": "urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>", "value": "100" } },
      "quantity": { "value": 30, "unit": "op.", "code": "5" },
      "priority": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/purchase-requisition-position-priority", "code": "1", "display": "pilne" }] },
      "creationTime": "2025-02-19T08:30:00",
      "fulfilledQuantity": 30
    }
  ]
}

5.2. Zapis

POST /v1/purchase-requisitions HTTP/1.1
Content-Type: application/json

{
  "resourceType": "PurchaseRequisition",
  "identifier": [{ "system": "urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>", "value": "2202" }],
  "symbol": [{ "text": "ZAP/CHIR/2025/32" }],
  "warehouse": { "type": "Location", "identifier": { "system": "urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>", "value": "12" } },
  "owner": [{ "type": "Party", "identifier": { "system": "urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>", "value": "1" } }],
  "issueDate": "2025-02-20T09:00:00",
  "position": [
    {
      "positionNo": 1,
      "product": { "type": "ProductDefinition", "identifier": { "system": "urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>", "value": "100" } },
      "quantity": { "value": 10, "unit": "op.", "code": "5" },
      "description": "Paracetamol 500 mg tabl."
    }
  ]
}

Odpowiedź 200: { "items": [ <PurchaseRequisition zapisane w magazynie> ], "nextToken": null }.


6. ReturnDocument (zlecenie zwrotu)

POST /v1/return-documents HTTP/1.1
Content-Type: application/json

{
  "resourceType": "ReturnDocument",
  "identifier": [{ "system": "urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>" }],
  "symbol": { "text": "ZW/CHIR/2025/4" },
  "owner": [{ "type": "Party", "identifier": { "system": "urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>", "value": "1" } }],
  "participant": [
    { "type": "Location", "identifier": { "system": "urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>", "value": "3" } },
    { "type": "Party", "identifier": { "system": "urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>", "value": "7" } }
  ],
  "position": [
    {
      "positionNo": 1,
      "productDefinition": { "type": "ProductDefinition", "identifier": { "system": "urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>", "value": "100" }, "display": "Paracetamol 500 mg tabl." },
      "quantity": { "value": 5, "unit": "op." },
      "issueDocument": { "type": "InventoryDocument", "identifier": { "system": "urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>", "value": "70211" } },
      "issuePositionNo": 1
    }
  ]
}

Odpowiedź 200: { "items": [ <ReturnDocument zapisany w magazynie> ], "nextToken": null }. Magazyn przetwarza wyłącznie pierwszą pozycję. Przestrzeń identifier[].system wskazuje magazyn rejestrujący zwrot; pominięta, rozstrzyga profil. Wartość nadaje magazyn (rejestracja zasobu).


7. Diagramy zależności obiektów WMS

7.1. Zależności między zasobami (relacje referencyjne)

erDiagram
    Party ||--o{ Location : "managingParty"
    Location ||--o{ Location : "partOf"
    ProductDefinition ||--o{ Inventory : "product"
    Location ||--o{ Inventory : "location"
    Party ||--o{ InventoryDocument : "participant"
    Location ||--o{ InventoryDocument : "fromLocation toLocation participant"
    InventoryDocument ||--o{ InventoryDocumentPosition : "position"
    ProductDefinition ||--o{ InventoryDocumentPosition : "product"
    Location ||--o{ InventoryDocumentPosition : "fromLocation toLocation"
    PurchaseRequisition ||--o{ PurchaseRequisitionPosition : "position"
    InventoryDocumentPosition }o--o{ PurchaseRequisitionPosition : "basedOn"
    Location ||--o{ PurchaseRequisition : "warehouse"
    ReturnDocument ||--o{ ReturnDocumentPosition : "position"
    InventoryDocument ||--o{ ReturnDocumentPosition : "issueDocument"

    Location {
        string name
        Reference managingParty
        Reference partOf
        Attribute attribute
    }

    Inventory {
        Reference product
        Reference location
        Quantity quantity
    }

    InventoryDocument {
        CodeableConcept movementType
        string effectiveDate
        Reference participant
        Reference relatedDocument
    }

    InventoryDocumentPosition {
        Reference product
        Quantity quantity
        Reference fromLocation
        Reference toLocation
        Reference basedOn
    }

    ProductDefinition {
        string name
        Attribute attribute
    }

7.2. Hierarchia lokalizacji (magazyn → oddział)

flowchart TB
    O[Location: Oddział Chirurgii\nprofil StorageLocation]
    M1[Location: Magazyn Główny\nprofil Warehouse\npartOf → oddział]
    M2[Location: Magazyn Materiałów\nprofil Warehouse\npartOf → oddział]
    O --> M1
    O --> M2

7.3. Przepływ: zapotrzebowanie → rozchód → stan

flowchart LR
    PR["PurchaseRequisition\nposition #1"]
    ID["InventoryDocument (issue)\nposition #1 basedOn → PR #1"]
    INV["Inventory\nproduct + location + quantity"]
    PR -.->|"realizacja"| ID
    ID -.->|"aktualizuje"| INV

7.4. Podsumowanie: zasoby WMS i ich powiązania

Zasób Zależności (odniesienia) Użycie
Location (profil Warehouse) partOf → Location (oddział) Magazyn; fromLocation/toLocation nagłówka InventoryDocument; warehouse w PurchaseRequisition
Location (profil StorageLocation) managingParty → Party Apteka centralna, oddział; participant i lokalizacje pozycji InventoryDocument
Inventory product → ProductDefinition; location → Location Stan: co, gdzie, ile
ProductDefinition Katalog; product w Inventory i na pozycjach dokumentów
InventoryDocument movementType (receipt/issue/transfer/adjustment); participant; relatedDocument Jedyny zasób na ruch magazynowy
InventoryDocument.position[] product, quantity, fromLocation, toLocation, basedOn Wiersz GI / transfer / adjustment
PurchaseRequisition warehouse → Location; position[].product → ProductDefinition Zapotrzebowanie oddziału
ReturnDocument participant → Location/Party; position[].issueDocument → InventoryDocument Zlecenie zwrotu

Przykłady i diagramy zgodne z Resources: WMS/README, Location, WMS/Inventory, WMS/Warehouse, InventoryDocument, PurchaseRequisition, ReturnDocument.