Documentazione dell’API REST
API REST per SMS e MMS
Invia messaggi applicativi approvati e gestisci accettazione, eventi di consegna, segmentazione e addebiti.
Scegli insieme l’API e la credenziale
Gli account approvati per Sviluppatori e Automazione, Aziende e Fornitori di comunicazioni possono integrare i servizi abilitati. Uno sviluppatore individuale non deve fingere di essere un’azienda. Gli SMS/MMS delle applicazioni richiedono l’approvazione all’invio e la registrazione previste. Il servizio per Privati e famiglie non offre un’API di invio dei messaggi accessibile ai clienti.
| Famiglia di API | URL di base | Autenticazione e risultato |
|---|---|---|
| Comunicazioni v3 | https://api.multitel.net/v3 | Credenziali Basic approvate; token predisposti idonei solo per le operazioni che li supportano. JSON status e response. |
| Registrazione per le emergenze | https://api.multi.tel/emergency | Credenziali Basic approvate oppure accesso bearer predisposto in modo specifico. JSON code, message e data. |
| Integrazioni REST del portale | Host e operazione indicati nel riferimento per sviluppatori del tuo account | Usa la credenziale, gli ambiti e lo schema documentati per quell’operazione. Le richieste di sessione del browser costituiscono una superficie separata. |
Imposta MULTITEL_API_USERNAME e MULTITEL_API_PASSWORD tramite la configurazione dei segreti del tuo server prima di usare gli esempi. Non inserirli mai nel JavaScript pubblico del browser, negli URL o nel controllo del codice sorgente. Le credenziali dedicate si gestiscono nelle impostazioni di integrazione API.
Preparare una richiesta SMS
Usa un numero mittente approvato, abilitato agli SMS e di proprietà dell’account, un destinatario che abbia acconsentito al messaggio e la necessaria verifica Brand/Campaign o toll-free. L’esempio seguente invia un messaggio reale se compilato con credenziali e numeri funzionanti; non è una sandbox.
curl --fail-with-body \
--user "$MULTITEL_API_USERNAME:$MULTITEL_API_PASSWORD" \
--header "Accept: application/json" \
--request POST \
--header "Content-Type: application/json" \
--data '{"from":"YOUR_APPROVED_NUMBER","to":"YOUR_CONSENTED_RECIPIENT","text":"Your requested update is ready."}' \
"https://api.multitel.net/v3/sendsms"Sostituisci i segnaposto di mittente e destinatario con cifre internazionali che includano il prefisso del paese. Per un MMS, indica in media l’URL del contenuto multimediale supportato e recuperabile pubblicamente, e verifica prima l’idoneità e i prezzi degli MMS.
L’accettazione non è la consegna
Controlla sia lo stato applicativo esterno sia il risultato di messaggistica restituito. Registra l’identificativo del messaggio fornito dal servizio e segui lo stato di consegna e gli eventi webhook. Un invio riuscito non può dimostrare che il dispositivo del destinatario abbia ricevuto il messaggio.
La fatturazione degli SMS avviene per segmento. Codifica e lunghezza del messaggio possono produrre più segmenti; i contenuti multimediali e gli addebiti legati all’operatore possono differire da quelli degli SMS. Leggi il prezzo di vendita corrente dell’account prima di inviare. Non ripetere mai alla cieca un invio andato in timeout: controlla prima l’esito registrato.
Gestire errori e nuovi tentativi
- Errore di autenticazione o di autorizzazione
- Verifica lo stato di abilitazione della credenziale API, il servizio consentito e la restrizione sull’IP di origine. Il cookie di sessione del portale non è una credenziale di integrazione.
- Credito insufficiente o approvazione mancante
- Risolvi il problema del saldo dell’account, dell’approvazione all’invio o del requisito documentale prima di ripetere l’operazione.
- Nessun risultato
- Gestisci un inventario vuoto o un nome del chiamante mancante come un esito ordinario. Non dare per scontato che un numero sintatticamente valido disponga di tutti i servizi.
- Timeout di rete o guasto del servizio
- Per le letture usa tentativi limitati con backoff. Per un acquisto, un invio o una registrazione, controlla prima lo stato dell’operazione: ripetere una richiesta già accettata può duplicare un’azione a pagamento.
Il supporto all’idempotenza dipende da ciascuna famiglia di API. L’API per le emergenze supporta chiavi di ripetizione; questo non rende idempotenti richieste v3 arbitrarie. Conserva marcature temporali, ID restituiti e risposte oscurate per l’assistenza.
Continua con il riferimento del tuo account
Il riferimento dopo l’accesso filtra le operazioni in base alle tue autorizzazioni e ai servizi abilitati. Usa l’host esatto, il tipo di credenziale, i campi della richiesta e lo schema della risposta che indica. Le console possono eseguire operazioni reali, inclusi acquisti e messaggi.