Aggiornare un marchio per la messaggistica

Correggere un marchio di messaggistica esistente

Aggiornare il marchio esistente quando cambiano i recapiti aziendali o un indirizzo. Mantenere il suo identificativo; creare un’altra registrazione non è il modo corretto per rettificare i dati di un’attività esistente. Utilizzare un account API abilitato tramite HTTPS da un indirizzo IP di origine consentito. Il marchio deve appartenere a tale account.

Iniziare leggendo il record attuale. Mantenere riservata la copia locale, perché contiene dati identificativi e di contatto dell’attività.

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

Conservare i campi attuali del marchio

Preparare brand-update.json a partire dal record attuale, selezionando soltanto i campi del marchio scrivibili. Conservare i dati identificativi dell’attività e gli altri valori obbligatori mentre si applica la correzione desiderata. Non inviare l’intera risposta GET: brandId, i risultati relativi all’identità e allo stato, le marche temporali e gli altri campi presenti soltanto nella risposta non devono essere inclusi nell’aggiornamento.

Lo schema di aggiornamento richiede entityType, displayName, country, email e brandRelationship. Restano valide le regole specifiche per il tipo di soggetto. Per un’organizzazione, conservare la ragione sociale, l’identificativo fiscale e il paese che lo ha rilasciato, l’indirizzo e il settore di attività, secondo il caso. Per un’impresa individuale, conservare invece i campi pertinenti relativi al nome della persona e al recapito mobile. Utilizzare i valori reali attuali, non i segnaposto di un esempio di registrazione.

Gruppi di campi per l’aggiornamento del marchio
Campi	Come utilizzarli
displayName, email, phone	Nome riconoscibile del marchio e recapiti validi. Lunghezze massime: 255, 100 e 20 caratteri. Utilizzare il formato telefonico internazionale con + seguito dal prefisso del paese.
street, city, state, postalCode, country	Indirizzo aziendale reale con dati coerenti. Limiti: 255, 100, 20, 10 e 2 caratteri. Utilizzare i codici attuali degli stati degli Stati Uniti, ove applicabile.
entityType, companyName, ein, einIssuingCountry	Identità giuridica. Queste modifiche sono soggette a restrizioni quando campagne o verifiche esterne sono in sospeso o attive. Non eliminare campagne funzionanti soltanto per aggirare una restrizione sull’identità.
firstName, lastName, mobilePhone, businessContactEmail	Dati identificativi o recapiti per la verifica, ove appropriati al tipo di soggetto. Limiti: 100, 100, 20 e 255 caratteri.
brandRelationship, vertical	Codici attuali della relazione e del settore di attività. La relazione può essere modificata al massimo una volta ogni tre mesi. Il normale modulo di modifica del portale non consente di cambiare la relazione.
website, altBusinessIdType, altBusinessId, stockSymbol, stockExchange	Sito web, dati identificativi aziendali alternativi e dati della società quotata, ove applicabili. Conservare i valori necessari per la convalida del soggetto.
referenceId, ipAddress	Metadati supportati relativi al riferimento aziendale e all’IP di origine. Nessuno dei due determina l’appartenenza all’account né funge da chiave di idempotenza della richiesta.

Utilizzare gli attuali cataloghi di messaggistica per i codici. Lo schema di aggiornamento non prevede l’uso di mock per cambiare l’ambiente di un marchio. Utilizzare il flusso separato e sottoposto a revisione per il passaggio dall’ambiente di prova a quello di produzione, anziché modificare tale indicatore durante una modifica.

Inviare la correzione esaminata

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"

Utilizzare una sola chiave per questo aggiornamento e conservare esattamente i byte del corpo della richiesta. Riutilizzarla con un metodo, un percorso, una query o un corpo modificati genera un conflitto; anche la riformattazione di JSON modifica l’impronta. Una richiesta duplicata mentre l’originale è in corso può restituire 409 con Retry-After. Una richiesta completata può restituire nuovamente il risultato salvato, incluso un errore. Conservare i dettagli della richiesta quando si accerta l’esito dopo un timeout, anziché generare automaticamente una nuova chiave.

Verificare il record salvato e lo stato di convalida

Un aggiornamento riuscito restituisce HTTP 200 e direttamente un oggetto JSON del marchio, senza il contenitore status/response della precedente v3. Controllare il suo brandId, quindi recuperare nuovamente lo stesso marchio con GET e confrontare i campi interessati. La rotta pubblica di aggiornamento non accetta il contenitore changes/version del portale né fornisce il relativo controllo ottimistico della concorrenza. Coordinare chi effettua modifiche contemporaneamente; una chiave di idempotenza impedisce invii duplicati, ma non le modifiche di un altro operatore.

Il portale attuale legge il marchio, conserva i suoi campi scrivibili, controlla la versione del modulo prima del salvataggio e legge nuovamente il risultato. Blocca i campi fondamentali dell’identità giuridica quando rileva campagne attive. Il registro può imporre ulteriori restrizioni, comprese quelle relative alle verifiche esterne, anche quando un campo era disponibile in un modulo.

Il salvataggio delle informazioni corrette non richiede automaticamente una nuova verifica dell’identità né garantisce l’approvazione. La ripetizione della verifica è un’azione separata che può comportare un costo; utilizzare il portale per esaminare lo stato attuale e confermare esplicitamente qualsiasi importo indicato. I normali aggiornamenti del marchio tramite PUT non generano un addebito di registrazione separato nell’attuale servizio API. Gli addebiti esistenti per campagne, messaggistica e altri servizi restano separati.

Risolvere gli errori senza creare una registrazione duplicata

Leggere lo stato HTTP e i dettagli dell’errore in JSON. Per 400, correggere il campo specifico o rispettare la restrizione relativa all’identità o alla relazione. Per 401, 403 o 404, controllare le credenziali, l’IP di origine consentito e l’appartenenza all’account. Per 429, rispettare Retry-After. Un errore 500 o 502 può verificarsi dopo che il registro ha accettato l’aggiornamento; conservare l’eventuale requestId e leggere il record esistente prima di un altro invio.

Una risposta di aggiornamento non vuota ma incompleta può lasciare un’istantanea locale incompleta; un corpo vuoto in una risposta di successo può lasciare invariati campi di un’istantanea precedente. Non dedurre la conservazione dei campi dal solo stato di successo. Recuperare nuovamente il marchio completo e risolvere eventuali discrepanze tramite l’assistenza. Questa guida non garantisce aggiornamenti atomici tra registro, cache locale e fatturazione.