Przejdź do treści

Przykłady requestów i odpowiedzi

Przykłady dla naszego API, zgodne z technical-conventions.md i założeniami REST API – Założenia v1.0 (pharmind XF): wersja w ścieżce /v1/, rzeczowniki w liczbie mnogiej, kebab-case w ścieżkach, snake_case w parametrach zapytań, camelCase w JSON, PATCH = tylko pola do zmiany, błędy w formacie Problem Details.

1. Odczyt zasobu (GET)

Request:

GET /v1/purchase-orders?user_id=123&start_date=2025-01-01 HTTP/1.1
Host: <base-url>
Authorization: Bearer <token>
Accept: application/json
ks-client: my-system

Response (200 OK):

{
  "id": "po-001",
  "orderNumber": "PO-2025-001",
  "status": "Open",
  "createdAt": "2025-01-15T10:00:00Z"
}

Pola w camelCase; parametry zapytań w snake_case. Konkretne zasoby i pola — zgodnie z api-contracts.md.

2. Utworzenie zasobu (POST)

Request:

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

{
  "supplierId": "sup-001",
  "orderDate": "2025-01-15",
  "lineItems": [
    {
      "productId": "prod-001",
      "quantity": 10,
      "unitPrice": 99.50
    }
  ]
}

Response (201 Created):

{
  "id": "po-002",
  "orderNumber": "PO-2025-002",
  "status": "Open",
  "createdAt": "2025-01-15T11:00:00Z"
}

3. Częściowa aktualizacja zasobu (PATCH)

Request: Tylko pola do zmiany (prosty obiekt JSON).

PATCH /v1/invoices/inv-001 HTTP/1.1
Host: <base-url>
Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json

{
  "tags": ["tag1", "tag2"],
  "documentProcessingStatus": "Processed",
  "processingSystem": "ERP"
}

Response (200 OK): Zaktualizowany zasób (pola w camelCase) lub potwierdzenie — zgodnie z kontraktem.

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

Response (404 Not Found):

{
  "status": 404,
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4",
  "title": "Resource not found",
  "detail": "Purchase order 'po-999' could not be found",
  "instance": "/v1/purchase-orders/po-999"
}

Response (422 Unprocessable Entity):

{
  "status": 422,
  "type": "https://example.com/errors/validation",
  "title": "Validation error",
  "detail": "Quantity must be greater than zero",
  "instance": "/v1/purchase-orders"
}

Format zgodny z RFC 7807 Problem Details (status, type, title, detail, instance).

5. Statusy HTTP (skrót)

  • 200 OK — żądanie zakończone sukcesem.
  • 201 Created — zasób utworzony.
  • 202 Accepted — przyjęte do przetwarzania.
  • 204 No Content — brak body (np. po DELETE).
  • 400 Bad Request — nieprawidłowe dane.
  • 401 Unauthorized — wymagane logowanie.
  • 403 Forbidden — brak uprawnień.
  • 404 Not Found — zasób nie istnieje.
  • 409 Conflict — konflikt danych.
  • 422 Unprocessable Entity — błąd walidacji.
  • 429 Too Many Requests — przekroczony limit.
  • 500 Internal Server Error — błąd serwera.

6. Paginacja

Request (parametry w snake_case):

GET /v1/purchase-orders?page=1&page_size=20&order_by=createdAt&sort=desc HTTP/1.1

Response (200 OK):

{
  "items": [
    {
      "id": "po-001",
      "orderNumber": "PO-2025-001",
      "status": "Open"
    }
  ],
  "totalCount": 150,
  "nextPageToken": "eyJwYWdlIjoyfQ=="
}

Nazwy pól (np. nextPageToken, page_size) do ustalenia w konwencjach; pola w JSON w camelCase.

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

Modele mogą zawierać tablicę identifiers (identyfikatory z różnych systemów) oraz pola typu Coding / CodeableConcept (kody z systemów terminologicznych). Zgodnie z technical-conventions.md.

Response (200 OK) — np. zamówienie zakupu z identyfikatorami i typem dokumentu:

{
  "id": "po-001",
  "identifiers": [
    {
      "system": "https://api.example.com/identifiers/purchase-order",
      "value": "PO-2025-001",
      "use": "official"
    },
    {
      "system": "urn:supplier:erp:order-id",
      "value": "SUP-98765",
      "use": "secondary"
    }
  ],
  "orderNumber": "PO-2025-001",
  "documentType": {
    "coding": [
      {
        "system": "https://api.example.com/codes/document-type",
        "code": "PO",
        "display": "Purchase Order"
      }
    ],
    "text": "Purchase Order"
  },
  "status": {
    "coding": [
      {
        "system": "https://api.example.com/codes/order-status",
        "code": "open",
        "display": "Open"
      }
    ]
  },
  "createdAt": "2025-01-15T10:00:00Z"
}

identifiers — wielozakresowa identyfikacja (wewnętrzny numer, numer u dostawcy). documentType i status — CodeableConcept z tablicą coding (system, code, display) i opcjonalnym text.

8. Zlecenie raportu asynchronicznego (202 Accepted)

9. Globalny Bundle (request + response)

Przykład globalnego, FHIR-like envelope do wymiany wielu zasobów w jednej wiadomości. Model jest samodzielnym zasobem integracyjnym i upraszcza klasyczne FHIR entry[] do dwóch sekcji: request i response.

Tryby type: collection (odczyt — zbiór w response), batch (wiele CRUD niezależnie), transaction (CRUD all-or-nothing — poniżej), message (zdarzenia), document (spójna całość). W items może być dowolny DomainResource. Pełna semantyka i przykłady pozostałych trybów: Resources/Core/Bundle.md.

9.1 transaction — przykład

Payload:

{
  "resourceType": "Bundle",
  "type": "transaction",
  "request": {
    "items": [
      {
        "method": "create",
        "url": "urn:uuid:party-1",
        "resource": {
          "resourceType": "Party",
          "id": "party-001",
          "comment": "Nowy podmiot biznesowy"
        }
      },
      {
        "method": "create",
        "url": "urn:uuid:party-role-1",
        "resource": {
          "resourceType": "PartyRole",
          "id": "pr-001",
          "comment": "Rola podmiotu: dostawca",
          "owner": [
            {
              "system": "internal-reference",
              "value": "urn:uuid:party-1"
            }
          ]
        }
      },
      {
        "method": "create",
        "url": "urn:uuid:posting-instruction-1",
        "resource": {
          "resourceType": "PostingInstruction",
          "id": "pi-001",
          "comment": "Instrukcja podatkowo-księgowa",
          "owner": [
            {
              "system": "internal-reference",
              "value": "urn:uuid:party-role-1"
            }
          ]
        }
      }
    ]
  },
  "response": {
    "status": "success",
    "detail": "Wszystkie obiekty zostały utworzone pomyślnie.",
    "items": [
      {
        "method": "create",
        "url": "urn:uuid:party-1",
        "resource": {
          "resourceType": "Party",
          "id": "party-001",
          "comment": "Nowy podmiot biznesowy",
          "meta": {
            "created": "2026-05-29T10:15:00Z"
          }
        }
      },
      {
        "method": "create",
        "url": "urn:uuid:party-role-1",
        "resource": {
          "resourceType": "PartyRole",
          "id": "pr-001",
          "comment": "Rola podmiotu: dostawca",
          "owner": [
            {
              "system": "internal-reference",
              "value": "urn:uuid:party-1"
            }
          ],
          "meta": {
            "created": "2026-05-29T10:15:01Z"
          }
        }
      },
      {
        "method": "create",
        "url": "urn:uuid:posting-instruction-1",
        "resource": {
          "resourceType": "PostingInstruction",
          "id": "pi-001",
          "comment": "Instrukcja podatkowo-księgowa",
          "owner": [
            {
              "system": "internal-reference",
              "value": "urn:uuid:party-role-1"
            }
          ],
          "meta": {
            "created": "2026-05-29T10:15:02Z"
          }
        }
      }
    ]
  }
}

type jest prostym code, wzorowanym na FHIR. Każdy element tablicy items zawiera method (CRUD operation), url (internal reference), i resource (DomainResource). W response method może być także error lub innym kodem stanu zamiast czysto CRUD. response.status to ogólny wynik (success, partial, failure), zaś szczegóły każdej operacji są w poszczególnych items[].

Request:

POST /reports HTTP/1.1
Host: <base-url>
Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json
ks-client: my-system

{
  "reportId": "{guid}",
  "runAt": "2026-05-26T18:00:00Z",
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=<account>;AccountKey=<key>;EndpointSuffix=core.windows.net",
  "publicKeyPem": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----",
  "obfuscationToken": "{token}",
  "pseudonymizationToken": "{token}",
  "compression": true,
  "parameters": {
    "year": "2026",
    "month": "05",
    "status": "active"
  },
  "secretToken": "{token}"
}

Wariant dla generowania raportu dla grupy używa pola groupId zamiast reportId. Pola obfuscationToken, pseudonymizationToken i compression są opcjonalne; secretToken pozostaje opcjonalny, jeśli wymagany jest dodatkowy token sterujący zakresem eksportu. Pole runAt pozwala zaplanować moment uruchomienia raportu, a connectionString wskazuje konto Azure Storage, na którym zostanie umieszczony artefakt.

Response (202 Accepted):

{
  "id": "rr-001",
  "status": "Accepted",
  "statusUrl": "/reports/rr-001",
  "artifactUrl": "/reports/rr-001/artifact",
  "dataKey": "base64-rsa-encrypted-session-key",
  "format": "csv"
}

Raport jest przyjmowany asynchronicznie. publicKeyPem jest wymagany, aby serwer mógł zwrócić jednorazowy dataKey w postaci zaszyfrowanej; dla csv dane są szyfrowane hybrydowo PGP z AES-256, dla parquet stosowany jest flow PME; zstd pozostaje opcjonalne.

Wszystkie przykłady odnoszą się do naszego API; po doprecyzowaniu kontraktów w api-contracts.md uzupełnić konkretnymi zasobami i polami.

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.