Sprawdź nazwę dzwoniącego

Pobierz dostępną nazwę dzwoniącego dla numeru telefonu. Jest to zapytanie w środowisku produkcyjnym, które może obciążyć Twoje konto, również wtedy, gdy wynik pochodzi z pamięci podręcznej usługi. Nie zmienia ono nazwy prezentowanej przy połączeniach wychodzących z numeru, który posiadasz.

Zwrócona nazwa nie potwierdza tożsamości, prawa własności do numeru ani zgody na wykonanie połączenia. Nazwy mogą być niedostępne, nieaktualne lub skrócone; zamiast nich mogą też pojawiać się oznaczenia geograficzne albo numer telefonu jako wartość zastępcza.

Żądanie

Korzystaj z aktywnego konta API, wysyłając żądania z dozwolonego dla niego źródłowego adresu IP. Przechowuj dane uwierzytelniające w magazynie sekretów po stronie serwera. W przykładzie użyto zmiennych środowiskowych i fikcyjnego numeru z Ameryki Północnej; nie umieszczaj danych uwierzytelniających w adresach URL ani w publicznie dostępnym kodzie przeglądarkowym.

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  https://api.multitel.net/v3/cnam/12025550123

Podaj pełny numer jako ciąg cyfr wraz z kodem kraju, na przykład jedenaście cyfr rozpoczynających się od 1 dla Ameryki Północnej. Nie zakładaj, że procedura obsługi znormalizuje znaki interpunkcyjne lub znak plus. Nie jest wymagana treść żądania ani wybór regionu. Potwierdź w MultiTEL obsługiwany zasięg dla planowanego zastosowania.

Odpowiedź

Wartości są wyłącznie przykładowe; podany koszt nie stanowi oferty cenowej.

{
  "status": {
    "code": 200,
    "msg": ""
  },
  "response": {
    "number": "12025550123",
    "name": "EXAMPLE NAME",
    "cost": 0.0037,
    "balance": 9.9963
  }
}

Pola zapytania o nazwę dzwoniącego
Pole	Znaczenie
number	Numer wskazany w zapytaniu.
name	Dostępna nazwa lub tekst zastępczy. Nie stanowi to weryfikacji tożsamości.
cost	Cena zapytania skonfigurowana dla konta lub usługi, zgłaszana przez tę ścieżkę przetwarzania. Stosuj aktualną stawkę konta, a nie wartość przykładową.
balance	Saldo obliczone na potrzeby odpowiedzi. Nie jest to nowe transakcyjne zapytanie o saldo konta.

Opłaty i uzgadnianie rozliczeń

Wyniki zawierające nazwę są rozliczane według ceny CNAM skonfigurowanej dla konta. Ponowne zapytanie lub zapytanie obsłużone z pamięci podręcznej może spowodować kolejną opłatę; klucz idempotencji nie jest udostępniany. Sprawdź aktualną stawkę konta przed włączeniem automatycznych zapytań.

Istnieje znane ograniczenie odpowiedzi dotyczące pustej nazwy w pamięci podręcznej: procedura obsługi może zwrócić kod API 200 z pustą nazwą, niezerowym kosztem i pomniejszonym obliczonym saldem, mimo że ta gałąź przetwarzania nie obciąża konta. Nie traktuj samej tej odpowiedzi jako dowodu naliczenia opłaty. Uzgodnij wynik z zapisami rozliczeniowymi konta oraz wynikiem nowego zapytania o saldo, a w razie niejednoznacznych wyników skontaktuj się z pomocą techniczną.

Kontrola środków przedpłaconych wymaga obecnie salda co najmniej 0.004 przed wykonaniem zapytania, niezależnie od skonfigurowanej ceny pojedynczego zapytania. Konto z wyłączonymi zakupami również zostanie odrzucone. Te kontrole nie czynią z tego punktu końcowego interfejsu API do wyceny ani ustalania limitów wydatków.

Błędy i ponawianie zapytań

Sprawdzaj zarówno status HTTP, jak i status.code/status.msg w JSON. Kod API 403 może oznaczać niewystarczające środki przedpłacone, zakaz zakupów, problem z autoryzacją konta lub brak znalezionej nazwy dzwoniącego. Ścieżka bez znalezionej nazwy może zwrócić kod jako ciąg znaków. Sprawdź komunikat, zamiast traktować każdy kod 403 jako informację o błędnych danych uwierzytelniających. Konflikty konfiguracji mogą powodować zwrócenie kodu API 500.

Przekroczenie limitu czasu może nastąpić po wykonaniu płatnego zapytania. Stosuj ograniczoną liczbę ponowień z wydłużającymi się odstępami tylko wtedy, gdy jest to odpowiednie dla Twojej aplikacji, i najpierw uzgodnij rozliczenie prób o niepewnym wyniku. Nie ponawiaj wielokrotnie zapytań o odrzucony numer ani po błędzie uprawnień lub salda konta. Pamięć podręczna odpowiedzi we własnej aplikacji może ograniczyć powtarzające się żądania, z zachowaniem warunków umowy i wymagań dotyczących dokładności.

Inne operacje na numerach

Ta operacja odczytu jest odrębna od aktualizacji nazwy dla połączeń wychodzących lub danych LIDB, wpisu w spisie abonentów czy rejestracji dzwoniącego. Te operacje mają własne wymagane pola, zasady autoryzacji i opłaty. Użyj funkcji sprawdzania zasięgu przydziałów do sprawdzenia tabeli prefiksów lub funkcji wyszukiwania numerów do sprawdzenia numerów dostępnych do zamówienia. Żadna z tych operacji nie potwierdza, że dzwoniący jest osobą, za którą się podaje.