Interfejs Simple API służy do szybkiej integracji oprogramowania zewnętrznych dostawców z platformą usługową sieci telefonii internetowej ExtraVoIP.pl.
Komunikacja odbywa się za pośrednictwem sieci Internet, protokołu HTTPS i prostych żądań GET/POST, odpowiedzi zwracane są w formacie JSON.
Autoryzacja
Wszystkie operacje wykonywane są w imieniu użytkownika, każde wywołanie autoryzowane jest loginem i tokenem dostępu API. Aby uzyskać token API użytkownik powinien skontaktować się z działem obsługi klienta. Wszystkie operacje zlecone za pomocą API mają równoważny charakter ze zleceniami złożonymi za pośrednictwem innych kanałów komunikacji i rodzą takie same skutki prawne i finansowe.
Bezpieczeństwo
W razie używania API na stronie WWW należy upewnić się, że wszystkie żądania przesyłane do serwera ExtraVoIP.pl wykonywane są z poziomu własnego serwera, nie zaś z przeglądarki użytkownika końcowego. Wszystkie wywołania API zawierają login i token, czyli parametry wystarczające do wykonywania operacji w imieniu i na koszt użytkownika. Korzystając z API użytkownik oświadcza, że zapoznał się z tym ostrzeżeniem i przyjmuje do wiadomości, że Operator nie będzie ponosić odpowiedzialności za skutki nieprawidłowego korzystania z interfejsu API w tym wyjawienia tokena osobom postronnym.
Opłaty
Korzystanie z interfejsu API jest bezpłatne, wszystkie zlecone operacje np. wykonywanie połączeń realizowane są zgodnie ze standardowymi cenami usług takimi jak przy innych sposobach korzystania z usługi. Opłaty za zrealizowane połączenia obciążają konto użytkownika w imieniu którego zostały wykonane żądania API.
Obsługa błędów
W razie błędu w odpowiedzi zostanie ustalone pole error z wartością 1 oraz pole status zawierające treść komunikatu błędu pozwalającą na określenie przyczyny problemu.
Opcjonalny, login subkonta SIP użytkownika dla którego ma zostać pobrany billing
token
Wymagany, kod dostępu do usługi API
fromdate
Wymagany, data początkowa w formacie SQL (YYYY-MM-DD) okresu za który pobierany jest billing
todate
Opcjonalny, data końcowa w formacie SQL (YYYY-MM-DD) okresu za który pobierany jest billing
direction
Opcjonalny, możliwe wartości: inbound - tylko połączenia przychodzące, outbound - tylko połączenia wychodzące, all (domyślnie) - wszystkie połączenia
show_unanswered
Opcjonalny, wartość 1 lub 0 - czy uwzględnić na liście próby połączeń które nie doszły do skutku (np. nie odebrane), domyślnie 0 (tylko odebrane połączenia)
offset
Opcjonalny, używany do paginacji, liczba początkowych wierszy do pominięcia np. podanie wartości 100 spowoduje pominięcie pierwszych 100 wyników i zwrócenie kolejnych w ilości zgodnej z parametrem limit
limit
Opcjonalny, liczba wierszy odpowiedzi, wartość z zakresu 1-1000, domyślnie 100
Format odpowiedzi:
error : int
Informacja czy wystąpił błąd
status : string
Status realizacji lub komunikat błedu
count : array
Liczba wszystkich wpisów billingowych spełniających zadane kryteria (na potrzeby paginacji)
Wymagany, data początkowa w formacie SQL (YYYY-MM-DD) okresu za który pobierana jest historia płatności
todate
Opcjonalny, data końcowa w formacie SQL (YYYY-MM-DD) okresu za który pobierana jest historia płatności
offset
Opcjonalny, używany do paginacji, liczba początkowych wierszy do pominięcia np. podanie wartości 100 spowoduje pominięcie pierwszych 100 wyników i zwrócenie kolejnych w ilości zgodnej z parametrem limit
limit
Opcjonalny, liczba wierszy odpowiedzi, wartość z zakresu 1-1000, domyślnie 100
UWAGA: Funkcji należy używać z rozwagą, za każdą rejestrację numeru pobierana jest opłata, która nie podlega zwrotowi w sytuacji usunięcia numeru. Wykonanie w pętli 1000 odwołań spowoduje 1000 nieodwołalnych operacji obciążenia konta.
Znaczenie parametrów:
username
Wymagany, login konta SIP użytkownika
token
Wymagany, kod dostępu do usługi API
prefix
Wymagany, krajowa strefa numeracyjna (2 cyfry bez początkowego zera)
unique_order_id
Wymagany, unikalny identyfikator zamówienia klienta, używany do zapobiegania przypadkowym odwołaniom w pętlach
months
Opcjonalny, ilość miesięcy początkowego okresu rezerwacji. Domyślnie 1 miesiąc. Nie wpływa na proces automatycznego przedłużania numeru po upłynięciu wyznaczonego okresu
Wykonanie tej funkcji powoduje zestawienie połączenia na konto użytkownika w sieci ExtraVoIP.pl, po odebraniu użytkownik zostanie połączony z numerem zewnętrznym określonym przez parametr "to". Wywołanie jest nie blokujące - powoduje umieszczenie żądania w kolejce i natychmiast zwraca potwierdzenie (umieszczenia w kolejce), nie czeka na przetworzenie przez system VoIP i zestawienie połączenia oraz nie zwraca statusu samego połączenia.
Wykonanie tej funkcji powoduje zestawienie połączenia pomiędzy dwoma wskazanymi numerami telefonu na koszt użytkownika. Przykładowym zastosowaniem jest umieszczenie na stronie internetowej funkcji pozwalającej na bezpłatne połączenie do firmy, w tym wypadku jedną stroną będzie numer pracownika firmy (np. komórka) a drugą numer telefonu klienta podany w polu na stronie. Opłaty pobierane są z konta użytkownika osobno za każdą stronę połączenia. Wywołanie jest nie blokujące - powoduje umieszczenie żądania w kolejce i natychmiast zwraca potwierdzenie (umieszczenia w kolejce), nie czeka na przetworzenie przez system VoIP i zestawienie połączenia oraz nie zwraca statusu samego połączenia.
Wymagany, unikalny identyfikator połączenia zainicjowanego z poziomu API.
Format odpowiedzi:
error : int
Informacja czy wystąpił błąd
status : string
Status realizacji lub komunikat błedu
call_status_leg_a : string
Status pierwszej strony połączenia, wartości: RINGING, ANSWERED
call_status_leg_b : string
Status drugiej strony połączenia, wartości: NONE (połączenie do strony B nie zostało jeszcze zainicjowane ponieważ nie połączono ze stroną A), RINGING, ANSWERED
Wykonanie tej funkcji powoduje wysłanie SMS. To API jest odpowiednie do wysyłki pojedynczych wiadomości, nie zaś wysyłek masowych. Jeżeli potrzebna jest funkcjonalność wysyłki do wielu odbiorców prosimy o kontakt z działem obsługi klienta.
Wymagany, numer docelowy (tylko cyfry, bez spacji, myślników i innych znaków) np. 501100100
message
Wymagany, 1 do 160 znaków, treść wiadomości zakodowana przy użyciu URL Encoding np. funkcji PHP urlencode($message); Polskie znaki nie są obsługiwane, jeżeli treść będzie zawierać polskie znaki, to zostaną one zamienione na ich łacińskie odpowiedniki bez ogonków (np. Ą na A)
Funkcja pozwala na utworzenie nowej kampanii faksowej i przekazanie jej do wysyłki. Realizacja kampanii faksowej polega na dostarczeniu jednego dokumentu do jednego lub większej liczby odbiorców. Istnieje możliwość określenia momentu rozpoczęcia realizacji kampanii (utworzenie teraz, wysyłka w zaplanowanych godzinach we wskazanych dniach)
Adres URL: https://www.extravoip.pl/api/send_fax
Metoda: POST w formacie multipart/form-data [RFC2388]
Parametry:
username
Wymagany, login konta SIP użytkownika
token
Wymagany, kod dostępu do usługi API
numbers
Wymagany, numery telefonów odbiorców oddzielone znakiem przecinka. Dozwolone są wyłącznie cyfry, bez spacji i znaków specjalnych. Każdy krajowy numer powinien zostać podany w formacie 9-cyfrowym bez wiodącego zera, np. 221234567. Numery zagraniczne muszą być poprzedzone cyframi 00, po których następuje kod kraju i numer abonenta.
delivery_days
Opcjonalny, maska binarna zawierająca dni tygodnia w których ma być prowadzona wysyłka. Przykłady: 1111111 - wysyłka we wszystkie kolejne dni tygodnia, 1000000 - wysyłka tylko w poniedziałek, 0000011 - wysyłka tylko w weekend. Domyślnie wysyłka prowadzona jest bez ograniczeń we wszystkie dni tygodnia.
delivery_hours_from
Opcjonalny, godzina w formacie 24 godzinnym gdzie pierwszą godziną jest 0, od której ma rozpocząć się wysyłka. Domyślna wartość 0.
delivery_hours_to
Opcjonalny, godzina w formacie 24 godzinnym gdzie pierwszą godziną jest 0, do której ma być prowadzona wysyłka. Domyślna wartość 23.
callerid
Opcjonalny, numer telefonu który ma zostać użyty do prezentacji połączenia wychodzącego. Dozwoloną wartością jest jeden z numerów wirtualnego faksu aktywny na koncie użytkownika. W razie nie podania numeru lub podania numeru który nie jest wirtualnym faksem połączenie będzie prezentowane numerem zastrzeżonym. Ze względu na coraz popularniejszą blokadę połączeń przychodzących z numerów zastrzeżonych, w celu maksymalizacji szansy wysyłki faksu zalecamy wypełnienie tego pola.
file
Plik to przesłania, przesyłanie pliku odbywa się zgodnie ze standardem multipart/formdata. Akceptowalny format: PDF, nie zaszyfrowany, bez skryptów, elementów aktywnych i formularzy. Maksymalny rozmiar pliku: 2 MB. Ze względu na specyfikę transmisji faksowej zalecamy użycie jednorodnego białego tła dokumentu.
Format odpowiedzi:
error : int
Informacja czy wystąpił błąd
status : string
Status realizacji lub komunikat błedu
task_id : int
Identyfikator utworzonej kampanii, który można później użyć do sprawdzenia statusu wysyłki
Przykładowy kod aplikacji klienckiej w języku PHP:
W przypadku wysyłek masowych powyżej 50 tys. odbiorców zalecamy podzielenie wysyłki na kilka mniejszych np. po 10 tys. Pozwala to na łatwiejsze zarządzanie kampaniami.
Funkcja pozwala na anulowanie wysyłki wcześniej utworzonej/zaplanowanej kampanii. Dalsza wysyłka zostanie wstrzymana po zakończeniu wszystkich trwających połączeń (jeżeli istnieją), trwające połączenia nie zostaną zerwane.
Opcjonalny, liczba początkowych wierszy do pominięcia w odpowiedzi. Używane do paginacji
limit
Opcjonalny, maksymalna liczba wierszy odpowiedzi (maksymalna dozwolona wartość: 1000). Używane do paginacji
Format odpowiedzi:
error : int
Informacja czy wystąpił błąd
status : string
Status realizacji lub komunikat błedu
count : int
Liczba wszystkich wpisów spełniających zadane kryteria (na potrzeby paginacji)
destinations : array
Lista numerów telefonów wraz ze szczegółowymi informacjami o statusie wysyłki pod każdy z nich. Każdy wiersz zawiera pola:
number : int
Numer telefonu (faksu)
status : string
Status doręczenia, jedna z wartości: PENDING - oczekje na wysyłkę, RUNNING - w trakcie wysyłki, COMPLETED - wysłany, CANCELLED - anulowany przez użytkownika, FAILED - nie udało się wysłać
date_finished : string
Data i godzina zakończenia przetwarzania (np. doręczenia lub ostatniej nieudanej próby wysyłki)
total_pages : int
Liczba stron dokumentu
pages_sent : int
Liczba stron wysłanych
fax_result_code : int
Kod błędu protokołu T.38 lub 0 jeżeli transmisja prawidłowa
sip_term_status : int
Kod statusu SIP ostatniej próby połączenia
calls_time : int
Sumaryczny czas połączeń (w sekundach) z tym numerem
Rezerwuje numer w wybranej strefie numeracyjnej i aktywuje na nim usługę wirtualnego faksu.
Uwaga: Używaj z rozwagą. Każde wywołanie tej funkcji powoduje natychmiastowe obciążenie konta użytkownika. Pobrane w momencie aktywacji numeru środki nie podlegają zwrotowi. W celu uniknięcia przypadkowych zapętleń i powtórzeń przy każdym wywołaniu należy podać unikalny identyfikator zamówienia (uniqueid).
Funkcja pozwala na utworzenie kampanii MassDial i przekazanie jej do realizacji. Kampania składa się z jednego komunikatu ogłosowego odtwarzanego jednemu lub wielu odbiorcom. System realizuje połączenia do kolejnych odbiorców i każdemu z nich odtwarza przekazany komunikat.
Używając tej funkcji użytkownik może określić adres URL pod którym działa jego własna aplikacja, który ma być wywoływany przez serwery ExtraVoIP.pl podczas zestawiania każdego połączenia przychodzącego. Daje to możliwość asynchronicznej integracji z systemem informatycznym użytkownika i wykonywanie określonych działań powiązanych z przychodzącą rozmową. Przykładowym zastosowaniem jest automatyczne pokazanie na ekranie konsultanta informacji o kliencie który właśnie dzwoni, bez konieczności ręcznego wprowadzania danych do systemu CRM.
Dane przesyłane są po zaszyfrowanym połączeniu HTTPS metodą POST pod adres URL ustalony przy użyciu wywołania
update_inbound_callback_url
Przesyłane dane:
src : string
Numer telefonu strony wywołującej połączenie w formacie E.164
dest : string
Numer telefonu pod który kierowane jest połączenie w formacie E.164
uniqueid : string
Unikalny identyfikator połączenia
timestamp : string
Data rozpoczęcia wywołania w formacie YYYY-MM-DD HH:ii:ss
username : string
Nazwa konta użytkownika (właściciela numeru), przydatne dla integratorów obsługujących wielu użytkowników pod jednym zwrotnym URL
checksum : string
Suma kontrolna pozwalająca na weryfikację integralności danych, wartość funkcji md5(token_api + src + dest + uniqueid + timestamp + username)
Oczekiwana odpowiedź: dowolna ze statusem HTTP 200 OK
Wywołanie przesyłane jest jeden raz, bez względu na rezultat, nie będą ponawiane próby transmisji.
Wywołanie zostaje automatycznie zakończone po 1 sekundzie, aby upewnić się że dane zostaną odebrane i obrobione należy upewnić się, że po zerwaniu połączenia przetwarzanie będzie kontynuowane np. używając
Funkcja pozwala ustalić, zmodyfikować lub usunąć adres URL dla wywołań zwrotnych (Inbound Callback)
Pod podany adres URL przesyłane będą informacje o zestawianych połączeniach przychodzących. Pozwala to na łatwą integrację np. z systemami CRM i automatyczne wyświetlanie na ekranie informacji o osobie dzwoniącej.
Wymagany, adres URL do kierowania połączeń zwrotnych. Wymaganym protokołem komunikacji jest HTTPS. Podany adres URL musi być osiągalny i zwrócić w chwili wywołania metody POST kod statusu HTTP 200, w przeciwnym razie nie zostanie zaakceptowany. Aby wyłączyć wywołania zwrotne należy przesłać pusty parametr url
W razie wygenerowania przez żądania API zbyt dużej liczby wywołań w krótkim czasie lub w razie tymczasowego przeciążenia interfejsu API system może zwrócić komunikaty:
Status HTTP 429 Too Many Requests, wraz z polami odpowiedzi JSON error > 0 oraz status z opisem problemu
Status HTTP 503 Service Overloaded, wraz z polami odpowiedzi JSON error > 0 oraz status z opisem problemu
Status HTTP różny od 200, aktualnie nie udokumentowany
W razie wystąpienia wyżej wymienionych oczekiwane jest, że aplikacja klienta zaprzestanie dalszej komunikacji (kierowanie jakichkolwiek żądań także z poziomu innych wątków/procesów, nie tylko obecnego żądania) przez okres minimalny określony w nagłówku HTTP Retry-After lub w razie jego braku nie mniej niż 60 sekund.
Dalsze kierowanie przez aplikacje żądań, nie respektujących wyżej wymienionego komunikatu oraz okresu oczekiwania, spowoduje inkrementalne zwiększanie minimalnego okresu oczekiwania na przywrócenie dostępu do API, co przy kierowaniu dużej ilości żądań może doprowadzić do całkowitego zablokowania dostępu API dla danego adresu IP/konta użytkownika.
Przetestuj usługi za darmo
Aby dalej dzwonić 
