Skip to main content

Konfiguracja wysylki przez RestAPI

Aktualizacja

Artykuł zweryfikowany dla linii 251231.

Wprowadzenie

Ten artykuł jest dla administratora, który chce skonfigurować wysyłkę wiadomości przez RestAPI w AMODIT. Po lekturze powinno być jasne, gdzie włączyć ten mechanizm, jaką rolę pełni parametr SendMailRestAPIParametersGroupName, jakie pola muszą znaleźć się w grupie parametrów i od czego zacząć diagnostykę, gdy wysyłka nie przechodzi.

W tym wariancie konfiguracja opiera się na nazwie grupy parametrów oraz na definicji zadania HTTP. Administrator musi wskazać grupę, z której AMODIT pobierze adres usługi, endpoint, metodę, content-type, nagłówki i body wysyłki.

Wymagania wstępne

Zanim zaczniesz, przygotuj:

  • decyzję, że organizacja ma wysyłać maile przez zewnętrzną usługę HTTP,
  • adres bazowy usługi, do której AMODIT ma wysyłać zadania,
  • endpoint wysyłki,
  • metodę HTTP oczekiwaną przez usługę,
  • content-type,
  • wymagane nagłówki,
  • szablon body zgodny z API po stronie dostawcy,
  • adres nadawcy, który ma być widoczny dla odbiorców,
  • poprawne adresy AMODIT używane w linkach z wiadomości,
  • uprawnienia administratora do ustawień systemowych i do utrzymania odpowiedniej grupy parametrów.

Krótki przykład: AMODIT może przekazywać gotową wiadomość do firmowej bramki HTTP, która dalej wysyła mail przez infrastrukturę organizacji albo zewnętrznego dostawcy transakcyjnego. W takim scenariuszu kluczowa jest poprawna definicja zadania HTTP.

Instrukcja krok po kroku

  1. Otwórz Ustawienia systemowe i przejdź do sekcji Ogólne > Powiadomienia.
    W tym miejscu wybierasz mechanizm wysyłki i uzupełniasz pola wspólne dla całej poczty wychodzącej.

  2. Ustaw mechanizm wysyłki na RestAPI.
    Ten wybór jest właściwy wtedy, gdy organizacja chce przekazywać wiadomości do zewnętrznej usługi HTTP albo do własnej warstwy integracyjnej.

  3. Uzupełnij parametr SendMailRestAPIParametersGroupName nazwą grupy, z której AMODIT ma pobierać konfigurację wysyłki.
    To jest punkt startowy dla całego transportu RestAPI. Sam wybór protokołu nie wystarczy, jeśli system nie wie, z której grupy ma czytać bazę URL, endpoint, metodę, nagłówki i body.

  4. Przygotuj w tej grupie parametr o nazwie równej nazwie grupy i wpisz w nim bazowy adres usługi.
    Kod używa tego pola jako adresu klienta HTTP. To zwykle host albo główny URL integracji, do którego zostanie dołożony endpoint wysyłki.

  5. Dodaj parametr `

    .Send.Endpoint` i wpisz ścieżkę endpointu wysyłki.
    To tutaj wskazujesz konkretną trasę API odpowiedzialną za przyjęcie zadania wysyłki.

  6. Dodaj parametr `

    .Send.RequestType` i ustaw metodę HTTP oczekiwaną przez usługę.
    Ta wartość steruje typem zadania HTTP. Musi być zgodna z wymaganiami po stronie usługi zewnętrznej.

  7. Dodaj parametr `

    .Send.ContentType` i ustaw format body.
    Ta wartość decyduje nie tylko o nagłówku `content-type`, ale też o sposobie parsowania body przez AMODIT. Dla `application/json` system traktuje treść jako JSON, a dla `application/x-www-form-urlencoded` jako dane formularza URL-encoded.

  8. Dodaj parametr `

    .Headers` i wpisz wymagane nagłówki HTTP.
    Nagłówki są częścią konfiguracji `RestAPI`. Mogą zawierać wartości stałe albo szablony, jeśli usługa oczekuje dynamicznych danych.

  9. Dodaj parametr `

    .Send.Body` i przygotuj body zgodne z API po stronie dostawcy.
    To najważniejsza część integracji. Body jest budowane na podstawie danych konkretnej wiadomości, dlatego musi być poprawne zarówno biznesowo, jak i składniowo.

  10. Uzupełnij pole nadawcy adresem, który ma być widoczny dla odbiorców.
    AMODIT nadal buduje wiadomość z określonym nadawcą. Trzeba jednak pamiętać, że usługa HTTP po swojej stronie może mieć dodatkowe zasady akceptacji albo nadpisywania tego adresu.

  11. Sprawdź ustawienia linków używanych w mailach wychodzących.
    Zwróć uwagę na Web URL for internal users, adres dla użytkowników zewnętrznych i ustawienie UseCurrentWebUrl. Poprawny endpoint RestAPI nie wystarczy, jeżeli wiadomość prowadzi odbiorcę pod zły adres AMODIT.

  12. Ustal podstawowe zasady pracy kolejki wychodzącej.
    Sprawdź Sending limit, Delete notifications older than [X] days, Log emails sent with the SendMessage function i listę kodów błędów pomijanych przy ponownej wysyłce. To ustawienia wspólne dla całego outgoing, ale nadal wpływają na zachowanie systemu przy RestAPI.

  13. Zapisz ustawienia i wykonaj rzeczywisty test wysyłki.
    Po teście sprawdź, czy usługa zwraca poprawną odpowiedź, czy mail został rzeczywiście dostarczony, czy nadawca i linki są poprawne oraz czy logi nie pokazują błędu budowy zadania HTTP.

Co musi znaleźć się w grupie parametrów

Minimalny zestaw wymagany przez kod:

Parametr Rola
`
` bazowy adres usługi HTTP
`
.Send.Endpoint` endpoint wysyłki
`
.Send.RequestType` metoda HTTP
`
.Send.ContentType| format body i nagłówekcontent-type`
`
.Headers` dodatkowe nagłówki
`
.Send.Body` szablon body zadania

W praktyce oznacza to, że administrator utrzymuje nazwę grupy, a sama grupa przechowuje szczegóły zadania HTTP.

Weryfikacja

Po poprawnej konfiguracji:

  • mechanizm wysyłki jest ustawiony na RestAPI,
  • SendMailRestAPIParametersGroupName wskazuje istniejącą i poprawnie uzupełnioną grupę,
  • usługa przyjmuje zadanie HTTP,
  • wiadomość jest rzeczywiście dostarczona,
  • odbiorca widzi poprawny adres nadawcy,
  • linki w treści prowadzą do poprawnego środowiska.

Jeśli system nadal nie wysyła wiadomości, sprawdź najpierw:

  1. czy mechanizm wysyłki na pewno jest ustawiony na RestAPI,
  2. czy SendMailRestAPIParametersGroupName wskazuje poprawną grupę,
  3. czy grupa zawiera bazę URL, endpoint, metodę, content-type, nagłówki i body,
  4. czy body jest zgodne z oczekiwaniami usługi,
  5. czy usługa zwraca HTTP 200 OK,
  6. czy problem nie dotyczy nadawcy albo linków, a nie samego transportu HTTP.

Wynik końcowy

Po wykonaniu tej konfiguracji AMODIT przekazuje wiadomości do zewnętrznej usługi HTTP zgodnie z definicją grupy parametrów i uznaje wysyłkę za zakończoną dopiero wtedy, gdy usługa odpowie sukcesem.

Ważne informacje i ostrzeżenia

  • Rdzeniem konfiguracji RestAPI są: wybór protokołu, nazwa grupy parametrów oraz poprawna definicja zadania HTTP.
  • W tym wariancie powodzenie wysyłki zależy nie tylko od AMODIT, ale też od odpowiedzi usługi zewnętrznej.
  • Kod uznaje za sukces tylko HTTP 200 OK. Inne odpowiedzi kończą się niepowodzeniem wysyłki.
  • W ścieżce RestAPI nie ma override transportu per mailbox.
  • Pole nadawcy nadal ma znaczenie biznesowe, ale sama usługa HTTP może mieć własne reguły walidacji albo mapowania nadawcy.

Typowe problemy

RestAPI nie wysyła wiadomości mimo poprawnego wyboru protokołu

Najczęstsze przyczyny:

  • błędna nazwa grupy w SendMailRestAPIParametersGroupName,
  • brak jednego z wymaganych parametrów grupy,
  • zły endpoint, metoda albo content-type,
  • body niezgodne z oczekiwaniami usługi,
  • usługa zwraca inny status niż 200 OK.

Usługa przyjmuje zadanie, ale mail nie dochodzi do odbiorcy

W tym scenariuszu trzeba odróżnić dwa poziomy:

  • czy AMODIT poprawnie zbudował i wysłał zadanie HTTP,
  • czy zewnętrzna usługa rzeczywiście dostarczyła wiadomość.

Jeśli odpowiedź HTTP jest poprawna, ale mail nadal nie dociera, problem może leżeć po stronie samej bramki albo dalszej infrastruktury dostawcy.

Wiadomość wychodzi, ale ma zły nadawcę albo złe linki

Najpierw sprawdź:

  • pole nadawcy,
  • zasady nadawcy po stronie usługi zewnętrznej,
  • ustawienia WebURL, ExternalWebURL i UseCurrentWebUrl.

Powiązane artykuły