Przejdź do treści

Przykłady requestów i odpowiedzi

Przykłady dla API.ERP, zgodne z technical-conventions.md: wersja w ścieżce /v1/, rzeczowniki w liczbie mnogiej, kebab-case w ścieżkach, camelCase w parametrach zapytań i w JSON, paginacja count/offset, koperta items/nextToken, błędy w formacie Problem Details (RFC 9457).

Konwencje przykładów

Wszystkie przykłady w IG (w tym strony przykładów poszczególnych zasobów, np. PostingInstruction — przykłady) stosują następujące konwencje:

  • Placeholdery wdrożeniowe — wartości urn:oid:2.999.* to placeholdery: łuk OID 2.999 jest zarezerwowany do celów przykładowych. Realne przestrzenie mają postać urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz> i wynikają z zasobów NamingSystem (GET /v1/naming-systems) oraz parametrów wdrożenia; przykłady nie definiują ich treści. Numeracja 2.999.<n> jest lokalna dla każdej strony przykładów (każda strona ma własną legendę) — ten sam numer na różnych stronach nie oznacza tej samej przestrzeni. Systemy niezależne od wdrożenia pozostają dosłowne (np. NIP/REGON: https://gov.pl/...).
  • Referencje logiczne przez identifier — powiązania między zasobami zapisujemy jako type + identifier{system, value}, zgodnie z Reference; pole reference jest wyłącznie opcjonalnym dodatkiem technicznym.
  • Zapis z przestrzenią identyfikatora — przykłady POST podają identifier[].system, bo to zalecana postać: przestrzeń wskazuje instalację, która zarejestruje zasób. Nie jest obowiązkowa — pominięta, rozstrzyga profil. W PATCH parametr identifier=system|value wskazuje zasób do zmiany. Wartość (value) przy rejestracji jest opcjonalna — nadaje ją system prowadzący (rejestracja zasobu).
  • Słowniki (value sety) — URL-e https://api-erp.kamsoft.pl/vs/... są częścią IG; pełny rejestr słowników: Systemy kodowania i value sety.

1. Odczyt zasobu (GET)

Odczyt zawsze idzie przez kolekcję; zasób wskazuje parametr identifier=system|value.

Request:

GET /v1/parties?identifier=https://gov.pl/nip%7C1234567890&count=20&offset=0 HTTP/1.1
Host: <base-url>
Authorization: Bearer <token>
Accept: application/json

Response (200 OK):

{
  "items": [
    {
      "resourceType": "Party",
      "id": "123",
      "meta": {
        "lastModified": "2025-01-15T10:00:00Z",
        "profile": ["https://api-erp.kamsoft.pl/ns/StructureDefinition/Contractor"]
      },
      "category": [
        { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/party-kind", "code": "contractor", "display": "Kontrahent" }] }
      ],
      "identifier": [
        { "system": "urn:oid:2.999.1", "value": "123" },
        { "system": "https://gov.pl/nip", "value": "1234567890" }
      ],
      "name": {
        "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/finance/party-name", "code": "short-name", "display": "ABC Sp. z o.o." }],
        "text": "ABC Sp. z o.o."
      }
    }
  ],
  "nextToken": null
}

Legenda: urn:oid:2.999.1 — przestrzeń id kontrahenta w instalacji księgowej. Pola w camelCase; parametry zapytań w camelCase. Konkretne zasoby i parametry — api-contracts.md.

2. Utworzenie zasobu (POST)

Request — zapotrzebowanie zakupowe:

POST /v1/purchase-requisitions HTTP/1.1
Host: <base-url>
Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json

{
  "resourceType": "PurchaseRequisition",
  "identifier": [{ "system": "urn:oid:2.999.6" }],
  "issueDate": "2025-01-15",
  "expectedDate": "2025-01-22",
  "warehouse": { "type": "Location", "identifier": { "system": "urn:oid:2.999.2", "value": "7" } },
  "description": "Uzupełnienie stanu apteczki oddziałowej",
  "position": [
    {
      "positionNo": 1,
      "product": { "type": "ProductDefinition", "identifier": { "system": "urn:oid:2.999.3", "value": "10045" } },
      "quantity": { "value": 10, "unit": "op." }
    }
  ]
}

Response (200 OK): koperta { "items": [ … ], "nextToken": null } z zapotrzebowaniem zapisanym po stronie systemu magazynowego — z nadanym identyfikatorem wewnętrznym (identifier[] w przestrzeni PurchaseRequisition.Id) i statusem ze słownika warehouse/purchase-requisition-status. Pozostałe operacje zapisu (POST /v1/parties, POST /v1/posting-instructions, POST /v1/fixed-asset-documents) zwracają sam zasób.

Legenda: urn:oid:2.999.6 — przestrzeń id zapotrzebowania, urn:oid:2.999.2 — przestrzeń id magazynu, urn:oid:2.999.3 — przestrzeń id produktu. Zapis niesie przestrzeń identyfikatora (identifier[].system), bo to zalecana postać — wskazuje instalację rejestrującą; pominięta, rozstrzyga profil. Wartość (value) przy rejestracji jest opcjonalna — nadaje ją system prowadzący. Zapis zasobu wieloprofilowego (np. POST /v1/parties?owner=https://gov.pl/nip|<NIP>) wymaga dodatkowo meta.profile albo cechy rozpoznającej profil — zob. Identyfikacja i parametry wdrożenia §3.

3. Aktualizacja zasobu (PATCH)

Request: PATCH na kolekcji; cel wskazuje identifier, treść to pełny zasób.

PATCH /v1/parties?identifier=urn:oid:2.999.1%7C123&owner=https://gov.pl/nip%7C1234567890 HTTP/1.1
Host: <base-url>
Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json

{
  "resourceType": "Party",
  "meta": { "profile": ["https://api-erp.kamsoft.pl/ns/StructureDefinition/Contractor"] },
  "identifier": [
    { "system": "urn:oid:2.999.1", "value": "123" },
    { "system": "https://gov.pl/nip", "value": "1234567890" }
  ],
  "name": { "text": "ABC Spółka z o.o." }
}

Response (200 OK): zaktualizowany zasób w postaci kanonicznej.

4. Obsługa błędów (Problem Details)

Response (404 Not Found) — przestrzeń identyfikatora spoza miejsca prawdy zasobu:

{
  "type": "https://httpstatuses.com/404",
  "title": "Resource not found",
  "status": 404,
  "detail": "The identifier namespace does not belong to the master of the requested resource.",
  "instance": "/v1/parties",
  "traceId": "00-6f1c…-01"
}

Response (422 Unprocessable Entity) — profil nieobsługiwany u klienta:

{
  "type": "https://httpstatuses.com/422",
  "title": "Request cannot be processed",
  "status": 422,
  "detail": "Profile 'https://api-erp.kamsoft.pl/ns/StructureDefinition/Contractor' is not supported for this client.",
  "instance": "/v1/parties",
  "traceId": "00-6f1c…-02"
}

Response (400 Bad Request) — brak profilu w zapisie:

{
  "type": "https://httpstatuses.com/400",
  "title": "Invalid request",
  "status": 400,
  "detail": "Profile of 'Party' is not specified: give meta.profile or the attributes of one of: …/Employee, …/Employer, …/Contractor, …/AssetHolder.",
  "instance": "/v1/parties",
  "traceId": "00-6f1c…-03"
}

Format zgodny z RFC 9457 Problem Details (type, title, status, detail, instance, traceId); type to https://httpstatuses.com/{status}.

5. Statusy HTTP (skrót)

  • 200 OK — odczyt oraz zapis POST/PATCH zakończony sukcesem (odpowiedź niesie zasób).
  • 202 Accepted — zlecenie raportu przyjęte (POST /v1/reports).
  • 400 Bad Request — zły format parametru (identifier, owner, attribute), wartość filtra kodowanego (category, type, status) z przestrzeni spoza słowników zasobu, zapis bez rozpoznanego profilu, nieznany profile.
  • 401 Unauthorized — brak lub nieważny token.
  • 403 Forbidden — brak roli API.<Zasób>.Read / API.<Zasób>.Write.
  • 404 Not Found — przestrzeń identyfikatora wskazuje instalację nieobsługującą profilu, nieznany typ raportu.
  • 422 Unprocessable Entity — profil nieobsługiwany w instalacji, zasób tylko do odczytu, odrzucenie przez system prowadzący.
  • 500 Internal Server Error — błąd serwera.
  • 501 Not Implemented — operacja nieobsługiwana.
  • 503 Service Unavailable — system prowadzący nie odpowiada.

6. Paginacja

Request:

GET /v1/purchase-orders?count=20&offset=40 HTTP/1.1

Response (200 OK):

{
  "items": [
    {
      "resourceType": "PurchaseOrder",
      "id": "41",
      "identifier": [
        { "system": "urn:oid:2.999.4", "value": "41" }
      ],
      "status": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/purchase-order-status", "code": "2", "display": "przekazane" }] }
    }
  ],
  "nextToken": null
}

count — rozmiar strony (domyślnie 20), offset — liczba pominiętych elementów. Kolejną stronę pobiera się zwiększając offset; nextToken jest dziś zawsze null. Legenda: urn:oid:2.999.4 — przestrzeń id zamówienia zakupu.

7. Zasób z Identifier i Coding (rozszerzalna identyfikacja, wzorowana na FHIR)

Modele zawierają tablicę identifier[] (identyfikatory z różnych przestrzeni) oraz pola typu CodeableConcept (kody ze słowników). Zgodnie z technical-conventions.md.

Response (200 OK) — element items[] dla GET /v1/purchase-orders:

{
  "resourceType": "PurchaseOrder",
  "id": "41",
  "meta": { "lastModified": "2025-01-15T10:00:00Z" },
  "identifier": [
    {
      "system": "urn:oid:2.999.4",
      "value": "41"
    },
    {
      "system": "urn:oid:2.999.5",
      "value": "ZAM/2025/0041"
    }
  ],
  "type": {
    "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/purchase-order-type", "code": "2", "display": "zamówienie" }]
  },
  "status": {
    "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/purchase-order-status", "code": "7", "display": "w trakcie realizacji" }]
  },
  "attribute": [
    {
      "code": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/purchase-order-attribute-type", "code": "order-fulfillment-step" }] },
      "value": { "valueCodeableConcept": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/warehouse/purchase-order-realization-step", "code": "part-fulfilled" }] } }
    }
  ]
}

identifier[] — identyfikacja w kilku przestrzeniach (id wewnętrzny, numer dokumentu), rodzaj wynika z przestrzeni system. type i status — CodeableConcept z tablicą coding (system, code, display) z wariantu warehouse/. Legenda: urn:oid:2.999.4 — id zamówienia, urn:oid:2.999.5 — numer zamówienia.

8. Zlecenie raportu asynchronicznego (202 Accepted)

Request:

POST /v1/reports HTTP/1.1
Host: <base-url>
Authorization: Bearer <token>
Content-Type: application/json

{
  "reportId": "cost-calculation",
  "format": "parquet",
  "runAt": "2026-05-01T02:00:00Z",
  "publicKeyPem": "-----BEGIN PUBLIC KEY-----\n…\n-----END PUBLIC KEY-----",
  "storage": { "type": "blob", "connectionString": "BlobEndpoint=https://<account>.blob.core.windows.net/;SharedAccessSignature=…" },
  "parameters": { "year": 2026, "month": 4 }
}

Response (202 Accepted):

{
  "executionId": "b3f1c2d4-…",
  "encryptedSessionKey": "base64…"
}

Nieznany reportId kończy się 404. Szczegóły zlecenia, szyfrowania i celu dostarczenia: Tryb raportowy, Raporty retrospektywne.

Dokumenty pionowe (przykłady poza REST)

Przykłady JSON i XML dla e-skierowania medycyny pracy (mp) — nie są requestami REST; służą generatorowi CDA i walidacji profilu:

Artefakt Lokalizacja
JSON wejściowe verticals/mp/tools/examples/
XML wygenerowane / wzorcowe verticals/mp/samples/, verticals/mp/tools/examples/generated/
Schemat verticals/mp/contracts/skierowanie_mp_input.schema.json

Indeks: API-ERP-MP-dokumentacja.md.