Baza numerów Wersja 1.1

Baza numerów Wersja 1.1

SPIS TREŚCI 1. Wprowadzenie 1.1 Adresy URL do połączenia z aplikacją 1.2 Informacje zwrotne wysyłane z API w odpowiedzi na odebrane odwołania I. Zarządzanie grupami Bazy Numerów 2. Zarządzanie grupami bazy numerów 2.1 Pobieranie listy dostępnych grup 2.2 Pobieranie informacji o grupie 2.3 Dodawanie nowej grupy 2.4 Edycja istniejącej grupy 2.5 Usunięcie istniejącej grupy II. Zarządzanie kontaktami Bazy Numerów 3. Zarządzanie kontaktami bazy numerów 3.1 Pobieranie listy kontaktów 3.2 Pobieranie informacji o kontakcie 3.3 Dodawanie kontaktów do Bazy Numerów 3.4 Edytowanie kontaktów znajdujących się w Bazie Numerów 3.5 Usuwanie kontaktów z Bazy Numerów III. PODSUMOWANIE Dodatek Lista kodów błędów Historia zmian ComVision 2013, strona nr: 2/15 ^ idź do spisu treści

1. Wprowadzenie Interfejs API phonebook.do służy do zarządzania listą kontaktów znajdującą się w serwisie SMSAPI w zakładce Baza numerów dla każdego klienta. Dostępne operacje zostały podzielone na dwie podstawowe grupy: Zarządzanie grupami bazy numerów. Zarządzanie kontaktami bazy numerów. 1.1 Adresy URL do połączenia z aplikacją Adresy URL do połączenia z aplikacją zwane dalej Adresem połączenia : - https://ssl.smsapi.pl/phonebook.do - dla połączeń szyfrowanych SSL - https://ssl2.smsapi.pl/phonebook.do - backup dla połączeń szyfrowanych SSL - http://api.smsapi.pl/phonebook.do - dla połączeń standardowych (Niezalecane!) - http://api2.smsapi.pl/phonebook.do - backup dla połączeń standardowych (Niezalecane!) 1.2 Informacje zwrotne wysyłane z API w odpowiedzi na odebrane odwołania Zwrotki z API do obsługi Bazy Numerów są zawsze wysyłane w formacie JSON (wyjątkiem jest błąd ERROR:999). Pełną specyfikację, opis oraz biblioteki i narzędzia pomagające w parsowaniu zwrotek znaleźć można pod adresem http://json.org/json-pl.html Niektóre języki takie jak np. C# czy PHP posiadają wbudowane mechanizmy służące do parsowania JSON'a. Dla API do obsługi Bazy Numerów zdefiniowane są 2 rodzaje zwrotek będących odpowiedziami na wysłane odwołania: 1. Obiekt Grupy zawiera następujące informacje: name nazwa grupy. info informacja, opcjonalne pole tekstowe zawierające krótki opis grupy. numbers_count liczba numerów znajdujących się w danej grupie (dla niektórych operacji pole to może się nie pojawić w Obiekcie Grupy, np. nie pojawia się dla add_group). 2 "name": "nazwa grupy", // string 3 "info": "notka", // string OR null 4 "numbers_count": 0 // integer 5 } 2. Lista Grup jest tablicą zawierającą obiekty grup i znajdują się w niej następujące informacje: count liczba grup. list lista grup w postaci obiektów grup oraz zawierająca następujące informacje: name nazwa grupy. info informacja, opcjonalne pole tekstowe zawierające krótki opis grupy. numbers_count liczba numerów znajdujących się w danej grupie (dla niektórych operacji pole to może się nie pojawić w Obiekcie Grupy, np. nie pojawia się dla add_group). 2 "count":1, // integer Liczba zwróconych grup 3 "list":[ // Array[Group] 4 { 5 "name": "nazwa grupy", // string 6 "info": "notka", // string OR null 7 "numbers_count": 0 // integer 8 }, 9... 10 ] 11 } ComVision 2013, strona nr: 3/15 ^ idź do spisu treści

3. Obiekt Kontaktu zawierające następujące informacje: number numer telefonu. first_name imię kontaktu. last_name nazwisko kontaktu. Info informacja, opcjonalne pole tekstowe zawierające krótki opis kontaktu. birthday data urodzenia. city miasto zamieszkania. gender płeć. date_add data dodania kontaktu. date_mod data ostatniej modyfikacji kontaktu. 2 "number":"48000000000", // string 3 "first_name":"test contact3i53", // string OR null 4 "last_name":null, // string OR null 5 "info":null, // string OR null 6 "birthday":null, // string OR null 7 "city":null, // string OR null 8 "gender":"unknown", //string {male, female, unknown} 9 "date_add":1368539813, //integer 10 "date_mod":1368539813 //integer 11 } 4. Lista Kontaktów jest tablicą zawierającą obiekty kontaktu i znajdują się w niej następujące informacje: total liczba znalezionych kontaktów spełniających kryteria wyszukiwania count liczba kontaktów zwróconych w tablicy list list lista zwróconych kontaktów w postaci tablicy obiektów kontaktu oraz zawierająca następujące informacje: number Numer telefonu. first_name Imię kontaktu. last_name nazwisko kontaktu. Info Informacja, opcjonalne pole tekstowe zawierające krótki opis kontaktu. birthday data urodzenia. city miasto zamieszkania. gender płeć. date_add data dodania kontaktu. date_mod data ostatniej modyfikacji kontaktu. 2 "total": 1234, // integer Liczba znalezionych kontaktów 3 "count": 123, // integer liczba zwróconych kontaktów (w "list":) 4 "list":[ // Array[Contact] 5 { 6 "number":"48000000000", // string 7 "first_name":"test contact3i53", // string OR null 8 "last_name":null, // string OR null 9 "info":null, // string OR null 10 "birthday":null, // string OR null 11 "city":null, // string OR null 12 "gender":"unknown", //string {male, female, unknown} 13 "date_add":1368539813, //integer 14 "date_mod":1368539813 //integer 15 }, 16... 17 ] 18 } 5. Błąd z listy znajdującej się w Dodatek Lista kodów błędów zawierające następujące informację: error kod błędu. message opis błędu. ComVision 2013, strona nr: 4/15 ^ idź do spisu treści

2. Zarządzanie grupami bazy numerów W grupie tej znajdują się następujące operacje do zarządzania grupami: Pobieranie informacji o Grupie Pobieranie listy Grup w Bazie numerów Dodawanie nowej Grupy do Bazy Numerów Edytowanie Grupy znajdującej się w Bazie Numerów Usuwanie Grupy z bazy numerów 2.1 Pobieranie listy dostępnych grup Za pomocą parametru list_groups możliwe jest pobranie listy grup wraz z informacjami o grupach, jako wynik zwracana jest tablica zawierająca Obiekt Grupy dla każdej z istniejących grup. list_groups * nie ma wartości powinien jedynie pojawić się w odwołaniu username=uzytkownik&password=haslomd5&list_groups=1 2 "count":1, // integer Liczba zwróconych grup 3 "list":[ // Array[Group] 4 { 5 "name": "nazwa grupy", // string 6 "info": "notka", // string OR null 7 "numbers_count": 0 // integer 8 }, 9... 10 ] 11 } lub w razie błędu 2.2 Pobieranie informacji o grupie Za pomocą parametru get_group zawierającego nazwę grupy możliwe jest pobranie informacji o danej grupie, jako wynik zwracany jest Obiekt Grupy. get_group * Nazwa grupy kontaktów z książki telefonicznej, o której informacje mają być pobrane ComVision 2013, strona nr: 5/15 ^ idź do spisu treści

username=uzytkownik&password=haslomd5&get_group=grupa 2 "name": "nazwa grupy", // string 3 "info": "notka", // string OR null 4 "numbers_count": 0 // integer 5 } lub w razie wystąpienia błędu 2.3 Dodawanie nowej grupy Za pomocą parametru add_group możliwe jest dodanie nowej grupy kontaktów do bazy numerów, jako wynik zwracany jest Obiekt Grupy jednakże bez informacji o liczbie numerów (numbers_count) ponieważ tworzona grupa jest pusta. add_group * Nazwa nowo tworzonej grupy. Info Opcjonalny opis tworzonej grupy. username=uzytkownik&password=haslomd5&add_group=nowa_grupa&info=_ nowej_grupy 2 "name": "nazwa grupy", // string 3 "info": "notka", // string OR null lub w razie błędu ComVision 2013, strona nr: 6/15 ^ idź do spisu treści

2.4 Edycja istniejącej grupy Za pomocą parametru edit_group możliwe jest edytowanie istniejącej grupy kontaktów (można edytować nazwę i/lub opis grupy). Jako wynik zwracany jest Obiekt Grupy. edit_group * Info Aktualna nazwa grupy, która ma być edytowana. Nowa wartość pola Info. name Nowa nazwa grupy. username=uzytkownik&password=haslomd5&edit_group=nazwa_grupy&info=nowy grupy&name=nowa_nazwa_grupy 2 "name": "nazwa grupy", // string 3 "info": "notka", // string OR null lub w razie błędu ComVision 2013, strona nr: 7/15 ^ idź do spisu treści

2.5 Usunięcie istniejącej grupy Za pomocą parametru delete_group możliwe jest usunięcie wybranej grupy z bazy numerów. Dodatkowe ustawienie parametru remove_contacts spowoduje usunięcie z bazy wszystkich kontaktów znajdujących się w grupie (również z innych grup jeżeli dany kontakt należał do więcej niż jednej grupy). W przypadku nie ustawienia parametru remove_contacts kontakty znajdujące się w usuwanej grupie pozostaną w bazie jako nieprzypisane do żadnej konkretnej grupy (chyba, że należały jednocześnie do innych grup) i będą figurować tylko w grupie Wszyscy. delete_group * remove_contacts Nazwa grupy do skasowania. Ustawienie tego parametru spowoduje całkowite usunięcie z bazy numerów wszystkich kontaktów należących do danej grupy (nawet w przypadku gdy należały jednocześnie do innych grup). username=uzytkownik&password=haslomd5&delete_group=grupa &remove_contacts=1 Obiekt zawierający następujące informacje: - deleted: true - removed_contacts: liczba usuniętych kontaktów np.: 2 "deleted":true, // bool 3 "removed_contacts":0 // Integer Ilość usuniętych kontaktów lub w razie błędu ComVision 2013, strona nr: 8/15 ^ idź do spisu treści

3. Zarządzanie kontaktami bazy numerów W grupie tej znajdują się następujące operacje do zarządzania grupami: Pobieranie informacji o kontakcie Pobieranie listy kontaktów Dodawanie nowego kontaktu do Bazy Numerów Edytowanie kontaktów znajdujących się w Bazie Numerów Usuwanie kontaktów z Bazy Numerów 3.1 Pobieranie listy kontaktów Za pomocą parametru list_contacts możliwe jest pobranie listy kontaktów, opcjonalnie możliwe jest jest ustawienie szeregu parametrów służących do filtrowania i/lub sortowania wynikowej listy. list_contacts * groups text_search gender number order_by order_dir limit offset nie ma wartości powinien jedynie pojawić się w odwołaniu ten określa grupy z jakich mają być pobrane kontakty. Nazwy grup powinny być podane jako lista przedzielone znakami przecinkiem, średnikiem lub dwukropkiem [, ; :] lub jako tablica. Lista wynikowa zawierać będzie kontakty zawierające ciąg znaków znajdujący się w wartości parametru. Działa analogicznie do wyszukiwarki w Bazie Numerów w panelu klienta. filtrujący wyniki po określonej płci. Dopuszczalne są następujące wartości: 0 lub unknown oznaczają płeć nieokreśloną 1, female, f lub kobieta oznaczają kobiety -1, m, male lub mężczyzna oznacza mężczyzn Konkretny numer telefonu, pozwala np. sprawdzić czy dany numer znajduje się w konkretnej grupie kontaktów. Umożliwia sortowanie wyników po jednym z pól first_name oraz last_name. Kierunek sortowanie wyników (malejący lub rosnący). Dostępne są następujące wartości: desc malejące asc -rosnące Określa liczbę zwróconych kontaktów. Domyślnie ustawiona jest wartość 50, maksymalna wartość to 200. Przesunięcie określające od którego kontaktu ma być wyświetlone limit kontaktów np. dla kombinacji limit=100 oraz offset=50 wyświetlone będzie 100 kontaktów rozpoczynając od kontaktu 51. username=uzytkownik&password=haslomd5&list_contacts=1&groups=grupa1;grup a2&text_search=jan&gender=m&order_by=last_name&order_dir=asc&limit=20&offs et=10 2 "total": 1234, // integer Liczba znalezionych kontaktów 3 "count": 123, // integer liczba zwróconych kontaktów (w "list":) 4 "list":[ // Array[Contact] 5 { 6 "number":"48000000000", // string 7 "first_name":"test contact3i53", // string OR null 8 "last_name":null, // string OR null 9 "info":null, // string OR null ComVision 2013, strona nr: 9/15 ^ idź do spisu treści

10 "birthday":null, // string OR null 11 "city":null, // string OR null 12 "gender":"unknown", //string {male, female, unknown} 13 "date_add":1368539813, //integer 14 "date_mod":1368539813 //integer 15 }, 16... 17 ] 18 } lub w razie wystąpienia błędu 3.2 Pobieranie informacji o kontakcie Za pomocą parametru get_contact możliwe jest pobranie informacji o konkretnym kontakcie z bazy numerów. Jako wynik zwracany jest Obiekt Kontaktu get_contact * Numer telefonu dla którego pobrane mają być informacje o kontakcie. username=uzytkownik&password=haslomd5&get_contact=48500501502 2 "number":"48000000000", // string 3 "first_name":"test contact3i53", // string OR null 4 "last_name":null, // string OR null 5 "info":null, // string OR null 6 "birthday":null, // string OR null 7 "city":null, // string OR null 8 "gender":"unknown", //string {male, female, unknown} 9 "date_add":1368539813, //integer 10 "date_mod":1368539813 //integer 11 } lub w razie wystąpienia błędu ComVision 2013, strona nr: 10/15 ^ idź do spisu treści

3.3 Dodawanie kontaktów do Bazy Numerów Za pomocą parametru add_contact możliwe jest dodawanie nowych kontaktów do Bazy Numerów wraz z opcjonalnie szczegółowymi informacjami. add_contact * first_name last_name info gender email birthday city groups Numer dodawanego kontaktu (dla numerów zagranicznych konieczny jest kierunkowy krajowy). Imię dodawanego kontaktu Nazwisko edytowanego kontaktu Dodatkowy opis dodawanego kontaktu Płeć dodawanego kontaktu male -mężczyzna lub female -kobieta Adres e-mail dodawanego kontaktu Data urodzenia dodawanego kontaktu, format daty powinien być zgodny z formatem ustawionym dla danego konta. Jeżeli nie jest zgodny system przeprowadza automatyczna detekcję formatu. Miasto zamieszkania dodawanego kontaktu Grupy do jakich należeć ma dodawany kontakt. Nazwy grup powinny być podane jako lista przedzielone znakami przecinkiem, średnikiem lub dwukropkiem [, ; :] lub jako tablica. username=uzytkownik&password=haslomd5&add_contact=48500501502 lub username=uzytkownik&password=haslomd5&add_contact=48500501502&first_name =Jan&last_name=Kowalski&info=&gender=male&email=jan.kowalski@domain.c om&birthday=23.03.1984&city=gliwice&groups=grupa1,grupa2 2 "number":"48000000000", // string 3 "first_name":"test contact3i53", // string OR null 4 "last_name":null, // string OR null 5 "info":null, // string OR null 6 "birthday":null, // string OR null 7 "city":null, // string OR null 8 "gender":"unknown", //string {male, female, unknown} 9 "date_add":1368539813, //integer 10 "date_mod":1368539813 //integer 11 } lub w razie wystąpienia błędu ComVision 2013, strona nr: 11/15 ^ idź do spisu treści

3.4 Edytowanie kontaktów znajdujących się w Bazie Numerów Za pomocą parametru edit_contact możliwe jest edytowanie kontaktów znajdujących się w Bazie Numerów. W przypadku edycji aktualne wartości poszczególnych parametrów zostaną nadpisane nowymi, pochodzącymi z odwołania. Jeżeli jakiś parametr ma pozostać niezmieniony nie musi pojawiać się w odwołaniu (lub powinien pojawić się z aktualną wartością). edit_contact * first_name last_name info gender email birthday city groups add_to_group remove_from_groups Nazwa użytkownika lub główny adres e-mail przypisany do konta w serwisie SMSAPI Hasło do API które można zmienić w zakładce Ustawienia API Hasło do API. Po rejestracji hasła do API i do Panelu są takie same. Hasło powinno być zakodowane w md5. Numer edytowanego kontaktu (dla numerów zagranicznych konieczny jest kierunkowy krajowy). Imię dodawanego kontaktu Nazwisko edytowanego kontaktu Dodatkowy opis dodawanego kontaktu Płeć dodawanego kontaktu male -mężczyzna lub female -kobieta Adres e-mail dodawanego kontaktu Data urodzenia dodawanego kontaktu, format daty powinien być zgodny z formatem ustawionym dla danego konta. Jeżeli nie jest zgodny system przeprowadza automatyczna detekcję formatu. Miasto zamieszkania dodawanego kontaktu Grupy do jakich należeć ma kontakt. Nazwy grup powinny być podane jako lista przedzielone znakami przecinkiem, średnikiem lub dwukropkiem [, ; :] lub jako tablica. Jeżeli kontakt już należy do jakiś grup to przynależność ta zostanie nadpisana wartością tego parametru. Dodawanie kontaktu do nowych grup. Kontakt zostanie dodany do grup podanych w wartości parametru pozostawiając go jednocześnie w grupach w których już się znajduje. Usuwanie kontaktu z podanych grup. username=uzytkownik&password=haslomd5&edit_contact=48500501502&first_name =Jan&last_name=Kowalski&info=&gender=male&email=jan.kowalski@domena. pl&birthday=23.03.1984&city=gliwice&groups=grupa2 2 "number":"48000000000", // string 3 "first_name":"test contact3i53", // string OR null 4 "last_name":null, // string OR null 5 "info":null, // string OR null 6 "birthday":null, // string OR null 7 "city":null, // string OR null 8 "gender":"unknown", //string {male, female, unknown} 9 "date_add":1368539813, //integer 10 "date_mod":1368539813 //integer 11 } lub w razie wystąpienia błędu ComVision 2013, strona nr: 12/15 ^ idź do spisu treści

3.5 Usuwanie kontaktów z Bazy Numerów Za pomocą parametru delete_contact możliwe jest usunięcie konkretnego kontaktu. Jako wynik zwracana jest wartość true lub odpowiedni kod błędu. delete_contact * rejestracji hasła do API i do Panelu są takie same. Hasło powinno być zakodowane w md5. Numer telefonu dla którego kontakt ma być usunięty z Bazy Numerów. username=uzytkownik&password=haslomd5&delete_contact=48500501502 obiekt: deleted: true np.: 2 "deleted":true // bool 3 } lub w razie wystąpienia błędu ComVision 2013, strona nr: 13/15 ^ idź do spisu treści

Dodatek Lista kodów błędów Tabela kodów błędu: ERROR 101 Niepoprawne lub brak danych autoryzacji. UWAGA! Hasło do API może być inne niż hasło do Panelu Klienta 105 Błędny adres IP (włączony filtr IP dla interfejsu API). 999 Wewnętrzny błąd systemu (prosimy zgłosić) 4000 Ogólny błąd operacji na bazie numerów. 4001 Usługa nie jest dostępna na danym koncie. 4002 Nieprawidłowa operacja 4003 Nieprawidłowe użycie parametru. 4004 Za duża wartość parametru limit (np. dla operacji list_contacts maksymalna wartość wyświetlanych rekordów to 200). 4100 Ogólny błąd operacji na grupach bazy numerów 4101 Grupa o podanej nazwie nie została znaleziona. 4110 Ogólny błąd nazwy grupy bazy numerów. 4111 Nieprawidłowa nazwa grupy. 4112 Nazwa grupy nie może być pusta. 4113 Nazwa grupy za krótka (minimalnie 2 znaki) 4114 Nazwa grupy za długa (maksymalnie 32 znaki) 4115 W nazwie grupy pojawiły się niedozwolone znaki. 4116 Grupa o podanej nazwie już istnieje. 4121 Nieprawidłowa wartość parametru Info dla grupy. 4122 Za długa wartość pola Info dla grupy (maksymalnie 200 znaków) 4200 Ogólny błąd kontaktu bazy numerów. 4201 Kontakt o podanej nazwie nie został odnaleziony. 4210 Ogólny błąd numeru telefonu przydzielonego do kontaktu. 4211 Nieprawidłowy numer. 4212 Kontakt musi zawierać numer telefonu. 4213 Numer jest za krótki. 4214 Numer jest za długi. 4220 Błąd Imienia kontaktu. 4221 Imię za krótkie (minimum 2 znaki) 4222 Imię za długie (maksymalnie 100 znaków) 4230 Błąd Nazwiska kontaktu. 4231 Nazwisko za krótkie (minimum 2 znaki) 4232 Nazwisko za długie (maksymalnie 100 znaków) 4240 Błąd pola Info dla kontaktu. 4241 Za długa wartość pola Info dla kontaktu (maksymalnie 200 znaków) 4250 Błąd adresu e-mail dla kontaktu. 4260 Błąd daty urodzenia kontaktu. 4270 Błąd grupy dla danego kontaktu. ComVision 2013, strona nr: 14/15 ^ idź do spisu treści

4271 Grupa o podanej nazwie dla nie została znaleziona. 4272 Przy operacji na kontaktach wymagana jest nazwa grupy. 4280 Błąd płci kontaktu. Historia zmian Wersja Data Zmiany Wersja 1.1 06.11.2013 1. Dodanie parametrów add_to_groups oraz remove_from_groups w edycji kontaktu z bazy numerów. Wersja 1.0 07.06.2013 1. Pierwsza wersja specyfikacji UWAGA! Najnowsza specyfikacja techniczna SMSAPI znajduje się w zakładce POMOC na stronie http://www.smsapi.pl/ ComVision 2013, strona nr: 15/15 ^ idź do spisu treści