Dokumentacja techniczna asendo API

Transkrypt

1 asendo.pl tel: Dokumentacja techniczna asendo API Spis treści 1. Wprowadzenie Komunikaty Zarządzanie kontaktami Szablony Nadawcy Kampanie asendo Data Pobranie salda Historia zmian

2 1. Wprowadzenie Interfejs Zdalnej Obsługi asendo API przy pomocy protokołu HTTPS umożliwia zdalną komunikację z systemem wysyłek. Dzięki temu możliwe jest wysyłanie, sprawdzanie statusu wysłanych wiadomości , jak również dostęp do innych funkcji bez konieczności logowania się do Panelu Klienta. Komunikacja z platformą asendo.pl odbywa się poprzez wywołanie specjalnego adresu URL metodą POST lub metodą GET z odpowiednimi parametrami. Jako odpowiedź zwracany jest dokument w formacie XML zawierający pobrane dane lub jedynie informujący o wyniku wykonanej operacji. Dedykowanym sposobem przesyłu danych jest opcja POST. W przypadku GET należy pamiętać o odpowiednim kodowaniu parametrów oraz o maksymalnej długości przesyłanych informacji. W celu autoryzacji do systemu wysyłek należy w swoim Panelu Klienta w dziale Moje konto Konto WebAPI stworzyć użytkownika do autoryzacji podając unikalną nazwę i hasło. Maksymalna wielkość pojedynczego zgłoszenia do wysyłki to adresów. Zalecane jest przesyłanie mniejszych porcji danych np odbiorców w jednym zgłoszeniu. Usługa komunikacji zdalnej obsługi dostępna jest pod adresem: /api/ Można również skorzystać z gotowego klienta PHP dostępnego pod adresem: /files/api _php.zip 2

3 2. Komunikaty Status ogólny W przypadku wykonania akcji zapisu lub usunięcia wybranego elementu systemu komunikat zwrotny zawiera ogólny status reprezentujący wykonaną akcję. W przypadku poprawnego wykonania zadania element XML zawiera komunikat OK, w przeciwnym razie generowany jest błąd z kodem identyfikującym przyczynę niepowodzenia. Komunikat błędu W momencie braku określenia akcji, zablokowanego konta lub podania błędnych danych uwierzytelniających, asendo.pl wygeneruje dokument w formacie XML z informacją na temat błędu który wystąpił. Przykładowo w sytuacji podania niewłaściwego loginu lub hasła klient zobaczy następujący komunikat: <asendo username="uzytkownik"> <error id="101">err: Nieprawidlowy login lub haslo</error> Jeśli nie zostanie określona żadna akcja do wykonania, system zwróci komunikat: <asendo username="uzytkownik"> <error id="103">err: Nie okreslono akcji do wykonania</error> Objaśnienie poszczególnych sekcji XML <error></error> Zawiera informację o przyczynie niepowodzenia: id identyfikator błędu 3

4 Lista kodów błędów zwracanych przez API Zwracane błędy przedstawione są w postaci liczbowej i opisowej. Poniżej znajduje się tabela z kodami oraz przyporządkowanymi do nich opisami tekstowymi. Nieujęte poniżej odpowiedzi systemu zwracane są z domyślnymi wartościami opisanymi w odpowiedniej sekcji dokumentacji. Kod Ogólne 100 ERR: Nie podano danych uwierzytelniajacych 101 ERR: Nieprawidlowy login lub haslo 102 ERR: Uzytkownik nie ma uprawnien do korzystania z API 103 ERR: Nie okreslono akcji do wykonania 104 ERR: Niedozwolona wartosc parametru action 105 ERR: Wystąpil problem. Prosimy sprobowac pozniej lub skontaktowac sie z administratorem 106 ERR: Odczekaj sekunde przed kolejnym zapisem 107 ERR: Nie podano wymaganych parametrow 108 ERR: Usluga jest tymczasowa niedostepna 109 ERR: Adres IP zostal zablokowany Grupy i kontakty 200 ERR: Nie podano identyfikatora grupy group_id 201 ERR: Brak grupy o podanym identyfikatorze 202 ERR: Nie podano nazwy grupy 203 ERR: Nazwa grupy jest nieprawidlowa 204 ERR: Grupa o podanej nazwie juz istnieje 205 ERR: Nie podano numeru telefonu, telefonu stacjonarnego lub adresu 206 ERR: Podaj prawidlowy 9 cyfrowy numer telefonu mobilnego 207 ERR: Podaj prawidlowy 9 cyfrowy numer stacjonarny 4

5 208 ERR: Podaj prawidlowy adres 209 ERR: Nie podano identyfikatora kontaktu do usuniecia 210 ERR: Podano nieprawidlowy identyfikator kontaktu Wysyłka wiadomości 301 ERR: Nie podano tematu wiadomosci 302 ERR: Brak identyfikatora nazwy nadawcy 303 ERR: Identyfikator nadawcy jest nieprawidlowy 304 ERR: Nadawca nie jest aktywny lub zweryfikowany 305 ERR: Podano nieprawidlowy identyfikator grup 306 ERR: Nie znaleziono adresu/adresow 307 ERR: Podano nieprawidlowe adresy 308 ERR: Maksymalnie mozna wyslac do odbiorcow 309 ERR: Nie podano tresci wiadomosci 310 ERR: System antyspamowy uznal wiadomosc za potencjalny SPAM 311 ERR: Podana data wysylki jest nieprawidlowa 312 ERR: Twoje saldo jest niewystarczajace Kampanie 401 ERR: Brak identyfikatora kampanii order_id 402 ERR: Nieprawidlowy identyfikator kampanii order_id Szablony 501 ERR: Brak nazwy szablonu lub nazwa jest nieprawidlowa 502 ERR: Brak zawartosci tresci szablonu 503 ERR: Nieprawidlowy identyfikator szablonu template_id Nadawcy 601 ERR: Brak nazwy nadawcy 602 ERR: Brak adresu nadawcy lub adres jest niepoprawny 5

6 603 ERR: Podany nadawca już istnieje 604 ERR: Podana nazwa jest nieprawidlowa 6

7 3. Zarządzanie kontaktami Pobranie listy grup Wywołanie adresu Aby przy pomocy Zdalnej obsługi pobrać listę dostępnych grup kontaktowych należy przesłać określone zgłoszenie protokołem HTTPS metodą POST lub GET. Przykładowo adres w przeglądarce wyglądać może następująco: /api/ /? username=uzytkownik&password=haslo&action=get_groups Dostępne parametry Parametr Typ Przykładowa wartość lub format username String username Login użytkownika WebAPI password String haslo Hasło do konta WebAPI action String get_groups Aby pobrać listę dostępnych grup należy umieścić tutaj get_groups Zwrot odpowiedzi W zależności od przesłanych danych asendo.pl wygeneruje w odpowiedzi dokument w formacie XML z informacją na temat wykonanej akcji. W przypadku prawidłowego pobrania listy grup kontaktowych klient otrzyma przykładowo dane o następującej strukturze: <asendo username="uzytkownik" action="get_groups"> <list> <group group_id="2" count="1" created=" :07:21">Grupa 2</group> <group group_id="1" count="2" created=" :07:21">Grupa 1</group> </list> 7

8 Objaśnienie poszczególnych sekcji XML <list></list> Zawiera listę dostępnych grup <group></group> Zawiera szczegółowe dane grupy: group_id identyfikator count ilość kontaktów wchodzących w skład grupy created data stworzenia w formacie RRRR-MM-DD GG:MM:SS Wartość sekcji stanowi nazwy grupy Oprócz tego może zostać wygenerowany błąd ogólny. Może to nastąpić np. w sytuacji gdy konto użytkownika nie jest aktywne lub wystąpił inny problem opisany w komunikatach błędów. Przykładowo: <asendo username="uzytkownik" action="nieznana-akcja"> <error id="104">err: Niedozwolona wartosc parametru action</error> Zapis nowej grupy Wywołanie adresu Aby przy pomocy Zdalnej obsługi wykonać zapis nowej grupy kontaktowej należy przesłać określone zgłoszenie protokołem HTTPS metodą POST lub GET. Przykładowo adres w przeglądarce wyglądać może następująco: /api/ /? username=uzytkownik&password=haslo&action=add_group&name=kontakty 8

9 Dostępne parametry Parametr Typ Przykładowa wartość lub format username String username Login użytkownika WebAPI password String haslo Hasło do konta WebAPI action String add_group name String Kontakty Aby zapisać nową grupę należy umieścić tutaj add_group Nazwa grupy w postaci znaków alfanumerycznych. Maksymalnie 100 znaków Zwrot odpowiedzi W zależności od przesłanych danych asendo.pl wygeneruje w odpowiedzi dokument w formacie XML z informacją na temat wykonanej akcji. W przypadku prawidłowego zapisu grupy klient otrzyma przykładowo zwrotną informację o następującej strukturze: <asendo username="uzytkownik" action="add_group"> <group group_id="3" name="kontakty" created=" :11:44">OK</group> Objaśnienie poszczególnych sekcji XML <group></group> Zawiera dane zapisanego elementu w systemie: group_id identyfikator grupy name nazwa created data stworzenia w formacie RRRR-MM-DD GG:MM:SS Wartość sekcji stanowi status wykonanej operacji 9

10 Oprócz tego może zostać wygenerowany błąd. Może to nastąpić np. w sytuacji gdy nie podano nazwy grupy lub jest ona nieprawidłowa z powodu błędnych znaków. <asendo username="uzytkownik" action="add_group"> <error id="202">err: Nie podano nazwy grupy</error> Usunięcie wybranej grupy Wywołanie adresu Aby przy pomocy Zdalnej obsługi usunąć wybraną grupę wraz z kontaktami wchodzącymi w jej skład należy przesłać określone zgłoszenie protokołem HTTPS metodą POST lub GET. Przykładowo adres w przeglądarce wyglądać może następująco: /api/ /? username=uzytkownik&password=haslo&action=remove_group&group_id=1 Dostępne parametry Parametr Typ Przykładowa wartość lub format username String username Login użytkownika WebAPI password String haslo Hasło do konta WebAPI action String remove_group group_id Interger 1 Aby usunąć wybraną grupę wraz z kontaktami należy umieścić tutaj remove_group Identyfikator swojej grupy, którą chcemy usunąć 10

11 Zwrot odpowiedzi W zależności od przesłanych danych asendo.pl wygeneruje w odpowiedzi dokument w formacie XML z informacją na temat wykonanej akcji. W przypadku prawidłowego usunięcia grupy klient otrzyma przykładowo informację o następującej strukturze: <asendo username="uzytkownik" action="remove_group"> <group group_id="1">ok</group> Objaśnienie poszczególnych sekcji XML <group></group> Zawiera dane usuniętego elementu: group_id identyfikator grupy Wartość sekcji stanowi status wykonanej operacji Pobranie listy kontaktów Wywołanie adresu Aby przy pomocy Zdalnej obsługi pobrać listę kontaktów należy przesłać określone zgłoszenie protokołem HTTPS metodą POST lub GET. Przykładowo adres w przeglądarce wyglądać może następująco: /api/ /? username=uzytkownik&password=haslo&action=get_contacts&group_id=1 11

12 Dostępne parametry Parametr Typ Przykładowa wartość lub format username String username Login użytkownika WebAPI password String haslo Hasło do konta WebAPI action String get_contacts group_id Interger 1 Aby pobrać kontakty z wybranej grupy należy umieścić tutaj get_contacts Identyfikator swojej grupy, z której chcemy pobrać kontakty Zwrot odpowiedzi W zależności od przesłanych danych asendo.pl wygeneruje w odpowiedzi dokument w formacie XML z informacją na temat wykonanej akcji. W przypadku prawidłowego pobrania listy klient otrzyma przykładowo dokument: <asendo username="uzytkownik" action="get_contacts"> <list group_id="1"> <contact contact_id="2" first_sub_name="" name="" phone="" stationary="" ="test@asendo.pl" created=" :35:14"/> </list> Objaśnienie poszczególnych sekcji XML <list></list> Zawiera listę kontaktów. Dostępne atrybuty: group_id identyfikator grupy kontaktowej <contact></contact> Zawiera szczegółowe dane kontaktu: 12

13 contact_id identyfikator first_sub_name imię i nazwisko name nazwa kontaktu phone telefon mobilny stationary telefon stacjonarny adres created data stworzenia w formacie RRRR-MM-DD GG:MM:SS Zapis kontaktu Wywołanie adresu Aby przy pomocy Zdalnej obsługi wykonać zapis kontaktu należy przesłać określone zgłoszenie protokołem HTTPS metodą POST lub GET. Przykładowo adres w przeglądarce wyglądać może następująco: /api/ /? Dostępne parametry Parametr Typ Przykładowa wartość lub format username String username Login użytkownika WebAPI password String haslo Hasło do konta WebAPI action String add_contact group_id Interger 1 Aby dodać nowy kontakt należy umieścić tutaj add_contact Identyfikator grupy do której chcemy przypisać kontakt String test@asendo.pl Adres kontaktu 13

14 Zwrot odpowiedzi W zależności od przesłanych danych asendo.pl wygeneruje w odpowiedzi dokument w formacie XML z informacją na temat wykonanej akcji. W przypadku prawidłowego zapisu klient otrzyma przykładowo informację o następującej strukturze: <asendo username="uzytkownik" action="add_contact"> <contact contact_id="2" first_sub_name="" name="" phone="" stationary="" ="test@asendo.pl" created=" :02:47">OK</contact> Objaśnienie poszczególnych sekcji XML <contact></contact> Zawiera szczegółowe dane zapisanego elementu: contact_id identyfikator kontaktu first_sub_name imię i nazwisko name nazwa phone telefon mobilny stationary telefon stacjonarny adres created data stworzenia w formacie RRRR-MM-DD GG:MM:SS Wartość sekcji stanowi status wykonanej operacji. Usunięcie kontaktu Wywołanie adresu Aby przy pomocy Zdalnej obsługi usunąć wybrany kontakt należy przesłać określone zgłoszenie protokołem HTTPS metodą POST lub GET. Przykładowo adres w przeglądarce wyglądać może następująco: 14

15 /api/ /? username=uzytkownik&password=haslo&action=remove_contact&contact_id=2 Dostępne parametry Parametr Typ Przykładowa wartość lub format username String username Login użytkownika WebAPI password String haslo Hasło do konta WebAPI action String remove_contact contact_id Interger 2 Aby usunąć kontakt należy umieścić tutaj remove_contact Identyfikator usuwanego kontaktu Zwrot odpowiedzi W zależności od przesłanych danych asendo.pl wygeneruje w odpowiedzi dokument w formacie XML z informacją na temat wykonanej akcji. W przypadku prawidłowego usunięcia klient otrzyma przykładowo poniższą informację: <asendo username="uzytkownik" action="remove_contact"> <contact contact_id="2">ok</contact> Objaśnienie poszczególnych sekcji XML <contact></contact> Zawiera dane dotyczące usuniętego elementu: contact_id identyfikator kontaktu Wartość sekcji stanowi status wykonanej operacji. 15

16 Lista duplikatów Wywołanie adresu Aby przy pomocy Zdalnej obsługi pobrać listę duplikowanych adresów należy przesłać określone zgłoszenie protokołem HTTPS metodą POST lub GET. Przykładowo adres w przeglądarce wyglądać może następująco: /api/ /? username=uzytkownik&password=haslo&action=get_duplicates Lista duplikatów pobierana jest w obrębie danej grupy. Mając więc dwa identyczne adresy w różnych grupach system nie potraktuje kolejnego adresu jako powielenia. Dostępne parametry Parametr Typ Przykładowa wartość lub format username String username Login użytkownika WebAPI password String haslo Hasło do konta WebAPI action String get_duplicates Aby pobrać listę duplikatów należy umieścić tutaj get_duplicates Zwrot odpowiedzi W zależności od przesłanych danych asendo.pl wygeneruje w odpowiedzi dokument w formacie XML z informacją na temat wykonanej akcji. W przypadku prawidłowego pobrania listy klient otrzyma przykładowo zwrotkę o następującej strukturze: <asendo username="uzytkownik" action="get_duplicates"> <list> <contact ="test@asendo.pl" group_id="1" count="1"/> </list> 16

17 Lub gdy nie znaleziono duplikatów: <asendo username="uzytkownik" action="get_duplicates"> <list/> Objaśnienie poszczególnych sekcji XML <list></list> Zawiera listę ewentualnych duplikatów <contact></contact> Zawiera dane dotyczące powielenia: adres group_id identyfikator grupy count ilość powielonych rekordów o takim samym adresie w obrębie tej samej grupy Usunięcie duplikowanych adresów Wywołanie adresu Aby przy pomocy Zdalnej obsługi usunąć powielone adresy należy przesłać określone zgłoszenie protokołem HTTPS metodą POST lub GET. Przykładowo adres w przeglądarce wyglądać może następująco: /api/ /? username=uzytkownik&password=haslo&action=remove_duplicates Usuwanie jest realizowane w obrębie danej grupy. Mając więc dwa identyczne adresy w różnych grupach system nie potraktuje drugiego adresu jako powielenia. 17

18 Dostępne parametry Parametr Typ Przykładowa wartość lub format username String username Login użytkownika WebAPI password String haslo Hasło do konta WebAPI action String remove_duplicates Aby usunąć duplikaty należy umieścić tutaj remove_duplicates Zwrot odpowiedzi W zależności od przesłanych danych asendo.pl wygeneruje w odpowiedzi dokument w formacie XML z informacją na temat wykonanej akcji. W przypadku prawidłowego usunięcia rekordów klient otrzyma przykładowo następującą informację zwrotną: <asendo username="uzytkownik" action="remove_duplicates"> <list> <contact contact_id="2" ="test@asendo.pl"/> </list> Objaśnienie poszczególnych sekcji XML <list></list> Zawiera listę usuniętych duplikatów <contact></contact> Zawiera szczegółowe dane usuniętego rekordu: contact_id identyfikator kontaktu adres 18

19 4. Szablony Pobranie listy dostępnych szablonów Wywołanie adresu Aby przy pomocy Zdalnej obsługi pobrać dostępne szablony należy przesłać określone zgłoszenie protokołem HTTPS metodą POST lub GET. Przykładowo adres w przeglądarce wyglądać może następująco: /api/ /? username=uzytkownik&password=haslo&action=get_templates Dostępne parametry Parametr Typ Przykładowa wartość lub format username String username Login użytkownika WebAPI password String haslo Hasło do konta WebAPI action String get_templates Aby pobrać dostępne szablony należy umieścić tutaj get_templates Zwrot odpowiedzi W zależności od przesłanych danych asendo.pl wygeneruje w odpowiedzi dokument w formacie XML z informacją na temat wykonanej akcji. W przypadku prawidłowego pobrania klient otrzyma przykładowo następującą informację zwrotną: <asendo username="uzytkownik" action="get_templates"> <list> <template template_id="1" name="szablon" created=" :14:11"> <html><![cdata[<p>treść szablonu</p>]]></html> </template> </list> 19

20 Objaśnienie poszczególnych sekcji XML <list></list> Zawiera listę szablonów <template></template> Zawiera szczegółowe dane dotyczące szablonu: template_id identyfikator name nazwa szablonu created data stworzenia w formacie RRRR-MM-DD GG:MM:SS <html></html> Zawartość szablonu Zapis nowego szablonu wiadomości Wywołanie adresu Aby przy pomocy Zdalnej obsługi wykonać zapis szablonu należy przesłać określone zgłoszenie protokołem HTTPS metodą POST lub GET. Przykładowo adres w przeglądarce wyglądać może następująco: /api/ /? username=uzytkownik&password=haslo&action=add_template&name=szablon&html= Wiadomość%20 Dostępne parametry Parametr Typ Przykładowa wartość lub format username String username Login użytkownika WebAPI password String haslo Hasło do konta WebAPI action String add_template Aby zapisać szablon należy umieścić tutaj add_template 20

21 name String Szablon Nazwa szablonu w postaci znaków alfanumerycznych. Maksymalnie 100 znaków html String Wiadomość Treść szablonu Zwrot odpowiedzi W zależności od przesłanych danych asendo.pl wygeneruje w odpowiedzi dokument w formacie XML z informacją na temat wykonanej akcji. W przypadku prawidłowego zapisu nowego szablonu klient otrzyma przykładowo następującą odpowiedź: <asendo username="uzytkownik" action="add_template"> <template template_id="2" name="szablon" created=" :24:56">OK</template> Objaśnienie poszczególnych sekcji XML <template></template> Zawiera dane dotyczące zapisanego szablonu: template_id identyfikator szablonu name - nazwa created data zapisu w formacie RRRR-MM-DD GG:MM:SS 21

22 5. Nadawcy Pobranie listy Wywołanie adresu Aby przy pomocy Zdalnej obsługi pobrać listę nadawców należy przesłać określone zgłoszenie protokołem HTTPS metodą POST lub GET. Przykładowo adres w przeglądarce wyglądać może następująco: /api/ /? username=uzytkownik&password=haslo&action=get_senders Dostępne parametry Parametr Typ Przykładowa wartość lub format username String username Login użytkownika WebAPI password String haslo Hasło do konta WebAPI action String get_senders Aby pobrać listę nadawców należy umieścić tutaj get_senders Zwrot odpowiedzi W zależności od przesłanych danych asendo.pl wygeneruje w odpowiedzi dokument w formacie XML z informacją na temat wykonanej akcji. W przypadku prawidłowego pobrania listy klient otrzyma przykładowo następującą informację zwrotną: <asendo username="uzytkownik" action="get_senders"> <list> <sender sender_id="1" name="tester" ="test@asendo.pl" active="1" created=" :14:47"/> </list> 22

23 Objaśnienie poszczególnych sekcji XML <list></list> Zawiera listę nadawców <sender></sender> Zawiera dane dotyczące nadawcy: sender_id identyfikator name - nazwa - adres active flaga określająca możliwość ustawienia do wysyłki: 0 nie 1 tak created data utworzenia w formacie RRRR-MM-DD GG:MM:SS Zapis nowego nadawcy Wywołanie adresu Aby przy pomocy Zdalnej obsługi stworzyć nowego nadawcę należy przesłać określone zgłoszenie protokołem HTTPS metodą POST lub GET. Przykładowo adres w przeglądarce wyglądać może następująco: /api/ /? Dostępne parametry Parametr Typ Przykładowa wartość lub format username String username Login użytkownika WebAPI password String haslo Hasło do konta WebAPI 23

24 action String add_sender name String Test Aby zapisać nadawcę należy umieścić tutaj add_sender Nazwa nadawcy w postaci ciągu alfanumerycznego, minimum 5 znaków, maksymalnie 60 znaków String test@asendo.pl Adres nadawcy Nowo dodany nadawca wymaga aktywacji, poprzez kliknięcie w link wysłany przez system na podany w żądaniu adres. Zwrot odpowiedzi W zależności od przesłanych danych asendo.pl wygeneruje w odpowiedzi dokument w formacie XML z informacją na temat wykonanej akcji. W przypadku prawidłowego zapisu klient otrzyma przykładowo następującą informację zwrotną: <asendo username="uzytkownik" action="add_sender"> <sender sender_id="2" name="test" ="test@asendo.pl" created=" :47:13">OK</sender> Objaśnienie poszczególnych sekcji XML <sender></sender> Zawiera dane dotyczące zapisanego elementu: sender_id identyfikator nadawcy name nazwa adres created data zapisu w postaci RRRR-MM-DD GG:MM:SS 24

25 6. Kampanie asendo Data Pobranie listy zamówień Wywołanie adresu Aby przy pomocy Zdalnej obsługi pobrać listę zamówionych kampanii należy przesłać określone zgłoszenie protokołem HTTPS metodą POST lub GET. Przykładowo adres w przeglądarce wyglądać może następująco: /api/ /? username=uzytkownik&password=haslo&action=get_campaigns Dostępne parametry Parametr Typ Przykładowa wartość lub format username String username Login użytkownika WebAPI password String haslo Hasło do konta WebAPI action String get_campaigns Aby pobrać dostępne zamówienia należy umieścić tutaj get_campaigns Zwrot odpowiedzi W zależności od przesłanych danych asendo.pl wygeneruje w odpowiedzi dokument w formacie XML ze spisem zamówionych kampanii. W przypadku prawidłowego pobrania klient otrzyma przykładową odpowiedź: <asendo username="uzytkownik" action="get_campaigns"> <list> <order order_id="tta1" count="2" price="0.02" sender="test test@asendo.pl" planned="0" send_date=" :29:00" status="w trakcie realizacji" created=" :28:34"> <html><![cdata[<p>treść wiadomości</p>]]></html> 25

26 </order> </list> Objaśnienie poszczególnych sekcji XML <list></list> Lista zamówionych kampanii <order></order> Szczegółowe informacji dotyczące kampanii: order_id identyfikator zamówienia count ilość odbiorców price koszt kampanii PLN netto sender nadawca wiadomości planned flaga określająca czy wysyłka jest zaplanowana: 0 nie 1 tak send_date data wysyłki w formacie RRRR-MM-DD GG:MM status status kampanii created data zamówienia w formacie RRRR-MM-DD GG:MM:SS <html></html> Zawiera treść przesyłanej wiadomości Pobranie raportu kampanii Wywołanie adresu Raport kampanii pozwala śledzić status wiadomości. Aby przy pomocy Zdalnej obsługi pobrać raport należy przesłać określone zgłoszenie protokołem HTTPS metodą POST lub GET. Przykładowo adres w przeglądarce wyglądać może następująco: /api/ /? username=uzytkownik&password=haslo&action=get_raport&order_id=tta1 26

27 Dostępne parametry Parametr Typ Przykładowa wartość lub format username String username Login użytkownika WebAPI password String haslo Hasło do konta WebAPI action String get_raport Aby pobrać raport należy umieścić tutaj get_raport order_id String TTA1 Identyfikator kampanii Zwrot odpowiedzi W zależności od przesłanych danych asendo.pl wygeneruje w odpowiedzi dokument w formacie XML z informacją na temat wykonanej akcji. W przypadku prawidłowego pobrania raportu klient otrzyma przykładowo następującą informację zwrotną: <asendo username="uzytkownik" action="get_raport"> <order order_id="tta1" count="2" price="0.02" status="w trakcie realizacji" created=" :28:34"> < _id="1" ="odbiorca1@domena.pl" status="w trakcie wysylki" raport_date=" :15:12" readed_date="" reason="" city="" ip="" lng="" lat=""/> < _id="2" ="odbiorca2@domena.pl" status="w trakcie wysylki" raport_date=" :15:10" readed_date="" reason="" city="" ip="" lng="" lat=""/> </order> Objaśnienie poszczególnych sekcji XML <order></order> Szczegóły kampanii: order_id identyfikator zamówienia count ilość odbiorców price koszt kampanii PLN netto status status kampanii 27

28 created data zamówienia w formacie RRRR-MM-DD GG:MM:SS < ></ > Szczegóły wiadomości _id identyfikator wiadomości adres odbiorcy status status wiadomości raport_date data raportu w formacie RRRR-MM-DD GG:MM:SS readed_date data odczytania wiadomości w formacie RRRR-MM-DD GG:MM:SS reason ewentualny powód niedostarczenia/niewysłania wiadomości city dane geolokalizacji dotyczące miejsca odebrania wiadomości ip adres IP osoby odczytującej wiadomość lub adres proxy serwera poczty lat, lng współrzędne dotyczące miejsca odebrania wiadomości Pobranie odpowiedzi Wywołanie adresu Mechanizm ten pozwala na odczytanie odpowiedzi przesłanych przez użytkowników. Aby przy pomocy Zdalnej obsługi pobrać zapisane odpowiedzi należy przesłać określone zgłoszenie protokołem HTTPS metodą POST lub GET. Przykładowo adres w przeglądarce może wyglądać następująco: /api/ /? username=uzytkownik&password=haslo&action=get_answers&order_id=tta1 Dostępne parametry Parametr Typ Przykładowa wartość lub format username String username Login użytkownika WebAPI password String haslo Hasło do konta WebAPI 28

29 action String get_answers Aby pobrać odpowiedzi należy umieścić tutaj get_answers order_id String TTA1 Identyfikator kampanii Zwrot odpowiedzi W zależności od przesłanych danych asendo.pl wygeneruje w odpowiedzi dokument w formacie XML z informacją na temat wykonanej akcji. W przypadku prawidłowego pobrania listy odpowiedzi klient otrzyma informację zwrotną o poniższej strukturze: <asendo username="uzytkownik" action="get_answers"> <order order_id="tta1"> <answer ="test@asendo.pl" subject="temat wiadomości" from="test" created=" :53:34"> <html>><![cdata[treść odpowiedzi]]></html> </answer> </order> Objaśnienie poszczególnych sekcji XML <order></order> Dane dotyczące kampanii: order_id identyfikator zamówienia <answer></answer> Szczegółowe dane odczytanej odpowiedzi: adres nadawcy from nazwa nadawcy subject temat wiadomości created data odebrania raportu w formacie RRRR- MM-DD GG:MM:SS html element zawierający treść odpowiedzi 29

30 Pobranie statystyk kampanii Wywołanie adresu Mechanizm statystyk pozwala śledzić ilość wysłanych, odczytanych lub niedoręczonych wiadomości wybranej kampanii. Aby przy pomocy Zdalnej obsługi pobrać statystyki należy przesłać określone zgłoszenie protokołem HTTPS metodą POST lub GET. Przykładowo adres w przeglądarce wyglądać może następująco: /api/ /? username=uzytkownik&password=haslo&action=get_stats&order_id=tta1 Dostępne parametry Parametr Typ Przykładowa wartość lub format username String username Login użytkownika WebAPI password String haslo Hasło do konta WebAPI action String get_stats Aby pobrać statystyki należy umieścić tutaj get_stats order_id String TTA1 Identyfikator kampanii Zwrot odpowiedzi W zależności od przesłanych danych asendo.pl wygeneruje w odpowiedzi dokument w formacie XML z informacją na temat wykonanej akcji. W przypadku prawidłowego pobrania danych klient otrzyma przykładowo następującą informację zwrotną: <asendo username="uzytkownik" action="get_stats"> <stat order_id="tta1" status="w trakcie realizacji" created=" :28:34"> <readed>0</readed> <noserved>0</noserved> <send>2</send> <nosend>0</nosend> 30

31 <wait>1</wait> </stat> Objaśnienie poszczególnych sekcji XML <stat></stat> Dane dotyczące kampanii: order_id identyfikator zamówienia status status kampanii created data zamówienia w formacie RRRR-MM-DD GG:MM:SS <readed></readed> <noserved></noserved> <send></send> <nosend></nosend> <wait></wait> Ilość odczytanych wiadomości Ilość wiadomości niedostarczonych. Możliwy powód: - brak takiego adresu - odrzucenie przez serwer Ilość wiadomości wysłanych Ilość wiadomości niewysłanych. Możliwy powód: - adres znajduje się na czarnej liście - nieprawidłowy format Ilość wiadomości w trakcie wysyłki (oczekujące na raport) Wysyłka wiadomości Wywołanie adresu Aby przy pomocy Zdalnej obsługi zrealizować wysyłkę wiadomości należy przesłać określone zgłoszenie protokołem HTTPS metodą POST lub GET. Przykładowo adres w przeglądarce wyglądać może następująco: /api/ /? username=uzytkownik&password=haslo&action=send&subject=temat&sender_id=1&r ecipients=odbiorca@domena.pl&message=wiadomość 31

32 Dostępne parametry Parametr Typ Przykładowa wartość lub format username String username Login użytkownika WebAPI password String haslo Hasło do konta WebAPI action String send subject String Temat sender_id Integer 1 recipients String group_id String 1,2 odbiorca@asendo.pl, odbiorca2@asendo.pl Aby wysłać wiadomość należy umieścić tutaj send Temat wiadomości. Maksymalnie można wprowadzić 80 znaków Identyfikator aktywnego nadawcy Lista odbiorców oddzielona przecinkiem Lista grup odbiorców oddzielona przecinkiem message String Wiadomość Treść wiadomości template_id Integer 1 Identyfikator szablonu send_date DateTime :45 test Integer 1 Parametr opcjonalny pozwalający na określenie terminu wysyłki w formacie RRRR-MM-DD GG:MM Parametr opcjonalny, zdefiniowanie wartości 1 powoduje, że na adres podany podczas rejestracji konta zostanie wysłana wiadomość testowa Definiowanie odbiorców Odbiorcę wiadomości możemy zdefiniować na 2 różne sposoby, poprzez: przekazanie listy adresatów oddzielonych przecinkiem w parametrze recipients określenie identyfikatorów grupy/grup w parametrze group_id Wyższy priorytet ma opcja druga. 32

33 Definiowanie treści wiadomości Treść wiadomości możemy zdefiniować na 2 różne sposoby, poprzez: ustalenie treści w parametrze message określenie parametru template_id definiującego szablon wiadomości Wyższy priorytet ma opcja druga. Definiowanie daty wysyłki System pozwala na określenie daty wysyłki. Jeśli data nie zostanie podana kampania zostanie natychmiastowo dodana do kolejki wysyłek. W przypadku zdefiniowania poprawnego parametru send_date wysyłka zostanie przekazana do realizacji w zaplanowanym terminie. Zwrot odpowiedzi W zależności od przesłanych danych asendo.pl wygeneruje w odpowiedzi dokument w formacie XML z informacją na temat wykonanej akcji. W przypadku prawidłowego zamówienia kampanii klient otrzyma przykładowo następującą odpowiedź: <asendo username="uzytkownik" action="send"> <order order_id="tta2" send_date=" :45" price="0.01" created=" :44:44"> <wait count="1"> < >obiorca1@asendo.pl</ > </wait> <nosend count="1"> < reason="konto znajduje się na czarnej liście lub subskrybent nie wyraził zgody na otrzymywanie wiadomości">obiorca2@asendo.pl</ > </nosend> </order> Lub w przypadku wysyłki testowej: <asendo username="test" action="send"> <contact>ok</contact> 33

34 Objaśnienie poszczególnych sekcji XML <order></order> Zawiera dane dotyczące zapisanej kampanii: order_id identyfikator zamówienia send_date data wysyłki w formacie RRRR-MM-DD GG:MM price koszt kampanii PLN netto created data zamówienia w formacie RRRR-MM-DD GG:MM:SS <wait></wait> Wiadomości dodane do kolejki wysyłek. Atrybuty: count ilość wiadomości dodanych do kolejki <nosend></nosend> < ></ > Wiadomości odrzucone. Atrybuty: count ilość wiadomości odrzuconych Element zawierający informacje dotyczące odbiorcy. W przypadku odrzucenia w atrybucie reason podana jest przyczyna odrzucenia wybranego adresu 34

35 7. Pobranie salda Wywołanie adresu Aby przy pomocy Zdalnej obsługi pobrać aktualny stan salda należy przesłać określone zgłoszenie protokołem HTTPS metodą POST lub GET. Przykładowo adres w przeglądarce wyglądać może następująco: /api/ /? username=uzytkownik&password=haslo&action=get_saldo Dostępne parametry Parametr Typ Przykładowa wartość lub format username String username Login użytkownika WebAPI password String Haslo Hasło do konta WebAPI action String get_saldo Aby pobrać stan salda należy umieścić tutaj get_saldo Zwrot odpowiedzi W zależności od przesłanych danych asendo.pl wygeneruje w odpowiedzi dokument w formacie XML z informacją na temat wykonanej akcji. W przypadku prawidłowego pobrania salda klient otrzyma przykładowo następującą informację zwrotną: <asendo username="test" action="get_saldo"> <saldo>88.01</saldo> 35

36 Objaśnienie poszczególnych sekcji XML <saldo></saldo> Zawiera aktualną wartość salda konta w PLN netto 36

37 8. Historia zmian Wersja Pierwsza odsłona zdalnej obsługi API 37