openapi: 3.0.3
info:
  title: API.ERP — Endpoint odbiorczy eksportu (po stronie integratora)
  version: "1.0.0"
  description: >
    Kontrakt endpointu HTTP, który **integrator** udostępnia jako cel eksportu w trybie
    rozgłoszeniowym i notyfikacyjnym. To API.ERP jest klientem — wysyła pojedyncze żądanie
    POST na skonfigurowany adres integratora. W trybie rozgłoszeniowym body zawiera pełny
    zasób kanoniczny, w trybie notyfikacyjnym — powiadomienie Notification.
    Ścieżka i host są ustalane przez integratora (poniżej użyto `/` poglądowo).

servers:
  - url: https://{host}{basePath}
    description: Adres endpointu odbiorczego integratora (konfigurowany w integracji)
    variables:
      host:
        default: integrator.example.com
      basePath:
        default: /api-erp/export

paths:
  /:
    post:
      summary: Odbiór wyeksportowanego zasobu lub powiadomienia
      operationId: receiveExport
      description: >
        Pojedyncze wywołanie = jeden zasób (tryb rozgłoszeniowy) lub jedno powiadomienie
        (tryb notyfikacyjny). Endpoint musi zwrócić kod 2xx dla powodzenia; inny kod
        skutkuje ponowieniem wg polityki retry.

        Zachowanie dla akcji usunięcia (delete):
        w trybie notyfikacyjnym wysyłane jest zwykłe Notification z operacją `deleted`;
        w trybie rozgłoszeniowym — ponieważ zasób źródłowy już nie istnieje — przesyłane jest
        zdarzenie z referencją do usuniętego zasobu (bez pełnej treści).
      security:
        - bearerAuth: []
        - basicAuth: []
      parameters:
        - in: header
          name: X-Source-Type
          description: Metadana — typ źródłowy zdarzenia (informacyjnie).
          required: false
          schema:
            type: string
        - in: header
          name: X-Params
          description: Metadana — parametry zdarzenia (informacyjnie).
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/Notification'
                - $ref: '#/components/schemas/CanonicalResource'
            examples:
              notification:
                summary: Tryb notyfikacyjny — powiadomienie
                value:
                  resourceType: Notification
                  id: 8ac2b4c8-18a7-4f94-810e-97c5d7d827e3
                  status:
                    coding:
                      - system: https://api-erp.kamsoft.pl/vs/notification-status
                        code: completed
                  operation:
                    coding:
                      - system: https://api-erp.kamsoft.pl/vs/notification-operation
                        code: updated
                  date: "2026-07-14T09:15:00Z"
                  reference:
                    type: Party
                    identifier:
                      system: https://api-erp.kamsoft.pl/vs/origin-id
                      value: "123456"
              resource:
                summary: Tryb rozgłoszeniowy — pełny zasób kanoniczny
                value:
                  resourceType: Party
                  id: "123456"
                  name: "Kowalski Jan"
      responses:
        "200":
          description: Przyjęto.
          headers:
            Location:
              description: Opcjonalny adres utworzonego/zaktualizowanego zasobu (odczytywany przez API.ERP).
              schema:
                type: string
        "201":
          description: Utworzono.
          headers:
            Location:
              schema:
                type: string
        "202":
          description: Przyjęto do przetworzenia.
        "401":
          description: Brak lub nieprawidłowa autoryzacja.
        "4XX":
          description: Odrzucono — skutkuje ponowieniem wg polityki retry.
        "5XX":
          description: Błąd po stronie integratora — skutkuje ponowieniem wg polityki retry.

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    basicAuth:
      type: http
      scheme: basic

  schemas:
    CanonicalResource:
      type: object
      description: >
        Pełny zasób kanoniczny (np. Party, Invoice) w postaci JSON (camelCase),
        z polem `resourceType` identyfikującym rodzaj zasobu (zgodnie z DomainResource;
        pole umożliwia też pakowanie zasobów do Bundle). Struktura zależna od typu zasobu —
        zob. modele w Implementation Guide.
      additionalProperties: true
      required: [resourceType]
      properties:
        resourceType:
          type: string
          example: Party
        id:
          type: string

    Notification:
      type: object
      description: >
        Kanoniczne powiadomienie o zdarzeniu na zasobie (tryb notyfikacyjny) —
        oparty o jeden model z polem `resourceType`.
      required: [resourceType, id, status, operation, date, reference]
      properties:
        resourceType:
          type: string
          enum: [Notification]
        id:
          type: string
          description: Identyfikator powiadomienia.
        status:
          $ref: '#/components/schemas/CodeableConcept'
        operation:
          $ref: '#/components/schemas/CodeableConcept'
        date:
          type: string
          format: date-time
        reference:
          $ref: '#/components/schemas/Reference'

    Reference:
      type: object
      description: Odniesienie do zasobu, którego dotyczy powiadomienie.
      properties:
        reference:
          type: string
        type:
          type: string
          description: Typ zasobu docelowego (np. Party).
        identifier:
          $ref: '#/components/schemas/Identifier'
        display:
          type: string

    Identifier:
      type: object
      properties:
        use:
          type: string
        type:
          $ref: '#/components/schemas/CodeableConcept'
        system:
          type: string
          format: uri
        value:
          type: string

    CodeableConcept:
      type: object
      properties:
        coding:
          type: array
          items:
            $ref: '#/components/schemas/Coding'
        text:
          type: string

    Coding:
      type: object
      properties:
        system:
          type: string
          format: uri
        code:
          type: string
        display:
          type: string
