Inviare un profilo di registrazione per un numero

Preparare il profilo salvato e il numero

Usa questa procedura per associare un profilo di registrazione salvato a un numero acquistato e, per i numeri gestiti tramite operatore che supportano questa funzione, richiedere la verifica della registrazione. Non è un'API di attivazione generale per tutti i fornitori di numeri. L'esito positivo di una richiesta non dimostra che i documenti siano approvati o che il numero sia attivo.

Usa un account API MultiTEL abilitato tramite HTTPS, con le credenziali e le restrizioni IP configurate per tale account. Sia il profilo non eliminato sia il numero acquistato e non annullato devono appartenere al tuo account.

Crea un profilo di registrazione oppure selezionane uno esistente. Conserva il uuid del profilo locale ottenuto da create_document; get_document restituisce lo stesso riferimento locale come id.
Per l'invio tramite operatore, il profilo deve contenere i riferimenti salvati all'identità e all'indirizzo. Allega le necessarie prove documentali e i documenti di supporto tramite le rispettive procedure prima dell'invio.
Verifica che il numero e il profilo soddisfino i requisiti applicabili al paese e al numero. Non presumere che un profilo salvato sia approvato per qualsiasi numero.

Inviare l'associazione

curl --silent --show-error --request POST \
  --user "$API_USER:$API_PASSWORD" \
  --form-string document_uuid="$PROFILE_UUID" \
  --form-string service_description="Example customer support line" \
  https://api.multitel.net/v3/number_identity/12125550123

Il percorso contiene il numero telefonico acquistato, non il suo UUID, un interno PBX o un identificativo di identità. Il gestore rimuove dal numero i caratteri diversi dalle cifre. Usa il numero internazionale completo, incluso il prefisso del paese. L'esempio è fittizio e deve essere sostituito con il tuo numero e il riferimento al profilo locale salvato.

Campi per l'invio della registrazione
Campo	Obbligatorio	Significato
`document_uuid`	Sì	Il valore esatto di uuid del profilo locale salvato. Non usare al suo posto gli identificativi remoti mascherati identity_id o address_id, un identificativo di caricamento o un valore registration_details_id restituito.
`service_description`	No	Una descrizione del servizio previsto, inoltrata per la verifica tramite operatore. Gli spazi iniziali e finali vengono rimossi.
`onetime_files`	Dipende dalla procedura	Un array accettato per i documenti monouso dell'operatore. Il gestore attuale rimuove gli spazi iniziali e finali dalle stringhe e le inoltra senza risolvere i riferimenti locali ai caricamenti. La compatibilità con gli identificativi mascherati restituiti da create_encrypt_files non è stata accertata; prima di usare questo campo, consulta la limitazione relativa ai documenti monouso riportata di seguito.

Nelle richieste multipart, un array usa campi onetime_files[] ripetuti. È accettata anche una richiesta JSON con Content-Type: application/json; le sue proprietà vengono unite al corpo dei dati del modulo. Il campo number può essere fornito nel corpo della richiesta quando il numero è omesso dal percorso. Per evitare ambiguità, preferisci il percorso esplicito mostrato sopra.

Distinguere l'associazione dall'approvazione

Leggi sia l'esito HTTP sia il campo JSON status.code. Gli errori JSON possono arrivare con HTTP 200. Un esito positivo tramite operatore riporta Address verification task created; awaiting carrier review. Questo esempio usa riferimenti fittizi.

{
  "status": {
    "code": 200,
    "msg": "Address verification task created; awaiting carrier review."
  },
  "response": {
    "number": "+12125550123",
    "did_id": "11111111111111111111111111111111",
    "document_uuid": "0123456789abcdef0123456789abcdef",
    "identity_id": "22222222222222222222222222222222",
    "address_id": "33333333333333333333333333333333",
    "address_verification_id": "44444444444444444444444444444444",
    "verification_status": "pending",
    "verification_reference": null,
    "requirement_id": "55555555555555555555555555555555",
    "registration_details_id": "8516ac99dc60603295de7bdb6a153530"
  }
}

Gli identificativi relativi al fornitore sono riferimenti mascherati, non identificativi di profili locali utilizzabili in modo intercambiabile. document_uuid rimane il riferimento al profilo locale che hai inviato. Nel percorso di questo gestore che passa tramite operatore, registration_details_id è un ulteriore hash di tale riferimento locale; non usarlo al posto di document_uuid nelle successive richieste relative al profilo o all'invio.

Per alcuni numeri assegnati viene usata un'associazione locale dell'identità anziché la creazione di una verifica presso l'operatore. Il loro esito positivo è Identity associated. con un array response vuoto. Questo esito non crea un'attività di verifica presso l'operatore e non attesta un'approvazione. Il portale dispone di una procedura di associazione più recente, la cui gestione dei fornitori e i cui controlli sugli invii ripetuti differiscono da quelli di questo endpoint.

Gestire gli errori senza creare attività duplicate

Il codice API 400 indica l'assenza del numero o del riferimento al profilo. Il codice 404 indica un profilo o un numero non disponibile per l'account, oppure un numero assente dall'inventario dell'operatore. Il codice 422 può segnalare riferimenti mancanti all'identità o all'indirizzo, requisiti del venditore o un rifiuto in fase di convalida da parte dell'operatore. L'assenza della configurazione di richiamata può produrre 503 e un errore di trasporto durante la creazione può produrre 502. Leggi il messaggio e gli eventuali requirement_diagnostics anziché trattare ogni errore allo stesso modo.

Il percorso tramite operatore può aggiornare gli indicatori locali di registrazione in sospeso prima che si concludano la convalida dei requisiti, i controlli sulla configurazione di richiamata o la creazione dell'attività. Un errore, quindi, non implica che lo stato locale sia rimasto invariato e un indicatore di attesa, da solo, non dimostra che esista un'attività. Non usare questi indicatori come conferma dell'approvazione o della consegna della richiesta.

Il fornitore può accettare un'attività anche se una successiva operazione sul database locale fallisce, e questa funzione ausiliaria non controlla l'esito di ogni scrittura locale prima di segnalare un risultato positivo. Questo gestore non prevede un parametro di idempotenza del client né una protezione dagli invii duplicati. Dopo un timeout, un errore o un risultato incerto, controlla la cronologia di registrazione del numero nel portale oppure contatta l'assistenza prima di ripetere l'invio. L'assenza di un record locale non dimostra di per sé che il fornitore non abbia ricevuto nulla.

Limitazione relativa ai documenti monouso

Il gestore accetta onetime_files e inoltra ogni stringa non vuota nella relazione dei file crittografati dell'operatore. Non cerca le righe dei caricamenti dell'account proprietario e non converte gli identificativi esterni mascherati dei caricamenti in identificativi dei file del fornitore. La verifica offline ha accertato il comportamento di inoltro, non la corretta associazione degli allegati presso l'operatore.

Non presumere che un identificativo di file ottenuto da create_encrypt_files possa essere copiato in questo campo per completare una procedura di accordo una tantum. Quando un numero richiede questi documenti, usa il portale oppure verifica con MultiTEL la procedura supportata per gli identificativi. Questo aspetto della revisione dell'API resta irrisolto e non costituisce un esempio verificato dall'inizio alla fine.

Proteggere le informazioni di registrazione

Invia solo informazioni e documenti che sei autorizzato a usare per il numero. Mantieni i riferimenti al profilo e alle verifiche associati all'account corretto ed evita di registrare nei log l'intero contenuto delle richieste di registrazione. Questa richiesta non elimina né sostituisce tutte le prove documentali o le verifiche precedenti. La verifica da parte dell'operatore, l'attivazione e la conservazione sono processi distinti.