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”

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

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