Accesso all’account e al progetto
Usa un account API abilitato tramite HTTPS da un indirizzo IP consentito. Il progetto deve appartenere a tale account e non deve essere stato eliminato. Usa l’identificativo univoco del progetto disponibile nel flusso di gestione dell’ordine di portabilità, non il suo identificativo numerico nel database né un numero di telefono. Applica la codifica URL all’identificativo del progetto quando componi una richiesta.
Preparare l’aggiunta
Questa operazione modifica un progetto di portabilità esistente. Conferma prima i numeri e l’autorizzazione del cliente tramite il tuo flusso di gestione dell’ordine di portabilità. Esprimi ogni numero con tutte le cifre del formato internazionale, rimuovi tu stesso i duplicati e controlla l’elenco dei numeri già presenti nel progetto. Non usare questo endpoint per provare numeri arbitrari.
Il portale attuale convalida e normalizza i numeri prima di chiamare questo percorso. L’endpoint preesistente, se usato direttamente, non offre le stesse garanzie: rimuove gli spazi iniziali e finali dai dati in ingresso, ma non verifica il formato dei numeri di telefono, il codice paese, i duplicati o lo stato del progetto nel flusso di lavoro.
Richiesta POST
Crea un file locale numbers.json con la struttura seguente. I numeri sono fittizi; sostituiscili con numeri autorizzati per il progetto selezionato.
{
"numbers": [
"12025550123",
"12025550124"
],
"isocode": "US"
}curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
--header "Content-Type: application/json" \
--data-binary @numbers.json \
"https://api.multitel.net/v3/lnp/project/$PROJECT_ID/addnumbers"| Campo | Significato |
|---|---|
| numbers | Array obbligatorio e non vuoto di numeri espressi come stringhe, oppure una stringa con un numero per riga. Le voci vuote vengono scartate e gli spazi iniziali e finali vengono rimossi. Il testo separato da virgole non viene suddiviso in numeri distinti. |
| isocode | Codice paese facoltativo per le righe aggiunte. Se omesso o vuoto, viene usata la località del progetto. Il gestore rimuove gli spazi iniziali e finali dal valore fornito, ma non lo converte in maiuscolo né lo convalida. Fornisci tu stesso il codice paese corretto in maiuscolo. |
Per questo esempio usa POST con application/json. Vengono letti anche i dati di un modulo inviati tramite POST. Il metodo non definisce una chiave di idempotenza né una garanzia specifica per questo endpoint sulla dimensione sicura dei lotti; confronta i risultati di lotti gestibili con quanto richiesto, anziché affidarti a un limite ipotizzato.
Risultato riportato
Esempio di risposta fittizia.
{
"status": {
"code": 200,
"msg": "Success add numbers"
},
"response": {
"uniqueid": "PROJECT_EXAMPLE",
"count": 2,
"numbers": [
{
"id": 21,
"number": "12025550123",
"status": 0,
"status_str": "Pending",
"isocode": "US"
},
{
"id": 22,
"number": "12025550124",
"status": 0,
"status_str": "Pending",
"isocode": "US"
}
]
}
}La risposta contrassegna con Pending le aggiunte tentate. Non verifica il risultato di ogni inserimento nel database prima di riportarlo. Pertanto, un conteggio o un identificativo restituito, da soli, non dimostrano che tutte le righe siano state salvate in modo persistente. Un’aggiunta con stato Pending non equivale all’accettazione da parte dell’operatore, a un trasferimento programmato o a un’attivazione completata.
Confrontare i risultati con quanto richiesto prima di riprovare
- Leggi l’elenco dei numeri del progetto prima di aggiungere numeri e conserva i dettagli dell’aggiunta prevista nei tuoi registri delle richieste.
- Invia la richiesta di aggiunta una sola volta.
- Leggi nuovamente l’elenco dei numeri del progetto e confrontalo con ogni numero che intendevi aggiungere. Controlla i duplicati e lo stato di ciascun numero.
- Se la richiesta supera il tempo di attesa, restituisce un errore o riporta un risultato ambiguo, rileggi i dati prima di riprovare. Alcune aggiunte potrebbero essere già presenti.
- Risolvi le righe mancanti o duplicate tramite il flusso di gestione dell’ordine di portabilità o l’assistenza, anziché ripetere alla cieca l’intera richiesta.
Il gestore inserisce le voci una alla volta, senza una transazione né protezione dai duplicati. Un’interruzione può lasciare in essere le scritture precedenti; un inserimento non riuscito che restituisce false può comunque essere incluso nel conteggio riportato. Ripetere una richiesta può aggiungere righe duplicate. Il gestore non registra autonomamente un evento né completa un trasferimento presso l’operatore.
Errori del sistema preesistente
Un metodo diverso da POST restituisce il codice API 403. Un progetto inesistente, eliminato o non appartenente all’account restituisce il codice API 404. Anche dati in ingresso vuoti per i numeri restituiscono il codice API 404. Si applicano l’autenticazione e le restrizioni sull’indirizzo IP di origine. Questi codici del sistema preesistente non dimostrano che, dopo l’inizio dell’elaborazione, non siano già avvenuti inserimenti.
Ambito della fatturazione e del trasferimento
Il gestore esaminato inserisce le righe dei numeri del progetto e non contiene operazioni di addebito diretto sull’account né di invio all’operatore. Questo non rende gratuito il servizio di portabilità nel suo complesso né annulla le tariffe di portabilità concordate. Soddisfa i requisiti di autorizzazione, documentazione e revisione del progetto prima di aspettarti un trasferimento.