Przejdź do treści

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:

  1. Wysłać request POST by zalogować się (/login) do endpointu e-mailem i hasłem jako metodą uwierzytelnienia.
  2. 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:

  1. W panelu administracyjnym, edytuj użytkownika, dla którego chcesz dodać API Key
  2. Przejdź do sekcji API Keys.
  3. 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.
  4. Kliknij przycisk DODAJ.
  5. Kliknij ikonę oczka by zobaczyć aktualny API Key / user token
  6. Kliknij ikonę trybiku i wybierz Pokaż szczegóły by uzyskać więcej informacji lub usunąć API Key

api-key-add.png

Figure 1.1 Add 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 data
    • total - total number of resources

  • GET single resource:

    • data - resources data
    • links - links to related resources

Każda odpowiedź błędu zawiera następujące właściwości:

  • message - general error message
  • errors - 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ści property mniejszej niż _SEARCH_VALUE_
    • lte lub <= podczas wyszukiwania rekordów o wartości property 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.