Wstęp¶
Tutaj znajdziesz opis API VoIPstudio, które da Ci dostęp do wszystkich zasobów platformy.
Ogólne¶
REST API umożliwia klientom VoIPstudio dostęp do szerokiej gamy zasobów. Nasze API ma ujednolicony format adresowania zasobów URL i używa kodów odpowiedzi HTTP do wskazywania błędów API. Używamy wbudowanych funkcji HTTP, takich jak uwierzytelnianie HTTP i HTTP verbs, które są zrozumiałe dla standardowych klientów HTTP. Obsługujemy udostępnianie zasobów między źródłami, umożliwiając bezpieczną interakcję z naszym interfejsem API z poziomu aplikacji internetowej po stronie klienta. JSON jest zwracany przez wszystkie API responses, w tym błędy.
Zasoby¶
Podstawowy URL dla API to:
https://l7api.com/v1.2/voipstudio/
Uwierzytelnienie¶
Aby zapewnić bezpieczną komunikację, musisz utworzyć klucz API, który będzie używany do autoryzacji interfejsu API.
Przed wysłaniem 'Request' do API musisz najpierw uzyskać API Key
znany także jako user token
by autoryzować Requests
Możesz utworzyć API Key
/ user_token
na dwa sposoby:
- Wysłać request POST by zalogować się (
/login
) doendpointu
e-mailem i hasłem jako metodą uwierzytelnienia. - Użyj interfejsu administratora VoIPstudio bu utowrzyć
API Key
/user_token
.
Poniżej szczegółowe instrukcje::
Logowanie e-mailem i hasłem¶
Żądanie logowania przy użyciu adresu e-mail i hasła:
curl -X POST -H "Content-Type: application/json" \
https://l7api.com/v1.2/voipstudio/login \
-d '{"email":"jsmith@example.com","password":"$ecretPas$$"}'
Przykład żądania HTTP:
POST /v1.2/voipstudio/login HTTP/1.1
Host: l7api.com
Content-Type: application/json
{"email":"jsmith@example.com","password":"$ecretPas$$"}
Przykład pomyślnej odpowiedzi:
{
"message":"Login success",
"user_token":"123456abc993ba5dd8a0e7ce9876543",
"user_id":123456
}
Domyślnie user_token
wygaśnie po 30 minutach nieaktywności (np. brak API requests). Za każdym razem gdy wysyłamy API request, licznik nieaktywności jest kasowany.
Jeśli potrzebujesz tokenów API o dłuższym czasie wygaśnięcia, po uzyskaniu początkowego user_token
za pomocą żądania POST /login
, dodatkowe klucze API mogą być utworzone poprzez wysłanie POST /apitokens
:
curl -X POST -H "Content-Type: application/json" \
-H "X-Auth-Token: 123456abc993ba5dd8a0e7ce9876543" \
https://l7api.com/v1.2/voipstudio/apitokens \
-d '{"name":"Example API App","expiry":604800}'
Przykład pomyślnej odpowiedzi:
{
"data":{
"user_id":123456,
"token":"9843211cb48787655cddb080ebdabced",
"customer_id":521156,
"name":"Example API App",
"host":"8.8.8.8",
"user_agent":"curl/7.58.0",
"expiry":604800,
"last_request_at":null,
"created_at":"2023-02-09 17:20:01"
},
"links":{}
}
Uwaga: aby utworzyć klucz API, który nigdy nie wygaśnie, użyj "expiry":0
w treści żądania do POST /apitokens
.
Pulpit administratora - Tworzenie API Key
¶
Wykonaj poniższe czynności, aby dodać klucz API dla użytkownika:
- W panelu administracyjnym, edytuj użytkownika, dla którego chcesz dodać
API Key
- Przejdź do sekcji
API Keys
. - Nazwij swój
API Key
, nazwa może byc dowolna. Na przykład nazwij go tak jak aplikacje, która będzie używaćAPI Key
. - Kliknij przycisk
DODAJ
. - Kliknij ikonę
oczka
by zobaczyć aktualnyAPI Key
/user token
- Kliknij ikonę
trybiku
i wybierzPokaż szczegóły
by uzyskać więcej informacji lub usunąćAPI Key
HTTP Requests¶
Oczekuje się, że przychodzące żądania obsługiwane przez nasze API będą miały nagłówek X-Auth-Token
z wartością user_token
(API Key) zwróconą z udanej odpowiedzi POST /login
lub POST /apitokens
X-Auth-Token: TOKEN
Przykład uwierzytelnionego żądania:
curl -H "Content-Type: application/json"
-H "X-Auth-Token: 123abc45678def3234sdfgdf3434df3444" \
https://l7api.com/v1.2/voipstudio/cdrs
HTTP Responses¶
VoIPstudio REST API używa konwencjonalnych kodów odpowiedzi HTTP do wskazania powodzenia lub niepowodzenia żądania API. Ogólnie, kody z zakresu 2xx wskazują na sukces, kody z zakresu 4xx wskazują błąd, który nie powiódł się, biorąc pod uwagę podane informacje (np. Pominięto wymagany parametr itp.), A kody z zakresu 5xx wskazują błąd serwera.
Każda pomyślna odpowiedź, w zależności od metody HTTP, zawiera następujące właściwości:
-
GET collection of resources:
data
- an array of resources datatotal
- total number of resources
-
GET single resource:
data
- resources datalinks
- links to related resources
Każda odpowiedź błędu zawiera następujące właściwości:
message
- general error messageerrors
- an array of error messages
Pager¶
Przy zbieraniu danych z endpointów przy pomocy GET https://l7api.com/v1.2/voipstudio/cdrs, pager może być użyty do zwrócenia określonej liczby rekordów z danej strony w zbiorze danych. Aby zastosować pager należy dołączyć do URL następujące parametry ?page=N&limit=Z gdzie N
jest numerem strony a Z
to liczba zwróconych rekordów (maks. 5000).
Filtry¶
Aby filtrować dane, parametr filter
można przekazać jako parametr w adresie url. Wartość parametru „filter” musi być ciągiem zakodowanym w formacie JSON w formacie pokazanym poniżej:
[
{"property":"_PROPERTY_NAME_","operator":"_OPERATOR_","value":"_SEARCH_VALUE_"},
{"property":"_PROPERTY_NAME_","operator":"_OPERATOR_","value":"_SEARCH_VALUE_"}
...
]
Trzy powyższe tokeny _PROPERTY_NAME_
, _OPERATOR_
oraz _VALUE_TO_SEARCH_
powinny być interpretowane jak poniżej:
-
_PROPERTY_NAME_
może to być dowolna właściwość należąca do określonego obiektu punktu końcowego. Zobacz sekcjęZasoby
poniżej, aby uzyskać szczegółowe wyjaśnienie modelu danych dla każdego punktu końcowego. -
_OPERATOR_
może być jednym z:eq
lub=
podczas wyszukiwania rekordów z wartościąproperty
równą_SEARCH_VALUE_
ne
,neq
,<>
lub!=
podczas wyszukiwania rekordów z wartościąproperty
, która NIE równa się z_SEARCH_VALUE_
lt
lub<
podczas wyszukiwania rekordów o wartościproperty
mniejszej niż_SEARCH_VALUE_
lte
lub<=
podczas wyszukiwania rekordów o wartościproperty
mniejszej lub równej niż_SEARCH_VALUE_
gt
lub>
podczas wyszukiwania rekordów z wartościąproperty
większą niż_SEARCH_VALUE_
gte
lub>=
podczas wyszukiwania rekordów z wartościąproperty
większą lub równą_SEARCH_VALUE_
in
podczas wyszukiwania rekordów z wartościąproperty
uwzględnioną w_SEARCH_VALUE_
(Uwaga: wartość wyszukiwania należy przekazać jako tablicę, np .:[ "foo", "bar" ]
)like
podczas wyszukiwania rekordów z wartościąproperty
pasującą do wzorca_SEARCH_VALUE_
notlike
podczas wyszukiwania rekordów z wartościąproperty
NIE pasującą do wzorca z_SEARCH_VALUE_
-
_SEARCH_VALUE_
wartość, którą chcesz wyszukać
Przykład żądania do punktu końcowego / cdrs
wyszukującego połączenia przychodzące (właściwośćdst_id
równa się identyfikatorowi użytkownika) do identyfikatora użytkownika 123456
po 1 września 2018 r .:
curl -u user_id:API_Key -H "Content-Type: application/json" \
https://l7api.com/v1.2/voipstudio/cdrs?filter=[
{"property":"dst_id","operator":"eq","value":"123456"},
{"property":"calldate","operator":"gt","value":"2018-09-01 00:00:00"}
]
Grupowanie¶
Parametr group_by
jest dostępny dla grupowania rekordów po określonej właściwości: GET https://l7api.com/v1.2/voipstudio/cdrs?group_by=src
. Parametr ten powinien być przekazany jako STRING zapytania URL.