Przykładowe dokumenty (DocumentReference)

Poniżej po jednym przykładowym dokumencie dla każdego profilu DocumentReference: HrInboxDocument (dokument w skrzynce kadrowej) i WarehouseDocument (dokument magazynowy poza GR/GI), zbudowanym z obiektów DocumentReference, DocumentPosition i ValueItem. GR i GI — wyłącznie InventoryDocument (zob. WMS-Examples). Zapis w JSON; wartości przykładowe.

W przykładach używane są wyłącznie pola rdzenia DocumentReference: identifier, space, issueDate, participant, basedOn, position, attachment oraz pola DomainResource (category, type, status, attribute). Pozycja (position[]) ma positionNo, code, value[] (lista ValueItem z type i jednym z valueQuantity, valueMoney, valueString, valueInteger, valueBoolean, valueCodeableConcept, valueReference), status, attachment. Nie ma pól statusDate, expectedDate, realizationDate — daty poza issueDate przenosi attribute[].

Profil: zapis (POST, PATCH) wymaga profilu — meta.profile z adresem HrInboxDocument lub WarehouseDocument albo category z kodem hr-inbox-document / warehouse-document; bez tego 400. Słowniki: warianty domenowe hr/document-category, hr/document-space, hr/document-status, hr/document-attribute-type, warehouse/document-type, warehouse/document-status, warehouse/document-position-type, warehouse/value-item-type, warehouse/invoice-position-vat-rate, warehouse/document-attribute-type — Systemy kodowania.

Legenda placeholderów (zob. konwencje przykładów): urn:oid:2.999.1 — id dokumentu w skrzynce kadrowej (inbox-document-id), urn:oid:2.999.2 — id pracownika (employee-id), urn:oid:2.999.3 — id dokumentu magazynowego (document-id), urn:oid:2.999.4 — id kontrahenta w magazynie (contractor-id), urn:oid:2.999.5 — id produktu (product-id).

---

1. Kadry – dokument w skrzynce kadrowej (profil HrInboxDocument)

{
  "resourceType": "DocumentReference",
  "id": "4711",
  "meta": {
    "lastModified": "2025-02-17T16:00:00Z",
    "profile": ["https://api-erp.kamsoft.pl/ns/StructureDefinition/HrInboxDocument"]
  },
  "category": [
    { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/hr/document-category", "code": "hr-inbox-document", "display": "Dokument skrzynki HR" }] }
  ],
  "space": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/hr/document-space", "code": "hr-inbox", "display": "Skrzynka HR" }] },
  "identifier": [
    { "system": "urn:oid:2.999.1", "value": "4711" }
  ],
  "type": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/hr-inbox-document-type", "code": "<kod z instalacji>", "display": "Zaświadczenie" }] },
  "status": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/hr/document-status", "code": "received", "display": "Przyjęty" }] },
  "issueDate": "2025-02-17",
  "participant": [
    {
      "type": "Party",
      "identifier": { "system": "urn:oid:2.999.2", "value": "1001" },
      "display": "Jan Kowalski"
    }
  ],
  "attribute": [
    {
      "code": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/hr/document-attribute-type", "code": "external-system-name" }] },
      "value": { "valueString": "System medycyny pracy" }
    },
    {
      "code": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/hr/document-attribute-type", "code": "external-document-id" }] },
      "value": { "valueString": "MP/2025/000123" }
    },
    {
      "code": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/hr/document-attribute-type", "code": "receive-operation-comment" }] },
      "value": { "valueString": "Przekazano automatycznie" }
    }
  ],
  "attachment": [
    {
      "resourceType": "Attachment",
      "contentType": "application/pdf",
      "title": "zaswiadczenie.pdf",
      "data": "<base64>"
    }
  ]
}

Uwaga: type pochodzi ze słownika wdrożeniowego hr-inbox-document-type — kody pobiera się z GET /v1/value-sets?url=https://api-erp.kamsoft.pl/vs/hr-inbox-document-type. Dokument kadrowy nie ma pozycji; treść niesie attachment[], a dane operacyjne attribute[]. Zapis: POST /v1/document-references z treścią jak wyżej, bez id i bez value w identyfikatorze wewnętrznym — sama przestrzeń ({ "system": "urn:oid:2.999.1" }) wskazuje skrzynkę rejestrującą dokument (pominięta — rozstrzyga profil), a wartość nadaje skrzynka kadrowa (rejestracja zasobu); odpowiedź 200 z komunikatem systemu kadrowego. Odczyt: GET /v1/document-references?profile=https://api-erp.kamsoft.pl/ns/StructureDefinition/HrInboxDocument&participant=urn:oid:2.999.2|1001.

---

2. Magazyn – dokument zamówienia (profil WarehouseDocument)

{
  "resourceType": "DocumentReference",
  "id": "88",
  "meta": {
    "lastModified": "2025-02-19T14:30:00Z",
    "profile": ["https://api-erp.kamsoft.pl/ns/StructureDefinition/WarehouseDocument"]
  },
  "category": [
    { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/document-category", "code": "warehouse-document", "display": "Dokument magazynowy" }] }
  ],
  "identifier": [
    { "system": "urn:oid:2.999.3", "value": "88" }
  ],
  "type": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/document-type", "code": "6", "display": "dokument zamówienia" }] },
  "status": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/document-status", "code": "buffer", "display": "W buforze" }] },
  "issueDate": "2025-02-19",
  "participant": [
    {
      "type": "Party",
      "identifier": { "system": "urn:oid:2.999.4", "value": "15" },
      "display": "Dostawca XYZ"
    }
  ],
  "position": [
    {
      "positionNo": 1,
      "code": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/document-position-type", "code": "order-line", "display": "Pozycja zamówienia" }] },
      "status": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/document-position-status", "code": "buffer", "display": "w buforze" }] },
      "value": [
        { "valueReference": { "type": "ProductDefinition", "identifier": { "system": "urn:oid:2.999.5", "value": "10045" }, "display": "Produkt A" } },
        { "type": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/value-item-type", "code": "net-value", "display": "Wartość netto" }] }, "valueMoney": { "value": 1000, "currency": "PLN" } },
        { "type": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/value-item-type", "code": "vat-rate", "display": "Stawka VAT" }] }, "valueCodeableConcept": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/invoice-position-vat-rate", "code": "23" }] } },
        { "type": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/value-item-type", "code": "tax-value", "display": "Wartość VAT" }] }, "valueMoney": { "value": 230, "currency": "PLN" } },
        { "type": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/value-item-type", "code": "gross-value", "display": "Wartość brutto" }] }, "valueMoney": { "value": 1230, "currency": "PLN" } }
      ]
    },
    {
      "positionNo": 2,
      "code": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/document-position-type", "code": "vat-summary-line", "display": "Podsumowanie VAT" }] },
      "value": [
        { "type": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/value-item-type", "code": "vat-rate" }] }, "valueCodeableConcept": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/invoice-position-vat-rate", "code": "23" }] } },
        { "type": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/value-item-type", "code": "net-value" }] }, "valueMoney": { "value": 1000, "currency": "PLN" } },
        { "type": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/value-item-type", "code": "tax-value" }] }, "valueMoney": { "value": 230, "currency": "PLN" } }
      ]
    }
  ],
  "attribute": [
    { "code": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/document-attribute-type", "code": "total-net", "display": "Suma netto" }] }, "value": { "valueMoney": { "value": 1000, "currency": "PLN" } } },
    { "code": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/document-attribute-type", "code": "total-vat", "display": "Suma VAT" }] }, "value": { "valueMoney": { "value": 230, "currency": "PLN" } } },
    { "code": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/document-attribute-type", "code": "total-gross", "display": "Suma brutto" }] }, "value": { "valueMoney": { "value": 1230, "currency": "PLN" } } }
  ]
}

Uwaga: Pozycja i podsumowanie VAT są w position[]; każda wartość to element value[] (ValueItem) z type ze słownika warehouse/value-item-type i jedną z wartości value*. Podsumowanie dokumentu (suma netto, VAT, brutto) jest w attribute[] (warehouse/document-attribute-type). Kod warehouse-document rozpoznaje profil; wersja 1.0.0 pliku warehouse/document-category jeszcze go nie publikuje. Dekretacja faktury w API.ERP: wyłącznie PostingInstruction (postingLine[]) + Invoice, nie przez DocumentReference.

2a. Zmiana statusu dokumentu magazynowego (PATCH)

PATCH /v1/document-references przyjmuje zasób z profilem WarehouseDocument; cel wskazuje identifier[] w treści, a zmianę niesie status:

{
  "resourceType": "DocumentReference",
  "meta": { "profile": ["https://api-erp.kamsoft.pl/ns/StructureDefinition/WarehouseDocument"] },
  "identifier": [{ "system": "urn:oid:2.999.3", "value": "88" }],
  "type": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/document-type", "code": "6" }] },
  "status": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/document-status", "code": "not-buffer", "display": "Przyjęty" }] }
}

Odpowiedź 200 z kopertą { "items": [ … ] } zawierającą wynik operacji po stronie systemu magazynowego.

---

3. Magazyn — przyjęcie i wydanie (GR / GI)

Przyjęcie (GR, goods receipt) i wydanie (GI, goods issue) nie są modelowane jako DocumentReference. Wyłączny zasób: InventoryDocument z movementType receipt lub issue, endpoint /v1/inventory-documents. Pełne przykłady JSON: WMS-Examples — § 7 (w tym #gr-receipt-example i #gi-issue-example).

---

4. Diagramy zależności obiektów DocumentReference

4.1. Struktura DocumentReference, DocumentPosition i ValueItem

erDiagram
    DocumentReference ||--o{ DocumentPosition : "position"
    DocumentReference }o--o{ Party : "participant"
    DocumentReference }o--o{ Attribute : "attribute"
    DocumentReference }o--o{ Attachment : "attachment"
    DocumentReference }o--o{ DocumentReference : "basedOn"
    DocumentPosition ||--o{ ValueItem : "value"
    ValueItem }o--o| ProductDefinition : "valueReference"

    DocumentReference {
        string id
        CodeableConcept category
        CodeableConcept type
        CodeableConcept status
        CodeableConcept space
        date issueDate
        Reference participant
        Reference basedOn
    }

    DocumentPosition {
        integer positionNo
        CodeableConcept code
        CodeableConcept status
        ValueItem value
        Attachment attachment
    }

    ValueItem {
        CodeableConcept type
        Quantity valueQuantity
        Money valueMoney
        string valueString
        CodeableConcept valueCodeableConcept
        Reference valueReference
    }

4.2. Profile i typy dokumentów

flowchart TB
    subgraph DR["DocumentReference"]
        D[identifier, category, type, status, issueDate, participant]
    end

    D --> HR[HrInboxDocument: dokument w skrzynce kadrowej\ntype z hr-inbox-document-type]
    D --> WHS[WarehouseDocument: zamówienie, zapotrzebowanie, komis\ntype z warehouse/document-type]
    WHS -.->|GR/GI/MM| INV[InventoryDocument]

4.3. Position (code) a value[] w zależności od profilu

flowchart LR
    subgraph WHS_pos["WarehouseDocument: order-line, vat-summary-line"]
        C1[value: valueReference → ProductDefinition\nvalue-item-type: net-value, vat-rate, tax-value, gross-value\nattribute: total-net, total-vat, total-gross]
    end

    subgraph INV_pos["InventoryDocument: GR/GI (nie DocumentReference)"]
        C2[InventoryDocumentPosition:\nproduct, quantity, from/to Location]
    end

    subgraph HR_pos["HrInboxDocument: bez pozycji"]
        C3[attachment: treść dokumentu\nattribute: external-system-name, external-document-id]
    end

---

Podsumowanie

Profil	Typ dokumentu (type)	Position (code)	Wykorzystane pola DocumentPosition / attribute
HrInboxDocument	słownik wdrożeniowy hr-inbox-document-type	(bez pozycji)	attachment; attribute: external-system-name, external-document-id, receive-operation-comment
WarehouseDocument	warehouse/document-type: 1, 6, 8, 10	order-line, vat-summary-line, goods-receipt-line, goods-issue-line	positionNo, code, status, value[] (valueReference, valueMoney, valueCodeableConcept); attribute: total-net, total-vat, total-gross
InventoryDocument (GR/GI)	(InventoryDocument.type)	(InventoryDocumentPosition)	product, quantity, fromLocation, toLocation

Profile różnią się category, type i code pozycji oraz wyborem składników value[] i attribute[]; struktura rdzenia jest wspólna.