# Trasferisci il tuo traffico SMS a BroadNet da qualsiasi provider.

- URL canonico: https://www.broadnet.me/it/developers/migrate
- Lingua: it
- Ultimo aggiornamento: 2026-10-21
- Editore: BroadNet (https://www.broadnet.me)
- Versione Markdown della pagina, generata dalla pagina pubblicata.

Guida alla migrazione indipendente dal fornitore· /developers/migrate

Questa guida riprende i concetti utilizzati dal tuo attuale provider (invio di un messaggio, mittente, conferme di consegna e webhooks di stato) e mostra la parte corrispondente API BroadNet. Successivamente, illustra gli aspetti operativi: registrazione dell'ID mittente, esecuzione di entrambi i provider in parallelo, aumento graduale del traffico, ripristino e individuazione delle responsabilità per ciascuna fase. Non viene menzionato alcun provider specifico, poiché i concetti sono gli stessi ovunque.

**Invia un SMS**

POST /sms/sendSms

**Autenticazione**

Authorization: Bearer <token>

**API HTTP legacy**

/websmpp/websms

**SMPP**

Versione 3.4, con ricevute di consegna

## Mappa la tua API attuale su BroadNet

La maggior parte API SMS condivide alcuni concetti simili, seppur con nomi diversi. Individua il concetto nella prima colonna, indipendentemente dal nome utilizzato dal tuo provider, e usa l'equivalente BroadNet. I nomi dei campi sono esattamente come appaiono nelle specifiche OpenAPI.

| Concetto | Forma tipica presso altri provider | BroadNet |
|---|---|---|
| Host API | Un host API regionale per il tuo account | `https://api.broadnet.me` Le credenziali di test, e l'indirizzo a cui inviare il traffico di prova, arrivano con il tuo accesso di test: richiedilo su /signup e rispondiamo entro un giorno lavorativo. |
| Autenticazione | Un ID account e un segreto tramite autenticazione di base, oppure un'intestazione della chiave API. | `Authorization: Bearer <token>` Un token di accesso per account. |
| Invia un messaggio | Una richiesta HTTP POST a un endpoint di messaggistica | `POST /sms/sendSms` Il corpo della richiesta è in JSON. |
| Mittente | `from`, `sender`, `originator` | `senderId` Un identificativo alfanumerico del mittente o un numero, registrato per ciascun paese. |
| Destinatario | `to`, `destination`, `msisdn` | `destinationNumber` Formato internazionale, come nell'esempio di specifica `447700900101`. |
| Testo del messaggio | `body`, `text`, `content` | `message` Il testo del messaggio, esattamente come lo vedrà il destinatario. |
| Codifica dei caratteri e parti del messaggio | Calcolato dal fornitore o restituito tramite una chiamata API separata | `messageType` `TEXT` (GSM-7) o `UNICODE`. `POST /sms/identify` restituisce `messageType`, `charCount`, `smsParts` e `charLimit` prima dell'invio. |
| Invio programmato | Un campo `send_at` o di pianificazione temporale | `isSchedule · gmt · time` Lascia vuoti questi campi per inviare il messaggio immediatamente. |
| ID messaggio | Un campo ID nella risposta JSON | `200 OK → 2603121407537573731` Il corpo della risposta di `/sms/sendSms` è l'ID del messaggio. |
| Più destinatari | Un punto finale di batch o un ciclo | `POST /sms/sendSmsGroupData` Un array `contacts` nel corpo. `POST /sms/sendbulk` accetta invece il caricamento di un file. |
| Webhook sullo stato della consegna | Un URL di callback per richiesta o per account | `Webhook URL on your account` Lo stato della consegna viene inviato all'URL del webhook configurato nel tuo account. `POST /sms/resendDlr` invia nuovamente le ricevute se non sono pervenute. |
| Richiesta di stato della consegna | Una richiesta GET per il messaggio tramite il suo ID | `GET /websmpp/websmsstatus` API HTTP legacy. Passa l'ID del messaggio come `respid` e `format=json` per JSON. Valori: `DELIVRD`, `UNDELIV`, `EXPIRED`, `REJECTD`. |
| Esportazione del rapporto di consegna | Un'esportazione CSV nella console | `/websmpp/api/dlrreport` API HTTP legacy. Un report di consegna in formato XLSX per un intervallo di date. |
| Risposte di errore | Uno stato HTTP più un codice di errore del provider | `400 · 401 · 500` 400: errore di convalida o campo mancante. 401: token Bearer non valido o mancante. 500: errore imprevisto del server. |
| SMPP | Le sessioni SMPP (si collegano) SMSC del provider | `bind · submit_sm · deliver_sm` Sessioni SMPP v3.4 come trasmettitore, ricevitore o transceiver. Le ricevute di consegna arrivano come `deliver_sm`. Il tuo account include le credenziali di accesso SMPP. |
| Invio tramite URL HTTP GET | Un URL GET con le credenziali nei parametri | `GET /websmpp/websms` API HTTP legacy. `user`, `pass` (o `accesskey` ), `sid`, `mno`, `type`, `text`. Mantenuti per le integrazioni esistenti; le nuove dovrebbero usare `/sms`. |
| SDK | Una libreria client per ogni linguaggio | `@broadnet/cpaas-sdk` Un SDK ufficiale per TypeScript e Node.js. Per altri linguaggi, è possibile generare un client a partire dalle specifiche OpenAPI. |

Ecco lo stesso invio come singola richiesta. Sostituisci i campi mittente, destinatario e testo del tuo provider con `senderId`, `destinationNumber` e `message`:

POST /sms/sendSms

```
curl -X POST https://api.broadnet.me/sms/sendSms \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "senderId": "ACME",
    "destinationNumber": "447700900101",
    "message": "Your code is 8123",
    "messageType": "TEXT"
  }'

# 200 OK — the response body is the message ID, e.g. 2603121407537573731
```

Per verificare un messaggio, interroga il suo stato utilizzando l'ID del messaggio restituito dalla richiesta di invio:

Ricerca dello stato della consegna

```
# Status lookup on the legacy HTTP API (/websmpp), by message ID
curl "https://api.broadnet.me/websmpp/websmsstatus?respid=2603121407537573731&format=json" \
  -H "Authorization: Bearer $BROADNET_TOKEN"

# "status": "DELIVRD"   (or UNDELIV, EXPIRED, REJECTD)
```

Ogni percorso e campo in questa pagina è tratto dalle specifiche BroadNet OpenAPI. Scaricatele e verificate la corrispondenza con esse prima di scrivere il codice. [Apri la specifica OpenAPI](https://www.broadnet.me/developers/openapi.yaml)

## Sposta i tuoi ID mittente

Gli ID mittente alfanumerici e i codici brevi sono generalmente portabili, fatte salve le norme di registrazione di ciascun operatore e autorità di regolamentazione. La registrazione è legata al percorso del traffico, quindi è importante pianificarla prima che qualsiasi messaggio di produzione venga inviato a BroadNet.

1. 1 Elenca ogni ID mittente, i paesi di destinazione e il tipo di traffico che trasporta: OTP, transazionale o di marketing.
2. 2 Verifica le normative di ciascun paese. Negli Emirati Arabi Uniti, gli ID del mittente vengono registrati secondo le norme TDRA tramite l'operatore, un ID per entità giuridica per caso d'uso. In Arabia Saudita, invece, è necessaria l'approvazione CST e dell'operatore, e i mittenti stranieri si vincolano tramite un aggregatore locale autorizzato CST.
3. 3 Il tuo tecnico addetto alla migrazione invia le registrazioni per le rotte di BroadNet e il team di conformità di BroadNet segue ciascuna di esse fino all'approvazione.
4. 4 Avvia l'invio parallelo in un Paese solo dopo che l'ID mittente è stato approvato per le rotte di BroadNet in quel Paese. Fino ad allora, continua a inviare tramite il tuo provider attuale.

Le regole per ciascun mercato sono riportate nelle pagine dedicate ai regolamenti. [Normative sugli SMS per paese](https://www.broadnet.me/it/regulations)

## Eseguire entrambi i provider in parallelo

Mantieni attivo il tuo provider attuale e aggiungi BroadNet come seconda rotta dietro uno switch nel tuo codice. Invia prima chiamate ai tuoi numeri verificati, poi a una piccola quantità di traffico reale e confronta le due rotte sulle stesse destinazioni.

Confronta, per paese e operatore:

- La combinazione degli stati di consegna: consegnato, non consegnato, scaduto e rifiutato.
- Il tempo che intercorre tra l'invio di un messaggio e la ricezione della conferma di consegna.
- Il mittente visualizzato sul telefono.
- Il conteggio dei segmenti per lo stesso testo, da `POST /sms/identify`.

Scegli il percorso per destinatario anziché per messaggio, in modo che tutti i tentativi di invio OTP per un utente passino attraverso lo stesso provider. Un'interfaccia di routing minimale:

route.ts

```
// Send a share of recipients through BroadNet; the rest stay on your
// current provider. BROADNET_SHARE is a percentage (0-100) you control.
const BROADNET_SHARE = Number(process.env.BROADNET_SHARE ?? "0");

// Same recipient -> same bucket, so OTP retries stay on one provider.
function bucket(to: string): number {
  let h = 0;
  for (const c of to) h = (h * 31 + c.charCodeAt(0)) >>> 0;
  return h % 100;
}

export async function sendSms(to: string, text: string, senderId: string) {
  if (bucket(to) < BROADNET_SHARE) return sendViaBroadNet(to, text, senderId);
  return sendViaCurrentProvider(to, text, senderId); // your existing code
}

async function sendViaBroadNet(to: string, text: string, senderId: string) {
  const res = await fetch("https://api.broadnet.me/sms/sendSms", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.BROADNET_TOKEN}`,
      "Content-Type": "application/json",
    },
    // Use UNICODE for non-GSM text; POST /sms/identify tells you which.
    body: JSON.stringify({ senderId, destinationNumber: to, message: text, messageType: "TEXT" }),
  });
  if (!res.ok) throw new Error(`BroadNet send failed: ${res.status}`);
  return { provider: "broadnet", messageId: await res.text() };
}
```

## Aumentare il traffico gradualmente

Trasferisci il volume di produzione su BroadNet gradualmente, un paese o un caso d'uso alla volta. Rimani in ogni fase finché le ricevute di consegna non corrispondono a quelle inviate, quindi passa alla successiva.

1. Test Utilizza solo i tuoi numeri verificati. Conferma l'ID del mittente, il testo del messaggio e la conferma di consegna.
2. 5% Una piccola percentuale di traffico reale. Il traffico OTP verso un singolo paese restituisce conferme di consegna rapide e chiare.
3. 25% Un volume sufficiente per confrontare le tariffe di consegna e i tempi di ricezione con il tuo attuale fornitore.
4. 100% Tutto il traffico per quel paese o caso d'uso. Il tuo provider attuale rimane attivo finché le ricevute di consegna non corrispondono a quanto hai inviato.

### Quanto tempo ci vuole

L'incremento del traffico richiede il tempo che si desidera. Il processo di onboarding segue un percorso predefinito: rispondiamo a una richiesta di accesso di prova entro un giorno lavorativo, l'integrazione tecnica richiede dai 2 ai 5 giorni lavorativi e la convalida del percorso con l'approvazione dell'ID mittente richiede dai 3 ai 10 giorni lavorativi. Nella maggior parte dei mercati, il passaggio dalla fase di individuazione a quella di lancio avviene in 5-15 giorni lavorativi; nei mercati in cui le autorità di regolamentazione impiegano più tempo per approvare gli ID mittente, i tempi sono più lunghi. [Consulta i passaggi per l'onboarding](https://www.broadnet.me/it/onboarding)

## Ritorna al tuo provider attuale senza interruzioni del servizio

Per annullare l'impostazione, utilizzare lo stesso interruttore in senso inverso: ridurre la percentuale di traffico inviato tramite BroadNet all'ultimo passaggio che ha funzionato, oppure a zero. L'integrazione corrente e le relative registrazioni dell'ID mittente rimangono attive, quindi è sufficiente ridurre la percentuale. Non è necessario ricostruire nulla.

- Mantieni attive le credenziali del tuo attuale provider, le registrazioni dell'ID mittente e l'endpoint webhook finché tutto il traffico non sarà stato trasferito e le ricevute di consegna non corrisponderanno a quanto hai inviato.
- Prima di iniziare, concordate quali fattori scatenano un rollback, ad esempio un calo della percentuale di messaggi recapitati in un determinato Paese, e chi è autorizzato a deciderlo.
- Mantieni attivo il gestore webhook anche dopo un rollback: le conferme di consegna per i messaggi già inviati tramite BroadNet potrebbero comunque arrivare.
- Disattiva il vecchio percorso solo dopo che tutto il traffico è transitato senza intoppi attraverso BroadNet e le ricevute di consegna corrispondono a quanto inviato.

## Chi è responsabile di cosa?

Una migrazione coinvolge il tuo codice, le registrazioni dei mittenti e il traffico in tempo reale. Ecco come viene suddiviso il lavoro.

| Compito | Il vostro team | BroadNet |
|---|---|---|
| Mappatura dei campi e modifiche al codice | Apporta le modifiche al codice e prendi il controllo dello switch di routing. | Il tuo tecnico addetto alla migrazione mappa i payload, gli ID mittente e le ricevute attuali API BroadNet. |
| Credenziali | Conserva il token di accesso in un luogo sicuro e non includerlo nel sistema di controllo versione. | Emette il token di accesso e, per SMPP, le credenziali di accesso. |
| Registrazione ID mittente | Fornire la documentazione aziendale richiesta da ciascun ente regolatore. | Gestisce le registrazioni per le sue tratte e ne segue ciascuna fino all'approvazione. |
| Validazione del percorso | Conferma i risultati del test sui tuoi numeri di telefono. | Prima di avviare la produzione, vengono effettuati test di consegna in ciascun mercato. |
| Aumento del traffico e rollback | Definisci ogni passaggio, cosa innesca un rollback e chi lo decide. | Un tecnico di migrazione dedicato è raggiungibile durante l'esecuzione parallela e il passaggio. |
| Consegna dopo che BroadNet ha accettato un messaggio | Monitorate le ricevute di consegna nei vostri sistemi. | Instrada ciascun messaggio dalla sua piattaforma all'operatore e segnala l'avvenuta consegna. |
| Incidenti di produzione | Segnalateli a developers@broadnet.me. | Assistenza tecnica 24 ore su 24, 7 giorni su 7 per gli account di produzione, con tempo di risposta P1 entro 15 minuti. |
| Dismissione del vecchio percorso | Chiudi il conto presso il tuo precedente fornitore. | Conferma che gli ID del mittente, il throughput e le ricevute di consegna siano stati risolti prima della chiusura. |

## Documentazione correlata

[Passa a BroadNet Perché i team passano a BroadNet e il piano di migrazione in quattro fasi.](https://www.broadnet.me/it/switch) [Riferimento API Autenticazione Bearer, invio singolo e massivo, ricerca dei numeri ed errori.](https://www.broadnet.me/it/developers/api) [Webhooks Lo stato della consegna verrà inviato all'URL webhook sul tuo account.](https://www.broadnet.me/it/developers/webhooks)

## Domande frequenti

### Devo riscrivere la mia integrazione per passare a BroadNet?

Di solito no. Si modificano l'host, l'intestazione di autenticazione e alcuni nomi di campo: il campo mittente diventa `senderId`, il campo destinatario diventa `destinationNumber` e il campo testo diventa `message`. Le integrazioni SMPP indirizzano il loro bind esistente a BroadNet con le nuove credenziali.

### Posso mantenere i miei ID mittente?

In generale sì, a seconda delle norme di registrazione di ciascun operatore e dell'autorità di regolamentazione. Le registrazioni vengono depositate sulle rotte di BroadNet prima del passaggio al nuovo servizio: negli Emirati Arabi Uniti secondo le norme TDRA e in Arabia Saudita con l'approvazione CST e dell'operatore.

### Quanto tempo richiede una migrazione?

Nella maggior parte dei mercati, il passaggio dalla fase di scoperta a quella di lancio avviene in 5-15 giorni lavorativi; nei mercati in cui le autorità di regolamentazione impiegano più tempo per approvare gli ID mittente, i tempi sono ancora più lunghi. La successiva fase di incremento del traffico richiede tutto il tempo che si desidera.

### Cosa succede se i tassi di consegna diminuiscono mentre il traffico aumenta?

Riduci la percentuale di traffico inviato tramite BroadNet all'ultimo passaggio che ha funzionato, oppure a zero. Il tuo provider attuale è ancora attivo, quindi il traffico continua a fluire. Successivamente, prima di riprovare, esamina le ricevute di consegna per il paese interessato con il tuo tecnico di migrazione.

### Il servizio di assistenza per la migrazione prevede un costo?

No. Il supporto per la migrazione e la finestra di esecuzione parallela sono inclusi nell'account. Paghi solo per i messaggi che invii.

## Richiedi l'accesso di prova · risposta entro un giorno lavorativo

Ottieni le credenziali, invia messaggi di prova al tuo numero verificato e configura la tua integrazione attuale con un tecnico delle telecomunicazioni BroadNet prima di avviare il traffico di produzione.

[Richiedi l'accesso di prova](https://www.broadnet.me/it/signup) [Perché passare a BroadNet](https://www.broadnet.me/it/switch)