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

API.ERP dostarcza powiadomienie do celu wskazanego przez integratora. Dostępne są dwa typy celu:

  • Endpoint HTTP — dostawa bezpośrednio do API integratora (API.ERP jest klientem POST-a; nie ma pośredniego magazynu).
  • Magazyn obiektowy (Blob Storage) — API.ERP zapisuje obiekt do magazynu, a integrator odczytuje go we własnym zakresie (asynchronicznie).

Magazyn obiektowy (Blob Storage)

API.ERP zapisuje każde powiadomienie jako obiekt JSON w kontenerze wskazanym przez integratora.

  • Nazwa obiektu: Notification/{id}_{znacznik-czasu}.json.
  • Uprawnienia connection string: API.ERP wyłącznie zapisuje — nie odczytuje ani nie usuwa danych. Poświadczenia muszą pozwalać na zapis i tworzenie obiektów w docelowym kontenerze oraz utworzenie kontenera, jeśli jeszcze nie istnieje.
  • Dla SAS: uprawnienia Write i Create; zakres obejmujący kontener i obiekty.
  • Nie są wymagane uprawnienia Read, Delete ani List.
  • Zalecane: SAS ograniczony do jednego kontenera, z terminem ważności; connection string w formacie BlobEndpoint=...;SharedAccessSignature=... lub oparty o klucz konta.

Endpoint HTTP

API.ERP wysyła powiadomienie pojedynczym żądaniem HTTP POST na adres wskazany przez integratora.

  • 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-Export-Receiver.yaml (dla powiadomień właściwy jest schemat Notification). 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.

Dostarczanie i ponawianie

  • Przy niepowodzeniu dostawy (brak połączenia, przekroczenie czasu, kod inny niż 2xx) powiadomienie pozostaje w kolejce i jest ponawiane w kolejnych cyklach eksportu, aż do skonfigurowanego limitu prób.
  • Po wyczerpaniu limitu trafia do martwej kolejki (dead-letter) i nie jest dalej wysyłane automatycznie — wymaga interwencji lub ponownego zlecenia.
  • Idempotencja (ważne): ponawianie oznacza, że integrator może otrzymać to samo powiadomienie więcej niż raz. Odbiorca musi być idempotentny — rozróżniać duplikaty po id i reference.
  • Kolejność dostarczenia nie jest gwarantowana.

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