Mettre à jour une marque de messagerie

Corriger une marque de messagerie existante

Mettez à jour la marque existante lorsque les coordonnées ou l’adresse de l’entreprise changent. Conservez son identifiant de marque ; créer un autre enregistrement n’est pas la bonne manière de corriger les informations d’une entreprise existante. Utilisez un compte API activé, via HTTPS, depuis une adresse IP source autorisée. La marque doit appartenir à ce compte.

Commencez par consulter l’enregistrement actuel. Gardez votre copie locale confidentielle, car elle contient des informations sur l’identité de l’entreprise et ses coordonnées.

curl --silent --show-error --fail-with-body --user "$API_USER:$API_PASSWORD" \
  "https://api.multitel.net/tcr/v2/brand/$BRAND_ID" \
  --output current-brand.json

Conserver les champs actuels de la marque

Préparez brand-update.json à partir de l’enregistrement actuel, en ne sélectionnant que les champs modifiables de la marque. Conservez l’identité de l’entreprise et les autres valeurs requises tout en appliquant la correction souhaitée. N’envoyez pas la réponse GET entière : brandId, les résultats d’identité et d’état, les horodatages et les autres champs réservés aux réponses ne doivent pas figurer dans la mise à jour.

Le schéma de mise à jour exige entityType, displayName, country, email et brandRelationship. Les règles propres à chaque type d’entité restent applicables. Pour une organisation, conservez sa raison sociale, son identifiant fiscal et le pays qui l’a délivré, son adresse et son secteur d’activité, selon le cas. Pour un entrepreneur individuel, conservez plutôt les champs pertinents relatifs au nom de la personne et à ses coordonnées mobiles. Utilisez les valeurs réelles actuelles, et non les valeurs fictives d’un exemple d’enregistrement.

Groupes de champs pour la mise à jour d’une marque
Champs	Utilisation
displayName, email, phone	Nom de marque reconnaissable et coordonnées valides. Longueurs maximales : 255, 100 et 20 caractères. Utilisez le format téléphonique international avec le signe + suivi de l’indicatif du pays.
street, city, state, postalCode, country	Adresse réelle et cohérente de l’entreprise. Limites : 255, 100, 20, 10 et 2 caractères. Utilisez les codes en vigueur des États américains, le cas échéant.
entityType, companyName, ein, einIssuingCountry	Identité juridique. Ces modifications sont soumises à des restrictions lorsque des campagnes ou des procédures d’évaluation externe sont en attente ou actives. Ne supprimez pas des campagnes qui fonctionnent simplement pour contourner une restriction liée à l’identité.
firstName, lastName, mobilePhone, businessContactEmail	Informations d’identité ou coordonnées de vérification, selon le type d’entité. Limites : 100, 100, 20 et 255 caractères.
brandRelationship, vertical	Codes actuels de relation et de secteur d’activité. La relation ne peut être modifiée qu’une fois tous les trois mois. Le formulaire de modification habituel du portail ne permet pas de modifier la relation.
website, altBusinessIdType, altBusinessId, stockSymbol, stockExchange	Site web, autre identifiant d’entreprise et informations de société cotée en bourse, selon le cas. Conservez les valeurs nécessaires à la validation de l’entité.
referenceId, ipAddress	Métadonnées prises en charge pour la référence de l’entreprise et l’adresse IP d’origine. Aucune de ces données ne définit le compte propriétaire ni ne sert de clé d’idempotence pour la requête.

Consultez les catalogues de messagerie à jour pour connaître les codes. Le schéma de mise à jour ne propose pas mock comme moyen de changer l’environnement d’une marque. Utilisez la procédure distincte et examinée de passage de l’environnement de test à la production, plutôt que de modifier cet indicateur lors d’une modification.

Envoyer la correction examinée

curl --silent --show-error --fail-with-body --user "$API_USER:$API_PASSWORD" \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data-binary @brand-update.json \
  "https://api.multitel.net/tcr/v2/brand/$BRAND_ID"

Utilisez une seule clé pour cette mise à jour et conservez les octets exacts du corps de la requête. Réutiliser cette clé avec une méthode, un chemin, des paramètres de requête ou un corps différents provoque un conflit ; reformater le JSON modifie également l’empreinte. Une requête en double dont le traitement est en cours peut renvoyer 409 avec Retry-After. Une requête terminée peut renvoyer à nouveau son résultat enregistré, y compris une erreur. Conservez les détails de la requête lorsque vous cherchez à déterminer son issue après un dépassement de délai, plutôt que de générer automatiquement une nouvelle clé.

Vérifier l’enregistrement sauvegardé et l’état de validation

Une mise à jour réussie renvoie HTTP 200 et directement un objet JSON représentant la marque, sans l’ancienne enveloppe v3 status/response. Vérifiez son brandId, puis récupérez à nouveau la même marque avec GET et comparez les champs concernés. La route publique de mise à jour n’accepte pas l’enveloppe changes/version du portail et ne fournit pas son contrôle de concurrence optimiste. Coordonnez les modifications simultanées ; une clé d’idempotence empêche l’envoi en double, mais pas les modifications d’un autre utilisateur.

Le portail actuel consulte la marque, conserve ses champs modifiables, vérifie la version du formulaire avant l’enregistrement, puis consulte à nouveau le résultat. Il verrouille les champs principaux d’identité juridique lorsqu’il détecte des campagnes actives. Le registre peut imposer des restrictions supplémentaires, notamment celles liées à l’évaluation externe, même si un formulaire permettait de modifier le champ.

Enregistrer les informations corrigées ne demande pas automatiquement une nouvelle vérification d’identité et ne garantit pas l’approbation. Une nouvelle vérification est une action distincte qui peut entraîner des frais ; utilisez le portail pour examiner l’état actuel et confirmer explicitement tout montant annoncé. Les mises à jour ordinaires de marque par PUT ne déclenchent pas de débit d’enregistrement distinct dans le service API actuel. Les frais existants de campagne, de messagerie et les autres frais restent distincts.

Résoudre les erreurs sans créer un enregistrement en double

Consultez le statut HTTP et les détails de l’erreur en JSON. Pour 400, corrigez le champ concerné ou respectez la restriction liée à l’identité ou à la relation. Pour 401, 403 ou 404, vérifiez les identifiants d’authentification, l’adresse IP source autorisée et le compte propriétaire. Pour 429, respectez Retry-After. Une erreur 500 ou 502 peut survenir après que le registre a accepté la mise à jour ; conservez tout requestId et consultez l’enregistrement existant avant un nouvel envoi.

Une réponse de mise à jour non vide mais incomplète peut laisser un instantané local incomplet ; un corps de réponse de succès vide peut laisser subsister d’anciens champs dans l’instantané. Ne déduisez pas que les champs ont été conservés du seul statut de réussite. Récupérez à nouveau la marque complète et faites résoudre toute divergence par l’assistance. Ce guide ne garantit pas l’atomicité des mises à jour du registre, du cache local et de la facturation.