Asynchroniczne API
Informacje ogólne
Asynchroniczne połączenia różnią się od synchronicznych (naszych standardowych) tym, że w odpowiedzi nie otrzymujemy od razu finalnego rezultatu. Zamiast niego otrzymujemy unikalny identyfikator, za pomocą którego można odpytywać status rozpoczętego procesu a także na końcu pobrać wynik.
Głównym celem asynchronicznego API jest danie możliwości pobierania dużych ilości danych oraz wykonywanie bardziej skomplikowanych obliczeniowo czynności.
Przygotowanie połączenia, autoryzacja oraz obsługa błędów jest taka sama jak w obecnym API, więc poniższe funkcjonalności należy traktować jako jego rozszerzenie.
Istnieje jednak pewna różnica, w asynchronicznym API doszła możliwość pobierania plików. Funkcjonalność ta wymusiła pewne zmiany w obsłudze odpowiedzi. Teraz odpowiedź nie zawsze musi być w formacie JSON lub XML, odpowiedź może być skompresowanym plikiem.
Wszystkie pliki jakie przesyłamy są w formacie zip i w nagłówkach odpowiedzi widnieje wtedy:
Content-Type: application/zip
Statusy procesów
0 | Proces oczekuje w kolejce |
---|---|
1 | Proces w trakcie przetwarzania |
2 | Proces zakończony powodzeniem |
3 | Proces zakończony niepowodzeniem |
Sprawdzenie i pobranie wyników
Kontroler służy do pobrania informacji o procesie oraz pobrania pliku z wynikiem.
Sprawdzenie wyników
Wywołanie:
/rest/async_result/get
Dane:
id_job | Wymagane Identyfikator procesu |
---|
Zwracane dane
job_status | Kod statusu procesu |
---|---|
job_message | Opis stanu procesu |
parts | Ilość części, na które został podzielony plik z rezultatem procesu |
Kody błędów
2000 | Nieprawidłowy id_job |
---|---|
2001 | Nie znaleziono procesu dla wskazanego id. |
Pobranie pliku z wynikami
W odpowiedzi na to żądanie otrzymamy od razu gotowy plik w formacie 'zip'. Jeżeli wynik jest w kilku częściach to należy pamiętać, że to nie jest jeden plik binarny rozdzielony na kilka części tylko wiele samodzielnych plików z niezależnymi danymi.
Jeżeli spróbujemy pobrać wyniki zanim proces został ukończony zostanie zwrócona odpowiedź analogiczna jak dla żądania „/rest/async_result/get”
Pobierane archiwa zawierają pliki *.csv. Pliki te mogą mieć różną strukturę, ale tylko pierwsza linijka w pierwszym pliku będzie zawierała opis wszystkich kolumn.
Wywołanie
/rest/async_result/getFile
Dane
id_job | Wymagane | Identyfikator procesu |
---|---|---|
part | Opcjonalne | Numer pliku który ma zostać pobrany. Domyślnie 1 |
Kody błędów:
2000 | Nieprawidłowy id_job |
---|---|
2001 | Nie znaleziono procesu dla wskazanego id |
2002 | Nie znaleziono pliku z wynikiem dla wskazanego id_job oraz part |
Eksport listy odbiorców i aktywności odbiorców
Asynchroniczne API daje możliwość pobrania listy odbiorców. Jako, że jest to API asynchroniczne nie ma pełnej walidacji wprowadzanych zmiennych na starcie. Pełne sprawdzanie parametrów „state” oraz „custom_fields” następuje w procesie głównym. Jeżeli te pola będą miały niepoprawną wartość zostaną zastąpione wartością domyślną. Jeśli niepoprawne będą tylko poszczególne elementy tych parametrów zostaną one pominięte.
Wywołanie:
/rest/async_subscribers_list/export
Dane
list | Wymagane | Hash listy odbiorców |
---|---|---|
state | Opcjonalne | Tablica z statusami odbiorców(lista statusów w „Subskrybenci” klasycznego API). Domyślnie wszyscy odbiorcy przykład: [1,2,4] |
custom_fields | Opcjonalne | Lista pól dodatkowych jakie mają być dołączone do eksportu. Na liście należy umieścić „personalization_tag” interesującego nas pola. Domyślnie żadne pole nie jest wybrane. Przykład: ['pole1','pole2'] |
Zwracane dane
id_job | Id procesu po którym będzie można sprawdzić jego status oraz pobrać końcowy wynik |
---|
Kody błędów:
2010 | Nie znaleziono listy odbiorców |
---|
Eksport akcji odbiorców
API daje możliwość pobrania wszystkich akcji jakie wykonali odbiorcy danego dnia.
Tak jak w przypadku eksportu listy na starcie nie ma pełnej walidacji danych, tutaj na starcie walidowana jest tylko poprawność formatu daty.
Wywołanie:
/rest/async_subscribers_actions/export
Dane
date | Wymagane | Data w formacie „YYYY-MM-DD” |
---|---|---|
type | Opcjonalne | Dostępne typy: all, opened, clicked, bounced, unsubscribed. Domyślna wartość: all |
Zwracane dane
id_job | Id procesu po którym będzie można sprawdzić jego status oraz pobrać końcowy wynik |
---|
Kody błędów
2020 | Niepoprawny format daty |
---|
Debuggowanie
Uwaga! To jest stara dokumentacja Webhooks - wersja ta będzie aktywna do 31.12.2021 r.
Ta wersja Webhooks będzie wygaszana. Prosimy o migrację na nową wersję.
W przypadku mechanizmów typu webhooks proces debuggowania jest trudny do realizacji. W pierwszej kolejności musisz sie upewnić, że Twój serwer odpowiada kodem 200. Do debuggowania można skorzystać z paru ogólnodostepnych narzędzi / serwisów. Niektóre przykłady zamieszczamy poniżej.
RequestBin
Serwis RequestBin można wykorzystać do monitorowania requestów które przychodzą z serwerów FreshMail. Jeśli chcesz skorzystać z tej opcji w pierwszj kolejności powinieneś stworzyć Bin URL. Adres ten wygląda podobnie do:
http://requestb.in/1i379i31
W tym momencie jesteś już gotowy, żeby umieścić ten adres URL w konfiguracji FreshMail Webhooks. Po kliknięciu przycisku Testuj połączenie i powrocie do serwisu RequestBin możesz odświeżyć stronę. Zobaczysz jakie żądania zostały wysłane z serwerów FreshMaila na wskazany przez Ciebie adres.
CURL
Kolejnym prostym sposobem przetestowania komunikacji jest skorzystanie z biblioteki CURL i spreparowanie odpowiednich żądań które będą symulowały dane wysyłane przez serwery FreshMail'a. Przykładowe żądania które można wykorzystać do debuggowania zamieszczamy poniżej:
Żądanie testowe
curl -X POST -d '{"test":"1"}' http(s)://my-domain.com/api/freshmail/webhooks
Żądanie z jednym zdarzeniem
curl -X POST -d '[{"campaign":"jsid73ejd0","email":"email@example.com","event":"open","timestamp":1439989130,"attempt":1,"hash":"32a3c15e44"}]' http(s)://my-domain.com/api/freshmail/webhooks
Żądanie z wieloma zdarzeniami
curl -X POST -d [{"campaign":"kais7nw3ee","email":"email@example.com","event":"open","timestamp":1439989207,"attempt":1,"hash":"0093332079"},{"campaign":"kais7nw3ee","email":"email@example.com","event":"open","timestamp":1439989208,"attempt":4,"hash":"ae9e92b9fe"},{"campaign":"kais7nw3ee","email":"email@example.com","event":"unsubscribe","timestamp":1439889404,"attempt":2,"hash":"ccec7ad7f1"}]
' http(s)://my-domain.com/api/freshmail/webhooks