Autoryzacja

API systemu FreshMail zostało zrealizowane według wzorca REST.

Komunikacja polega na wysłaniu żądania HTTP pod adres https://api.freshmail.com/rest/ i ewentualnym przesłaniu wymaganych danych. Odpowiedź jest zwracana w formacie JSON.

Uwierzytelnienie

Każde wysłane żądanie po API wymaga uwierzytelnienia. Klient ma do wyboru jedną z dwóch możliwości uwierzytelnienia:

Bearer Token
ApiKey & ApiSign

Bearer Token (Preferowana forma autoryzacji)

Uwierzytelnienie następuje poprzez wysłanie nagłówka HTTP o nazwie:

Authorization: Bearer XYZ	gdzie XYZ zawiera unikalny token dostępu do API, każdy z klientów posiada swój unikalny token/grupę tokenów API. Token można znaleźć w Aplikacji przechodząc do: Ustawienia → Wtyczki i API → Integracje →Twoje dane dostępowe do API V2/V3.

Authorization: Bearer XYZ

gdzie XYZ zawiera unikalny token dostępu do API, każdy z klientów posiada swój unikalny token/grupę tokenów API.

Token można znaleźć w Aplikacji przechodząc do:
Ustawienia → Wtyczki i API → Integracje →Twoje dane dostępowe do API V2/V3.

Przykład poprawnego nagłówka:
Authorization: Bearer fisgvt.6waelw6v7WiZ68mnFMExI79YXY3Y1RH0Xc5

ApiKey & ApiSign

Uwierzytelnienie następuje poprzez wysłanie nagłówków HTTP o nazwach:

X-Rest-ApiKey	zawiera unikalny klucz dostępu do API, każdy z klientów posiada swój unikalny klucz API. subskrypcje → lista subskrypcyjna → opcje zaawansowane i API
X-Rest-ApiSign	zawiera podpis żądania. Podpis jest generowany na podstawie parametrów wysyłanych w żądaniu oraz na podstawie ApiSecret.

Istnieją dwa schematy generowania X-Rest-ApiSign, oba zostały przedstawione poniżej:

1. Schemat oparty na URL-encoded query

wymagane jest dodanie nagłówka Content-Type w żądaniu http o wartości:

text/html lub application/xml lub application/json, np.: Content-Type: application/json

wtedy można wygenerować X-Rest-ApiSign w oparciu o algorytm:

sha1( ApiKey + GET_data + POST_data + ApiSecret )

gdzie:

ApiKey	32 znakowy klucz API.
GET_data	pełna ścieżka dostępu – np. /rest/ping, /rest/mail itp. Więcej szczegółów w sekcji „Ścieżka dostępu”.
POST_data	dane POST umieszczone w żądaniu. Jeśli w żądaniu znajdują się tylko dane GET to wartość POST_data jest pusta. Wartości muszą być escapowane na potrzeby URL, np.: email=test%40test.pl&subject=test+emaila
ApiSecret	40 znaków, unikalny sekret dla każdego z klientów. W przypadku skompromitowania klucza należy bezzwłocznie wygenerować nowy.

2. Schemat oparty na JSON

wymagane jest dodanie nagłówka Content-Type w żądaniu http w postaci:

Content-Type: application/json

wtedy można wygenerować X-Rest-ApiSign w oparciu o algorytm:

sha1( ApiKey + GET_data + JSON_data + ApiSecret )

gdzie:

ApiKey	32 znakowy Api key.
GET_data	pełna ścieżka dostępu – np. /rest/ping, /rest/mail itp. Więcej szczegółów w sekcji „Ścieżka dostępu”.
JSON_data	dane w formacie JSON jakie są wysyłane w żądaniu. Jeśli w żądaniu znajdują się tylko dane GET to wartość JSON_data jest pusta. Przykładowa wartość JSON_data: {"subscriber":"test@test.pl"}
ApiSecret	40 znaków, unikalny sekret dla każdego z klientów. W przypadku skompromitowania klucza należy bezzwłocznie wygenerować nowy.

Odpowiedzi API

Odpowiedź na każde żądanie wysłane do API jest w formacie JSON, np.

{"status":"OK","data":[1,2,3]}

Jeśli zapytanie powiedzie się wtedy pod kluczem „status” będziemy mieli wartość 'OK'. Jeśli metoda ma zwrócić dane będą one pod kluczem „data”. Natomiast jeśli wystąpi błąd pod kluczem „status” będzie wartość „ERROR”, a pod kluczem „errors” znajdzie się opis błędów jakie wystąpiły wraz z kodami błędów.

W przypadku błędu kod HTTP zwracany w nagłówku jest adekwatny do zaistniałego błędu, czyli np. 404, 403 itp. W przypadku braku błędu kod HTTP to 200.

Obsługa błędów

W razie wystąpienia błędu status odpowiedzi jest równy „ERROR” natomiast pole „errors” zawiera opis słowny błędu oraz kod błędu, np.

                {"errors":[
                           {"message":"Brak tematu emaila",
                           "code": 1202}
                       ],
               "status":"ERROR"}

lub

               {"errors":[
                          {"message": "Błędny adres odbiorcy",
                            "code": 1201},
                          {"message": "Brak tematu emaila",
                            "code": 1202}
                         ],
                "status":"ERROR"}

Ścieżka dostępu

Każda z akcji jaką można wykonać ma swoją osobną ścieżkę dostępu. Ścieżka zbudowana jest w następujący sposób:

/rest/[Controller]/[Action]/[param]/[param]/[param]

Controller	nazwa kontrolera np. ping, mail, itp.
Action	nazwa akcji w obrębie kontrolera.
param	parametr, nie może zawierać znaku „/”, w większości przypadków dodatkowe parametry GET są zbędne. Jeśli są wymagane to ilość oraz ich format jest podany w opisie akcji.

Ogólne kody błędów

500	Błąd serwera (Internal Server Error).
1000	Brak autoryzacji.
1001	Nie znaleziono kontrolera / akcji.
1002	Nieobsługiwany protokół. Proszę skorzystać z protokołu https.
1003	Nieobsługiwany rodzaj żądania, np. wysłano GET, a oczekiwano POST.
1004	Brak uprawnień do wywołania danego kontrolera/akcji