Soumettre un profil d’enregistrement de numéro

Préparer le profil sauvegardé et le numéro

Utilisez cette procédure pour associer un profil d’enregistrement sauvegardé à un numéro acheté et, pour les numéros pris en charge dont l’enregistrement est géré par un opérateur, demander un examen de l’enregistrement. Il ne s’agit pas d’une API d’activation générale pour tous les fournisseurs de numéros. La réussite d’une requête ne prouve ni que les documents sont approuvés ni que le numéro est actif.

Utilisez un compte API MultiTEL activé via HTTPS, avec les identifiants et les restrictions IP configurés pour ce compte. Le profil non supprimé et le numéro acheté et non annulé doivent tous deux appartenir à votre compte.

1. Créez un profil d’enregistrement ou sélectionnez-en un existant. Conservez le uuid du profil local fourni par create_document ; get_document renvoie la même référence locale sous le nom id.
2. Pour une soumission auprès de l’opérateur, le profil doit disposer de ses références d’identité et d’adresse sauvegardées. Joignez les preuves et les documents justificatifs requis en suivant leurs procédures respectives avant la soumission.
3. Vérifiez que le numéro et le profil satisfont aux exigences applicables au pays et au numéro. Ne présumez pas qu’un profil sauvegardé est approuvé pour tous les numéros.

Soumettre l’association

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

Le chemin contient le numéro de téléphone acheté, et non son UUID, un poste PBX ou un identifiant d’identité. Le gestionnaire retire du numéro tous les caractères autres que les chiffres. Utilisez le numéro international complet avec l’indicatif du pays. L’exemple est fictif et doit être remplacé par votre propre numéro et la référence de votre profil local sauvegardé.

Pour les requêtes multipart, un tableau utilise des champs onetime_files[] répétés. Une requête JSON est également acceptée avec Content-Type: application/json ; ses propriétés sont fusionnées avec les données du formulaire. Un champ number peut être fourni dans les données de la requête lorsque le numéro est omis du chemin. Privilégiez le chemin explicite présenté ci-dessus pour éviter toute ambiguïté.

Distinguer l’association de l’approbation

Lisez à la fois le résultat HTTP et le champ JSON status.code. Des erreurs JSON peuvent être renvoyées avec HTTP 200. Une soumission réussie auprès de l’opérateur indique Address verification task created; awaiting carrier review. Cet exemple utilise des références fictives.

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

Les identifiants liés au fournisseur sont des références masquées, et non des identifiants de profil local interchangeables. document_uuid reste la référence du profil local que vous avez soumise. Dans le traitement de ce gestionnaire faisant intervenir l’opérateur, registration_details_id est un hachage supplémentaire de cette référence locale ; ne remplacez pas document_uuid par cette valeur dans les requêtes ultérieures portant sur le profil ou sur une soumission.

Certains numéros attribués utilisent une association locale d’identité plutôt que la création d’une vérification auprès de l’opérateur. Leur résultat en cas de réussite est Identity associated. avec un tableau response vide. Ce résultat ne crée pas de tâche d’examen par l’opérateur et ne vaut pas approbation. Le portail dispose d’une procédure d’association plus récente dont la gestion des fournisseurs et les contrôles de soumissions répétées diffèrent de ceux de ce point de terminaison.

Traiter les erreurs sans créer de tâches en double

Le code API 400 indique l’absence d’un numéro ou d’une référence de profil. Le code 404 concerne un profil ou un numéro indisponible pour le compte, ou un numéro absent de l’inventaire de l’opérateur. Le code 422 peut signaler des références d’identité ou d’adresse manquantes, des exigences du vendeur ou un rejet lors de la validation par l’opérateur. L’absence de configuration de rappel peut produire le code 503, et un échec de transport lors de la création peut produire le code 502. Lisez le message et les éventuels requirement_diagnostics au lieu de traiter tous les échecs de la même manière.

Le traitement faisant intervenir l’opérateur peut mettre à jour les indicateurs locaux d’enregistrement en attente avant la fin de la validation des exigences, des contrôles de configuration de rappel ou de la création de la tâche. Une erreur n’implique donc pas que l’état local est inchangé, et un indicateur d’attente ne prouve pas à lui seul qu’une tâche existe. N’utilisez pas ces indicateurs pour confirmer une approbation ou la remise de la requête.

Le fournisseur peut accepter une tâche même si une opération ultérieure sur la base de données locale échoue, et cette fonction auxiliaire ne vérifie pas le résultat de chaque écriture locale avant de signaler une réussite. Ce gestionnaire ne dispose ni d’un paramètre d’idempotence côté client ni d’une protection contre les soumissions en double. Après un dépassement de délai, une erreur ou un résultat incertain, consultez l’historique d’enregistrement du numéro dans le portail ou contactez l’assistance avant de soumettre à nouveau. L’absence d’un enregistrement local ne prouve pas à elle seule que le fournisseur n’a rien reçu.

Limitation concernant les documents à usage unique

Le gestionnaire accepte onetime_files et transmet chaque chaîne non vide à la relation de fichiers chiffrés de l’opérateur. Il ne recherche pas les enregistrements de téléversement du compte propriétaire et ne convertit pas les identifiants externes masqués de téléversement en identifiants de fichiers du fournisseur. L’audit hors ligne a vérifié le comportement de transmission, sans confirmer que les fichiers étaient effectivement joints auprès de l’opérateur.

Ne présumez pas qu’un identifiant de fichier provenant de create_encrypt_files peut être copié dans ce champ pour mener à bien une procédure d’accord à usage unique. Utilisez le portail ou confirmez auprès de MultiTEL la procédure prise en charge pour les identifiants lorsqu’un numéro exige ces documents. Ce point de l’examen de l’API reste non résolu ; il ne s’agit pas d’un exemple vérifié de bout en bout.

Protéger les informations d’enregistrement

Soumettez uniquement des informations et des documents que vous êtes autorisé à utiliser pour le numéro. Maintenez les références de profil et de vérification associées au bon compte et évitez de consigner l’intégralité des données des requêtes d’enregistrement dans les journaux. Cette requête ne supprime ni ne remplace l’ensemble des preuves ou vérifications antérieures. L’examen par l’opérateur, l’activation et la conservation sont des processus distincts.