Creare un profilo di registrazione

Creare il profilo una sola volta

Questa richiesta crea un profilo di registrazione locale insieme ai record di identità e di indirizzo presso l'operatore. Iniziare dagli attuali paesi di registrazione, tipi di numero e requisiti. I requisiti dipendono dal paese e dal tipo di numero che si intende registrare.

Una risposta di creazione riuscita non costituisce un'approvazione normativa né l'attivazione del numero. Salvare separatamente l'UUID del documento, l'ID dell'identità e l'ID dell'indirizzo: servono a scopi diversi. Questa richiesta modifica i dati dell'account e non è un'operazione di sola validazione.

Richiesta di creazione

Autenticarsi con il proprio account API MultiTEL abilitato e il relativo indirizzo IP consentito. Gli esempi utilizzano credenziali HTTP Basic memorizzate in variabili d'ambiente. Verificare sia la risposta HTTP sia il campo JSON status.code; una risposta HTTP 200 da sola non dimostra che l'operazione sia riuscita. Tutti i valori di esempio sono fittizi.

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --header 'Content-Type: application/json' \
  --data @registration-profile.json \
  https://api.multitel.net/v3/create_document

{
  "identity_type": "Personal",
  "first_name": "Example",
  "last_name": "Person",
  "phone_number": "12025550123",
  "email": "end-user@example.com",
  "city": "Example City",
  "postal_code": "00000",
  "country": "US",
  "address": "1 Example Street",
  "nationality": "US",
  "signature": "BASE64_PNG_OF_THE_AUTHORIZED_END_USER_SIGNATURE"
}

Il JSON è un profilo Personal illustrativo, non un'identità reale pronta per l'invio. Sostituire i suoi dati e la firma con le informazioni dell'utente finale richieste dalle regole di registrazione selezionate. È supportato anche l'input codificato come form.

Campi del profilo di registrazione
Campo	Obbligatorietà e formato
`identity_type`	Obbligatorio. Utilizzare esattamente il valore Personal o Business; la validazione condizionale dipende dall'uso delle maiuscole.
`first_name, last_name`	Obbligatori, ciascuno di al massimo 64 caratteri. Per un'azienda, fornire i dati del rappresentante richiesti dal paese selezionato.
`phone_number`	Valore telefonico numerico obbligatorio, di almeno otto caratteri. Un numero internazionale composto solo da cifre e comprensivo del prefisso del paese è adatto a questa validazione; si tratta di un numero di contatto, non dell'acquisto di un numero.
`city, postal_code, address`	Obbligatori, ciascuno di al massimo 64 caratteri.
`country`	Codice ISO obbligatorio del paese dell'indirizzo, tratto dal catalogo di registrazione. Il servizio lo risolve nel record del paese presso l'operatore.
`signature`	Dati della firma obbligatori. Il portale attuale fornisce i byte dell'immagine PNG in Base64 senza il prefisso data:image/png;base64,. Ottenere la firma dell'utente finale tramite il proprio flusso di lavoro autorizzato; un segnaposto non vuoto non è una firma valida.
`nationality`	Obbligatorio per Personal, come codice ISO del paese. Non sostituirlo con l'UUID di un paese.
`company_name, incorporation_country`	Obbligatori per Business. La ragione sociale è di al massimo 64 caratteri; incorporation_country è un codice ISO del paese.
`email`	Email di contatto dell'utente finale, facoltativa, di al massimo 254 caratteri. Un'email omessa o vuota non eredita l'email dell'account di base.
`company_reg_number, vat_id, id_number, personal_tax_id, birth_date, description`	Facoltativi in questo gestore, ma il paese/operatore selezionato potrebbe richiederne alcuni. Fornire i formati richiesti per quella registrazione. Le chiamate API dirette non applicano automaticamente tutte le normalizzazioni eseguite dal portale.

Questo gestore v3 diretto richiede i campi dell'indirizzo e crea un indirizzo. Non dare per scontato che l'opzione del portale per rinviare l'indirizzo sia disponibile tramite esso.

Conservare tutti e tre gli identificatori

Di seguito sono mostrati alcuni campi selezionati della risposta; la risposta effettiva contiene anche le informazioni del profilo inviate e i dati della firma. Trattare la risposta completa come riservata.

{
  "status": {
    "code": 200,
    "msg": "Success Create Registration Detail."
  },
  "response": {
    "uuid": "11111111111111111111111111111111",
    "identity_id": "22222222222222222222222222222222",
    "address_id": "33333333333333333333333333333333",
    "country_iso": "US",
    "email": "end-user@example.com"
  }
}

response.uuid identifica il profilo locale. Utilizzarlo con get_document. Nelle risposte di documents e di get_document, lo stesso identificatore del profilo è denominato id.
response.identity_id identifica l'identità da utilizzare in seguito per prove di identità e documenti giustificativi.
response.address_id identifica l'indirizzo creato. Conservarlo separatamente; l'UUID del profilo locale non è un ID di indirizzo. La compatibilità del successivo allegato di una prova di indirizzo per i profili appena creati è ancora in fase di revisione.

I due endpoint di rilettura del profilo non restituiscono identity_id né address_id, quindi conservare la risposta di creazione originale andata a buon fine. Se è andata persa, utilizzare la vista dei documenti nel portale oppure contattare l'assistenza prima di creare un sostituto.

Avanzato: allegare prove già caricate durante la creazione

È possibile fornire identity_encryptfiles e address_encryptfiles come array di ID restituiti da create_encrypt_files. Caricare utilizzando un tipo di prova per la categoria di entità corrispondente, quindi inviare prima della scadenza del riferimento al file, pari a circa 20 minuti. Il gestore di creazione verifica l'account, la categoria e la scadenza di ciascun riferimento fornito.

Questi campi hanno nomi diversi da encrypted_file_ids dell'endpoint di allegato successivo. Durante la creazione, ogni file viene inviato come richiesta di prova separata, anche quando più file condividono lo stesso tipo di prova. Per una prova di identità che deve contenere più file insieme, utilizzare la successiva richiesta create_proof con un unico array. La sola creazione riuscita del profilo non fornisce i risultati di approvazione delle singole prove.

Se una successiva prova di indirizzo viene rifiutata per un indirizzo appena creato, non sostituire l'UUID del profilo né ricreare ripetutamente l'identità. Fermarsi e verificare il profilo nel portale o con l'assistenza. Il percorso di rilettura/ricerca della prova di indirizzo resta una limitazione della revisione.

Errori e creazione parziale

Il codice API 400 copre la validazione dei campi, gli errori di creazione presso l'operatore e gli errori di salvataggio locale. Gli errori di validazione possono comparire come voci indicizzate per campo in response. Il codice 500 è utilizzato per un paese di registrazione non disponibile/non valido, e il codice 404 per riferimenti precaricati mancanti o scaduti. Leggere status.msg oltre al codice.

Il profilo locale e le operazioni presso l'operatore a monte non costituiscono un'unica transazione atomica. Una richiesta non riuscita può lasciare dello stato a monte anche quando nessun profilo locale risulta elencato. Non è esposta alcuna chiave di idempotenza lato client. Dopo un timeout o un errore incerto, ispezionare i profili esistenti e contattare l'assistenza prima di ripetere la creazione; un elenco documents vuoto non è una prova che nulla sia stato creato a monte.