Uwierzytelnianie i odpowiedzi API

Użyj danych uwierzytelniających API

Wysyłaj żądania v3 przez HTTPS do https://api.multitel.net. Każdy punkt końcowy w tym przewodniku wymaga uwierzytelnienia. Przechowuj dane uwierzytelniające na swoim serwerze i nigdy nie umieszczaj ich w przeglądarkowym JavaScript, na stronach publicznych, zrzutach ekranu ani w systemach kontroli wersji.

Użyj jednej z tych form danych uwierzytelniających:

• HTTP Basic z nazwą użytkownika API i hasłem skonfigurowanymi dla Twojego konta MultiTEL.
• Token Bearer w nagłówku Authorization: Bearer YOUR_API_TOKEN dla włączonego konta API skonfigurowanego do uwierzytelniania tokenem. Żądania z tokenem są akceptowane wyłącznie z adresów dozwolonych dla tego konta API.

Jeśli skonfigurowano listę dozwolonych IP dla Twojego konta API, wysyłaj wszystkie żądania z dozwolonych adresów.

curl --user "$API_USER:$API_PASSWORD" 'https://api.multitel.net/v3/getcountries'

curl --header "Authorization: Bearer $API_TOKEN" 'https://api.multitel.net/v3/getcountries'

Zmienne w tych przykładach są symbolami zastępczymi dla danych uwierzytelniających, które przechowujesz prywatnie w swoim środowisku.

Obsługuj błędy uwierzytelniania

Błędy uwierzytelniania są wysyłane ze statusem HTTP 401. Treść używa standardowej koperty, przy czym status.code ma wartość 401, a pole response jest pustym ciągiem.

• Brak danych uwierzytelniających: status.msg to Username and password are required, a odpowiedź zawiera wyzwanie uwierzytelniające Basic.
• Token Bearer odrzucony: jeśli nagłówek Authorization używa schematu Bearer i token jest nieznany, wyłączony lub niedozwolony z Twojego adresu, status.msg to Invalid bearer token. Gdy obecny jest nagłówek Bearer, nie są próbowane żadne inne dane uwierzytelniające.
• Nieprawidłowe dane uwierzytelniające Basic: status.msg zaczyna się od A valid username and password pair are required., a odpowiedź zawiera wyzwanie uwierzytelniające Basic. Komunikat może zawierać więcej tekstu diagnostycznego, więc nie parsuj go w kodzie.

Nie ponawiaj automatycznie z tymi samymi danymi uwierzytelniającymi. Wiele nieudanych prób z jednego adresu w krótkim czasie może spowodować zablokowanie dalszych żądań z tego adresu.

Odczytuj treść odpowiedzi

Większość punktów końcowych v3, w tym getcountries, getstates, getareas i other, zwraca JSON w tej kopercie:

{
  "status": {
    "code": 200,
    "msg": "Results: 1",
    "results": 1
  },
  "response": [
    {
      "countrycode": "1",
      "name": "United States",
      "description": "United States",
      "isocode": "US",
      "is_mobile": 0,
      "sms_coverage": 1,
      "latitude": "38.0000",
      "longitude": "-97.0000",
      "next_function": "v3/getareas/US"
    }
  ]
}

To jest przykładowa odpowiedź z listą krajów, a nie stwierdzenie dotyczące bieżących zapasów lub możliwości.

Odpowiedź o błędzie wygląda tak:

{
  "status": {
    "code": 404,
    "msg": "No areas found"
  },
  "response": ""
}

Jeśli odpowiedź nie może zostać zakodowana, treść ma status.code 500, status.msg Response encoding error, a pole response jest pustym obiektem.

Starszy punkt końcowy GET /v3/countries zwraca {"code": 200, "data": [...]} zamiast tego. Sprawdź udokumentowaną odpowiedź każdego punktu końcowego. Jeśli treść nie jest prawidłowym JSON, na przykład po nieoczekiwanej awarii serwera, potraktuj żądanie jako nieudane i ponów później.

Kody wyników API i status HTTP

status.code jest kodem wyniku API. Nie jest to status HTTP. Błędy uwierzytelniania są wysyłane z HTTP 401. W przeciwnym razie punkty końcowe wyszukiwania zgłaszają wyniki takie jak 404 i 500 tylko w status.code i nie ustawiają pasującego statusu HTTP. Wynik nieznalezienia lub brakującego parametru może zatem nadejść z pomyślnym statusem HTTP. Zawsze sprawdzaj status.code przed użyciem response.

Kod wyniku 500 z komunikatem ISO Code parameter is required oznacza, że brakuje wymaganego parametru. Popraw żądanie zamiast traktować je jako awarię serwera.

Podążaj za next_function

Wyniki wyszukiwania zawierają next_function. Jest to ścieżka względna bez wiodącego ukośnika, czasem z ciągiem zapytania, taka jak v3/getareas/US lub v3/getareas/US?state=NY. Poprzedź ją https://api.multitel.net/, aby utworzyć następne żądanie, i uwierzytelnij to żądanie w ten sam sposób. Opcjonalne filtry, które wysłałeś, takie jak pid, nie są przenoszone do next_function. Dodaj je ponownie, jeśli ich potrzebujesz.

Opcjonalny selektor zapasów (pid)

getcountries, getstates i getareas akceptują opcjonalny parametr zapytania pid, który zawęża wyniki do jednego źródła zapasów. Używaj go wyłącznie z wartością dostarczoną przez MultiTEL, w formie liczbowej lub w formie 32-znakowego szesnastkowego zapisu. Pomijaj go przy normalnym użyciu. Wysyłaj pid w ciągu zapytania. Jeśli punkt końcowy nie rozpoznaje lub nie akceptuje wartości, ignoruje ją bez błędu, a żądanie zachowuje się tak, jakby pid został pominięty.

Oddziel wyszukiwanie od zamówień

Wyszukiwania krajów, stanów i obszarów nie zmieniają Twojego konta. Katalog numerów specjalnych (other) odświeża szczegóły katalogu i zapisuje wyceny dla Twojego konta, ale nie składa zamówienia. Żadne żądanie wyszukiwania nie rezerwuje numeru, a zapasy mogą zmieniać się między żądaniami. Przed użyciem punktu końcowego zamówień sprawdź wymagania i cenę numeru.

W przypadku zakupów, przypisań, wiadomości, wysyłek faksów i innych działań przestrzegaj własnych zasad ponawiania tego punktu końcowego. Jeśli działanie przekroczy limit czasu po wysłaniu, sprawdź jego status lub zapisy konta przed jego powtórzeniem. Utracona odpowiedź nie dowodzi, że działanie się nie powiodło.