Przejdź do treści

Tryb notyfikacyjny

Tryb notyfikacyjny to lekki wariant trybu rozgłoszeniowego: zamiast pełnej zawartości zasobu, API.ERP emituje jedynie krótkie powiadomienie (awizo) z referencją do zasobu, którego dotyczy zdarzenie — bez przesyłania jego treści biznesowej.

Tryb notyfikacyjny działa naprzemiennie z trybem rozgłoszeniowym — dla danego zasobu obowiązuje zawsze tylko jeden z nich, ustalony w ramach integracji.

Charakterystyka

  • Odroczone pobieranie danych — powiadomienie niesie tylko fakt zdarzenia, nie treść zasobu.
  • Krótkie powiadomienie (awizo) — Notification: operation (created/updated/deleted), date, reference (typ i identyfikator zasobu).
  • Strona odbiorcza decyduje, kiedy i czy w ogóle pobrać pełny zasób — standardowym zapytaniem w trybie żądaniowym.

Przepływ informacji

Cel jest jednym z dwóch: endpoint integratora (POST bezpośrednio do API integratora) albo magazyn obiektowy (integrator odczytuje).

flowchart RL
    D1["FK"]:::domain --> A["API.ERP"]:::api
    D2["WMS"]:::domain --> A
    D3["HR"]:::domain --> A
    A -- "powiadomienie — POST bezpośrednio" --> I["Aplikacja integratora<br/>(endpoint HTTP)"]:::integrator
    A -- "powiadomienie — zapis obiektu" --> B["Magazyn obiektowy"]:::repo
    B -. "odczyt (integrator)" .-> I
    I -. "opcjonalnie: pobranie pełnego zasobu" .-> A

    classDef integrator fill:#8BC34A,stroke:#558B2F,color:#000
    classDef api fill:#03A9F4,stroke:#0277BD,color:#000
    classDef domain fill:#FFA000,stroke:#E65100,color:#000
    classDef repo fill:#FFFFFF,stroke:#333,color:#000

Sekwencja przetworzenia jednego zdarzenia (dwa warianty celu):

sequenceDiagram
    participant D as Systemy dziedzinowe (FK / WMS / HR / ESM)
    participant A as API.ERP
    participant I as Aplikacja integratora / magazyn

    D->>A: Zdarzenie (utworzenie / zmiana / usunięcie zasobu)
    A->>A: Budowa powiadomienia (Notification)
    alt Endpoint HTTP (bezpośrednio do integratora)
        A->>I: POST — powiadomienie
        I-->>A: 2xx (potwierdzenie odbioru)
    else Magazyn obiektowy
        A->>I: Zapis obiektu (powiadomienie)
        Note over I: integrator odczytuje asynchronicznie
    end
    opt integrator potrzebuje pełnych danych
        I->>A: Żądanie (tryb żądaniowy)
        A-->>I: Odpowiedź (zasób kanoniczny)
    end

Repozytorium danych

Tryb notyfikacyjny dostarcza powiadomienie do celu ustalanego w ramach integracji — obsługiwane typy to storage.type: blob (magazyn obiektowy) oraz http (POST bezpośrednio do API integratora). Wspólny model celu, pola połączenia, uprawnienia oraz zasady dostarczania i ponawiania: Cel dostarczenia (storage.type).

Magazyn obiektowy (blob)

API.ERP zapisuje każde powiadomienie jako obiekt JSON w kontenerze integratora; integrator odczytuje go we własnym zakresie (asynchronicznie).

  • Nazwa obiektu: Notification/{id}_{znacznik-czasu}.json.

Endpoint HTTP (http)

API.ERP wysyła powiadomienie pojedynczym żądaniem HTTP POST na adres integratora (storage.url).

  • Metoda: POST na jeden, stały URL (jedno wywołanie = jedno powiadomienie).
  • Body: Notification w JSON (camelCase): resourceType, id, status, operation, date, reference.
  • Nagłówki: Content-Type: application/json; Authorization (Bearer JWT lub Basic — zależnie od ustaleń integracji); dodatkowo nagłówki metadanych zdarzenia.
  • Odpowiedź: endpoint musi zwrócić kod 2xx dla powodzenia (patrz Potwierdzenie odbioru). Opcjonalny nagłówek Location jest odczytywany.

Pełny kontrakt endpointu odbiorczego w formacie OpenAPI 3.0: API-ERP-Notification-Receiver.yaml. Zarys:

paths:
  /:                              # ścieżka/host ustalane przez integratora
    post:
      security: [ { bearerAuth: [] }, { basicAuth: [] } ]   # Bearer JWT lub Basic
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Notification'
      responses:
        '200': { description: Przyjęto }        # dowolny 2xx = sukces
        # kod inny niż 2xx → ponowienie wg polityki retry

Potwierdzenie odbioru

  • Endpoint HTTP: potwierdzeniem przyjęcia jest kod odpowiedzi HTTP — dowolny 2xx oznacza sukces. API.ERP nie oczekuje żadnego dodatkowego callbacku ani treści odpowiedzi; wystarczy status. Brak 2xx, brak połączenia lub przekroczenie czasu = niepowodzenie (patrz niżej).
  • Magazyn obiektowy: brak potwierdzenia zwrotnego — dostarczenie jest uznane po udanym zapisie obiektu. Integrator konsumuje obiekty asynchronicznie we własnym zakresie.

Ponawianie, martwa kolejka (dead-letter), idempotencja (rozróżnianie duplikatów po id i reference) oraz brak gwarancji kolejności są wspólne dla trybów wychodzących — zob. Cel dostarczenia → Dostarczanie, ponawianie, idempotencja. Potwierdzenie odbioru zależy od typu celu — patrz wyżej.

Kiedy używać

Tryb notyfikacyjny pasuje tam, gdzie integratora interesuje sam fakt zmiany, a pełne dane pobiera tylko, gdy faktycznie ich potrzebuje — mniejszy ruch sieciowy niż tryb rozgłoszeniowy. Jeśli integrator zawsze potrzebuje kompletnych danych od razu, właściwy jest tryb rozgłoszeniowy.

Odniesienia