Cercare il nome di un chiamante

Recupera il nome del chiamante disponibile per un numero di telefono. Questa ricerca viene eseguita nell’ambiente di produzione e può comportare un addebito sul tuo account, anche quando il risultato proviene dalla cache del servizio. Non modifica il nome visualizzato per le chiamate in uscita da un numero di tua proprietà.

Il nome restituito non costituisce una verifica dell’identità, della titolarità del numero o del permesso di chiamare. I nomi possono essere assenti, obsoleti, abbreviati, indicare un’area geografica oppure essere sostituiti dal numero di telefono.

Richiesta

Usa il tuo account API abilitato dall’indirizzo IP di origine consentito. Conserva le credenziali in un archivio di segreti sul server. L’esempio utilizza variabili d’ambiente e un numero nordamericano fittizio; non inserire credenziali negli URL o nel codice pubblico eseguito nel browser.

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

Fornisci il numero completo in cifre, incluso il prefisso internazionale: ad esempio, undici cifre che iniziano con 1 per il Nord America. Non fare affidamento sul gestore della richiesta per normalizzare la punteggiatura o il segno più. Non sono necessari un corpo della richiesta né un selettore della regione. Verifica con MultiTEL la copertura supportata per l’uso previsto.

Risposta

I valori sono puramente illustrativi; il costo non costituisce un preventivo.

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

Campi della ricerca del nome del chiamante
Campo	Significato
number	Il numero richiesto.
name	Il nome disponibile o il testo sostitutivo. Non costituisce una verifica dell’identità.
cost	Il prezzo di ricerca configurato per l’account o il servizio, riportato da questo percorso di elaborazione. Usa la tariffa attuale dell’account, non il valore illustrativo.
balance	Il saldo calcolato per la risposta. Non si tratta di una nuova interrogazione transazionale del saldo dell’account.

Addebiti e riconciliazione

I risultati che contengono un nome vengono addebitati alla tariffa CNAM configurata per l’account. Una ricerca ripetuta o servita dalla cache può generare un ulteriore addebito; non viene messa a disposizione alcuna chiave di idempotenza. Verifica la tariffa attuale dell’account prima di abilitare le ricerche automatiche.

Esiste una limitazione nota della risposta quando il nome nella cache è vuoto: il gestore della richiesta può restituire il codice API 200 con un nome vuoto, un costo diverso da zero e un saldo calcolato ridotto, anche se quel ramo di elaborazione non addebita l’account. Non considerare quella sola risposta come prova di un addebito. Esegui la riconciliazione con i registri di fatturazione dell’account e una nuova consultazione del saldo, e contatta l’assistenza in caso di risultati ambigui.

Il controllo del credito prepagato richiede attualmente un saldo di almeno 0.004 prima della ricerca, indipendentemente dal prezzo configurato per ciascuna interrogazione. Viene rifiutato anche un account con gli acquisti disabilitati. Questi controlli non rendono questo endpoint un’API per preventivi o limiti di spesa.

Errori e nuovi tentativi

Controlla sia lo stato HTTP sia status.code/status.msg nella risposta JSON. Il codice API 403 può indicare credito prepagato insufficiente, acquisti non consentiti, un problema di autorizzazione dell’account o l’assenza di un nome del chiamante. Il percorso senza nome può restituire il codice come stringa. Esamina il messaggio invece di interpretare ogni 403 come un problema di credenziali errate. I conflitti di configurazione possono restituire il codice API 500.

Il tempo di attesa può scadere dopo una ricerca addebitabile. Usa un numero limitato di nuovi tentativi con intervalli di attesa crescenti solo quando è appropriato per la tua applicazione e riconcilia prima i tentativi dall’esito incerto. Non riprovare ripetutamente in caso di numero rifiutato o di errore relativo alle autorizzazioni o al saldo dell’account. Una cache delle risposte nella tua applicazione può ridurre le richieste ripetute, nel rispetto del tuo accordo e dei requisiti di accuratezza.

Altre operazioni sui numeri

Questa operazione di lettura è distinta dall’aggiornamento del nome per le chiamate in uscita o del LIDB, dall’inserimento in un elenco telefonico o dalla registrazione del chiamante. Queste operazioni prevedono propri campi obbligatori, autorizzazioni e costi. Usa copertura delle assegnazioni per un controllo nella tabella dei prefissi oppure ricerca dei numeri per consultare i numeri disponibili per l’ordine. Nessuna di queste operazioni dimostra che un chiamante sia chi dichiara di essere.