Scegli un singolo prefisso
Usa le chiamate per individuare paesi e aree di copertura del catalogo, quindi getprefixes senza raggruppamento. Copia il valore del prefisso selezionato nel campo uuid. Se returns_numbers è 0, il prefisso assegna un numero al momento dell’ordine; usa il valore restituito nel campo next_function anziché richiedere un elenco di singoli numeri.
Esplora un gruppo di risultati di dimensioni limitate
Per una ricerca ordinaria, usa compact=1 e indica la dimensione desiderata del gruppo sia nel percorso sia nel parametro di query quantity, come mostrato di seguito. Non esiste un parametro per la pagina o il cursore. Un risultato compatto è un campione; ripetere una richiesta non garantisce una pagina successiva priva di risultati già restituiti. Non interpretare un risultato vuoto o con pochi elementi come il conteggio totale dei numeri in inventario.
Trova una sequenza di cifre facile da ricordare
Specifica number_filter_mode=contains oppure ends_with insieme a number_filter_value. Il valore deve contenere 1–15 cifre. Una ricerca può recuperare gruppi limitati di numeri candidati prima di applicare il filtro, quindi potrebbe non trovare altri numeri corrispondenti in inventario. Se hai bisogno di una fonte supportata che esegua la ricerca richiesta, ottieni un selettore pid da MultiTEL e usa filter_required=1; una selezione assente o non supportata restituisce un errore API.
Esamina il numero selezionato
Leggi number, info.uuid, il valore selezionato di price[].uuid, i nomi delle funzionalità disponibili e i requisiti di registrazione dallo stesso risultato. L’array price può offrire più piani con quantità di canali e tariffe diverse. I campi monetari e le quantità possono essere codificati come stringhe. I metadati facoltativi, incluso info.state, variano tra le fonti; non richiedere una struttura universale per lo stato e non dedurre i prezzi da un ID.
Nel flusso senza streaming, i numeri candidati vengono deduplicati e ripartiti tra le fonti prima che il gruppo selezionato venga ordinato in base al prezzo mensile del primo piano. Altri flussi possono iniziare lo streaming prima, quindi non esiste una garanzia di ordinamento globale o deduplicazione valida per ogni richiesta. Inoltre, l’ordinamento non dimostra che il campione restituito contenga il numero più economico dell’intero catalogo.
Ordina separatamente e verifica l’esito
Una ricerca non acquista né prenota nulla. Conserva gli identificativi del numero e del piano restituiti per la procedura d’ordine con lo stesso account. Esamina il piano effettivo, i requisiti e gli addebiti prima di inviare un ordine. I requisiti di registrazione possono ritardare l’attivazione; un risultato di ricerca non stabilisce alcun termine fisso per l’attivazione.
Richiesta
Usa un account API MultiTEL abilitato: credenziali HTTP Basic per un account con password, oppure Authorization: Bearer per un account con token. Si applicano le autorizzazioni dell’account e le relative restrizioni IP. Consulta le indicazioni comuni sull’autenticazione.
Parametri del percorso e parametri di query dell’URL. Usa GET per la procedura pubblica di ricerca. Il gestore accetta anche determinati valori di modulo/richiesta, ma non è un’API di ricerca con corpo JSON.
curl --fail-with-body --get \
--user "${MULTITEL_API_USERNAME}:${MULTITEL_API_PASSWORD}" \
--data-urlencode "compact=1" \
--data-urlencode "quantity=10" \
"https://api.multitel.net/v3/getnumbers/${PREFIX_ID}/10"| Nome | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
prefix_id | string | Sì | L’ID di un singolo prefisso restituito da una risposta di getprefixes senza raggruppamento. Copialo esattamente; non sostituirlo con l’ID di un paese, di un’area di copertura del catalogo, di un prefisso raggruppato o di un piano tariffario. |
quantity | integer | No | Quantità da recuperare, con valore predefinito 1. I valori non positivi diventano 1. Il solo parametro quantity nel percorso non costituisce un limite complessivo affidabile ai risultati: una ricerca non vincolata a una fonte, senza il parametro di query quantity, può ampliare il recupero e restituire fino a 50 elementi per fonte prima delle altre elaborazioni. Per la normale consultazione di gruppi limitati, usa compact=1 e ripeti la quantità desiderata nella query, come nell’esempio. |
| Nome | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
quantity | integer | No | Dimensione finale richiesta del gruppo di risultati. I valori non vuoti vengono convertiti in interi, con un minimo di 1. Nel flusso senza streaming non vincolato a una fonte, questo limita l’allocazione finale. Non obbliga il servizio a trovare tale quantità di numeri. Le ricerche compatte vincolate a una fonte possono restituire il gruppo compatto della fonte anziché rispettare questo limite. |
compact | string | No | Usa 1, true oppure on per una risposta più piccola senza streaming, con un massimo di 10 elementi per fonte prima dell’allocazione finale. I risultati sono un campione dei numeri attualmente recuperati dall’inventario, non un catalogo completo. |
number_filter_mode | string | No | Modalità facoltativa di ricerca per sequenza di cifre: contains oppure ends_with. Specifica anche number_filter_value. I risultati vengono verificati rispetto alle cifre normalizzate dei numeri di telefono; la ricerca non esamina l’intero inventario per garantire tutte le possibili corrispondenze. |
number_filter_value | string | No | Da 1 a 15 cifre, senza spazi, + o segni di punteggiatura. Gli zeri iniziali sono significativi; invia il valore come testo. |
filter_required | string | No | Avanzato: impostare 1, true, yes oppure on richiede una fonte di inventario esplicitamente selezionata che supporti la modalità di filtro. In caso contrario, l’API restituisce status.code 422. Non è necessario per la normale consultazione del catalogo. |
pid | string | No | Selettore avanzato dell’inventario fornito da MultiTEL. Sono accettate le forme numeriche e quelle esadecimali supportate di 32 caratteri; i valori non riconosciuti vengono ignorati senza segnalazioni. Omettilo per l’uso normale. Non ricavare i selettori dagli ID dei prezzi e non presumere che un selettore arbitrario limiti l’inventario esclusivamente a una fonte. |
Risposta
Un singolo oggetto JSON contenente status e response. In caso di esito positivo, status.code è 200 e response è un array di elementi relativi ai numeri. status.results è il numero di elementi dell’array restituito; status.msg può essere Results: N oppure OK per una risposta in streaming. Senza compact=1, alcune ricerche scrivono l’array response in modo incrementale e terminano con status, quindi attendi il corpo JSON completo. Non si tratta di JSON delimitato da caratteri di nuova riga. Controlla status.code anche quando il trasporto HTTP ha esito positivo. Di seguito sono mostrati i campi tipici; i metadati specifici delle fonti e i campi facoltativi variano. Tratta ogni identificativo come opaco e conserva insieme il numero e il relativo price[].uuid selezionato.
Struttura di risposta a scopo illustrativo; non rappresenta dati reali dell’account né un preventivo attuale.
{
"status": {
"code": 200,
"msg": "Results: 1",
"results": 1
},
"response": [
{
"number": "12125550123",
"info": {
"uuid": "NUMBER_ID_FROM_RESPONSE",
"prefix_uuid": "PREFIX_ID_FROM_RESPONSE",
"area_uuid": "AREA_ID_FROM_RESPONSE",
"country_uuid": "COUNTRY_ID_FROM_RESPONSE",
"country_iso": "US",
"prefix": "+1212",
"name": "Example area",
"state": "US"
},
"price": [
{
"uuid": "PRICE_PLAN_ID_FROM_RESPONSE",
"per_minute": "0.01",
"per_sms": "0",
"per_mms": "0",
"free_minutes": "0",
"setup_price": "1.00",
"monthly_price": "2.00",
"yearly_price": "0",
"channels": "2"
}
],
"contract": {
"term": "1 month",
"renewal": "monthly",
"notice": "none"
},
"restrictions": {
"needs_registration": "0",
"restrictions": ""
},
"features": [
"voice"
],
"overflow": "0"
}
]
}Errori
- 401: autenticazione non riuscita. Credenziali non valide o mancanti e accessi all’account API rifiutati non producono risultati di ricerca.
- 404: Invalid prefix ID, Invalid country, Invalid area oppure No numbers found. Leggi status.msg; una risposta di errore non è un array di numeri.
- 400: NUMBER_FILTER_INVALID in response.code: modalità non valida, valore che non contiene 1–15 cifre oppure filter_required senza che siano presenti sia la modalità sia il valore.
- 422: NUMBER_FILTER_UNSUPPORTED in response.code: il prefisso assegna un numero al momento dell’ordine (reason=order_only_prefix e next_function identifica il percorso per l’ordine), oppure la fonte esplicitamente selezionata non può supportare il filtro richiesto.
Disponibilità ed effetti collaterali
- Questo gestore esegue ricerche e prepara preventivi; non invia ordini di numeri né addebita costi per l’acquisto di numeri. Può aggiornare le cache del catalogo, rimuovere dalla cache i dati di inventario obsoleti, salvare piani tariffari specifici dell’account e scrivere registri delle ricerche.
- La disponibilità è un risultato riferito a un preciso istante, non una prenotazione. Un ordine successivo può non riuscire o restituire una disponibilità diversa. Verifica e riconcilia l’esito dell’ordine prima di tentare nuovamente un acquisto.
- I prezzi sono specifici dell’account. Conserva l’ID del piano selezionato per lo stesso account ed esamina separatamente le condizioni e gli addebiti dell’ordine; questo endpoint da solo non dimostra che un prezzo rimarrà valido fino a un ordine successivo.
- Il numero e i prezzi dell’esempio sono dati fittizi che illustrano la struttura della risposta, non un preventivo reale. Le funzionalità, le quantità di canali, la durata contrattuale e le informazioni sulla registrazione devono essere lette nel risultato effettivamente selezionato.
- Alcune descrizioni dei requisiti di registrazione contengono testo formattato o collegamenti. Tratta le stringhe restituite come dati non attendibili quando le visualizzi nella tua applicazione.
- La disponibilità di numeri mobili e i relativi indicatori dipendono dall’idoneità dell’account e dall’inventario. Un prefisso del catalogo o il solo indicatore is_mobile non determina le funzionalità mobili di uno specifico numero.