Charger les catalogues d’enregistrement pour la messagerie

Charger les choix avant de créer un formulaire d’enregistrement

Utilisez le catalogue actuel d’enregistrement pour la messagerie afin de renseigner les choix plutôt que de coder en dur les valeurs du registre. Pour un formulaire de marque, le portail charge les catalogues du type d’entreprise, du secteur d’activité, du type d’identifiant alternatif d’entreprise, de la relation avec la marque, du pays, de l’État américain et de la place boursière. Pour un formulaire de campagne, il charge les cas d’utilisation, les sous-cas d’utilisation valides et les partenaires de connectivité. Conservez chaque valeur machine renvoyée avec son libellé d’affichage ; utilisez cette valeur, et non un libellé traduit, pour construire une requête ultérieure.

Choisir un catalogue

Traiter directement la réponse TCR

Le corps de la réponse provient directement de l’API TCR. Contrairement à de nombreux anciens points de terminaison /v3, il ne comporte aucune enveloppe supplémentaire status/response. Vérifiez le statut HTTP avant d’interpréter la réponse. Un catalogue peut contenir des libellés textuels ou des définitions structurées ; ne supposez donc pas que toutes les valeurs possèdent les mêmes champs. Si la requête HTTP réussit mais que le corps n’est pas un document JSON valide présentant la structure attendue, signalez l’échec de la consultation au lieu de le remplacer silencieusement par une liste vide.

Distinguer les choix des catalogues de l’éligibilité et de la tarification

Un catalogue général de cas d’utilisation n’indique pas à quels cas d’utilisation une marque donnée est éligible. Le portail actuel vérifie l’éligibilité propre à la marque avant la création d’une campagne et contrôle les exigences des opérateurs sélectionnés. De même, les métadonnées de frais d’un fournisseur ne constituent pas le prix de vente final du compte. Examinez séparément le tarif applicable au compte et les conditions d’enregistrement. Le chargement d’un catalogue ne vaut pas approbation d’une marque, d’une campagne ou d’un numéro de messagerie.

Gérer les catalogues indisponibles

Conservez les données saisies par le client dans le formulaire si une consultation échoue. Affichez l’erreur, respectez Retry-After lorsque cet en-tête est renvoyé, et espacez progressivement les nouvelles tentatives. Ne rechargez pas sans cesse tous les catalogues et ne traitez pas une erreur de limitation du débit ou de transport comme un catalogue vide valide. Cette requête GET ne nécessite pas de clé d’idempotence et n’est pas rejouée depuis le stockage d’idempotence des mutations.

Requête

Utilisez un compte API activé via HTTPS depuis une adresse IP source autorisée. La route actuelle prend en charge la politique d’authentification du compte, notamment l’authentification Basic et les comptes API activés utilisant un jeton au porteur. N’utilisez pas les identifiants du fournisseur.

Effectuez une requête GET avec un nom de catalogue pris en charge dans le chemin. Transmettez les filtres de catalogue applicables dans la chaîne de requête. Aucun corps de requête n’est nécessaire.

curl --fail-with-body --silent --show-error \
  --user "$API_USER:$API_PASSWORD" \
  "https://api.multitel.net/tcr/v2/enum/usecase?validSubUsecase=true"

Réponse

Cette route TCR renvoie directement le corps du registre avec son statut HTTP. Elle n’utilise pas l’ancienne enveloppe status.code/status.msg/response de v3. La structure varie selon le catalogue : certains associent les valeurs à des objets descriptifs, d’autres à des chaînes de caractères. Conservez les clés lisibles par machine lors de l’envoi ultérieur d’un formulaire. L’exemple fictif abrégé de usecase illustre une table de correspondance dont les valeurs sont des objets ; il ne s’agit ni d’un catalogue réel ni d’un schéma dont l’exhaustivité est garantie. Vérifiez à la fois le statut HTTP et la structure JSON attendue.

Structure de réponse donnée à titre d’exemple ; il ne s’agit ni de données réelles d’un compte ni d’un devis actuel.

{
  "2FA": {
    "displayName": "Authentication",
    "description": "Example authentication use case"
  }
}

Erreurs

• 401 : Échec de l’authentification du compte. Vérifiez l’identifiant API, l’état d’activation et les restrictions applicables à l’adresse IP source.
• 400/404 et autres erreurs du registre : Catalogue ou filtre invalide ou indisponible. La route actuelle conserve le statut HTTP et le corps de réponse du service en amont ; il n’existe pas d’enveloppe d’erreur universelle v3.
• 429 : Limite de requêtes du compte ou limite partagée du fournisseur atteinte. Respectez Retry-After et espacez progressivement les nouvelles tentatives.
• 502 : Impossible de joindre le registre. Sa disponibilité est inconnue ; ne présentez pas des choix vides comme un résultat réussi.
• 503 : Le limiteur de requêtes ou le service en amont est indisponible. Examinez le corps et tout en-tête Retry-After avant de réessayer.

Disponibilité et effets de bord

• Dans le parcours examiné, cette requête GET de catalogue ne crée ni marque ni campagne, ne soumet pas d’enregistrement, ne réserve pas de ressource et ne facture pas de frais d’enregistrement. Elle contacte le fournisseur et écrit des enregistrements d’audit des requêtes.
• Les définitions des catalogues et les éventuelles métadonnées de frais du fournisseur ne constituent pas un devis de vente au client. Le portail actuel obtient séparément les prix de vente des campagnes ; l’ancienne fonction auxiliaire getCampaignPrice et les anciennes annotations de prix des énumérations ne doivent pas être considérées comme les conditions tarifaires contractuelles de cette route.
• La présence d’une entrée prise en charge dans un catalogue ne prouve pas qu’une marque donnée est éligible à ce cas d’utilisation. Effectuez la vérification d’éligibilité propre à la marque, remplissez les déclarations, recueillez le consentement et examinez la tarification du compte avant toute requête d’enregistrement ultérieure.