Autenticazione e risposte API

Usa le credenziali API

Invia le richieste v3 tramite HTTPS a https://api.multitel.net. Ogni endpoint di questa guida richiede l'autenticazione. Conserva le credenziali sul tuo server e non inserirle mai nel JavaScript del browser, in pagine pubbliche, screenshot o nel controllo del codice sorgente.

Usa una di queste forme di credenziali:

• HTTP Basic con il nome utente e la password API configurati per il tuo account MultiTEL.
• Token Bearer in un'intestazione Authorization: Bearer YOUR_API_TOKEN, per un account API abilitato configurato per l'autenticazione tramite token. Le richieste con token sono accettate solo dagli indirizzi consentiti per quell'account API.

Se è configurata una lista di indirizzi IP consentiti per il tuo account API, invia tutte le richieste dagli indirizzi consentiti.

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

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

Le variabili in questi esempi sono segnaposto per le credenziali che archivi privatamente nel tuo ambiente.

Gestisci gli errori di autenticazione

Gli errori di autenticazione vengono inviati con stato HTTP 401. Il corpo usa la busta standard, con status.code impostato su 401 e una stringa vuota come response.

• Nessuna credenziale: status.msg è Username and password are required, e la risposta include una sfida di autenticazione Basic.
• Bearer token rifiutato: se l'intestazione Authorization usa lo schema Bearer e il token è sconosciuto, disabilitato o non consentito dal tuo indirizzo, status.msg è Invalid bearer token. Non vengono provate altre credenziali quando è presente un'intestazione Bearer.
• Credenziali Basic non valide: status.msg inizia con A valid username and password pair are required., e la risposta include una sfida di autenticazione Basic. Il messaggio può contenere altro testo diagnostico, quindi non analizzarlo.

Non riprovare automaticamente con le stesse credenziali. Molti tentativi falliti da un indirizzo in un breve periodo possono causare il blocco di ulteriori richieste da quell'indirizzo.

Leggi il corpo della risposta

La maggior parte degli endpoint v3, inclusi getcountries, getstates, getareas e other, restituiscono JSON in questa busta:

{
  "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"
    }
  ]
}

Questa è una risposta illustrativa di elenco paesi, non una dichiarazione sull'inventario o sulle capacità attuali.

Una risposta di errore ha questo aspetto:

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

Se una risposta non può essere codificata, il corpo contiene status.code 500, status.msg Response encoding error, e un oggetto vuoto come response.

L'endpoint legacy GET /v3/countries restituisce {"code": 200, "data": [...]} invece. Controlla la risposta documentata di ciascun endpoint. Se un corpo non è JSON valido, ad esempio dopo un errore imprevisto del server, considera la richiesta come non riuscita e riprova più tardi.

Codici di risultato API e stato HTTP

status.code è il codice di risultato API. Non è lo stato HTTP. Gli errori di autenticazione vengono inviati con HTTP 401. Altrimenti, gli endpoint di ricerca riportano esiti come 404 e 500 solo in status.code e non impostano uno stato HTTP corrispondente. Un risultato di non trovato o parametro mancante può quindi arrivare con uno stato HTTP di successo. Controlla sempre status.code prima di usare response.

Il codice di risultato 500 con il messaggio ISO Code parameter is required significa che manca un parametro obbligatorio. Correggi la richiesta invece di trattarla come un'interruzione del server.

Segui next_function

I risultati della ricerca includono next_function. È un percorso relativo senza barra iniziale, a volte con una stringa di query, come v3/getareas/US o v3/getareas/US?state=NY. Aggiungi come prefisso https://api.multitel.net/ per creare la richiesta successiva e autentica tale richiesta allo stesso modo. I filtri facoltativi inviati, come pid, non vengono riportati in next_function. Aggiungili di nuovo se ne hai bisogno.

Selettore di inventario facoltativo (pid)

getcountries, getstates e getareas accettano un parametro di query facoltativo pid che restringe i risultati a un'unica origine di inventario. Usalo solo con un valore fornito da MultiTEL, nella sua forma numerica o nella sua forma esadecimale di 32 caratteri. Omettilo per l'uso normale. Invia pid nella stringa di query. Se l'endpoint non riconosce o non accetta il valore, lo ignora senza errore e la richiesta si comporta come se pid fosse stato omesso.

Separa la ricerca dagli ordini

Le ricerche di paesi, stati e aree non modificano il tuo account. Il catalogo dei numeri speciali (other) aggiorna i dettagli del catalogo e salva i preventivi di prezzo per il tuo account, ma non effettua un ordine. Nessuna richiesta di ricerca prenota un numero e l'inventario può cambiare tra una richiesta e l'altra. Verifica i requisiti e il prezzo di un numero prima di usare un endpoint di ordinazione.

Per acquisti, assegnazioni, messaggi, invii di fax e altre azioni, segui le regole di ripetizione specifiche di quell'endpoint. Se un'azione scade dopo l'invio, controlla il suo stato o i record del tuo account prima di ripeterla. Una risposta persa non dimostra che l'azione sia fallita.