{"openapi":"3.0.1","info":{"title":"Gateway SMS","description":"L'API Gateway SMS di Openapi fornisce una soluzione robusta e scalabile per integrare la messaggistica SMS professionale nelle vostre applicazioni. Il nostro servizio è progettato per gestire con precisione elevati volumi di messaggi e offre endpoint dedicati per regioni specifiche come l'Italia e la Spagna, oltre a un endpoint mondiale per una portata globale.\n\nOgni richiesta viene sottoposta a un rigoroso processo di convalida che include il controllo della sintassi per i formati **E.164**, il rilevamento della codifica dei caratteri (GSM-7 o UCS-2) e la segmentazione automatica per i messaggi lunghi. Diamo priorità alla sicurezza e alla conformità: il sistema analizza automaticamente il contenuto alla ricerca di parole proibite per evitare abusi e garantisce che tutti i messaggi siano conformi ai requisiti legali.\n\nGli sviluppatori possono usufruire di funzionalità avanzate come la \"**dryRun**\" per effettuare test senza dover sostenere costi e le chiamate Webhook in tempo reale che forniscono aggiornamenti immediati sullo stato di consegna. I messaggi hanno un tempo massimo di **scadenza** di **48 ore**; se un messaggio non può essere consegnato entro questa finestra, il suo stato cambierà in EXPIRED. La fatturazione è trasparente e dinamica; mentre i messaggi regionali hanno tariffe fisse, i costi di consegna in tutto il mondo sono calcolati dopo l'invio per garantire il miglior prezzo di mercato. Per le operazioni in tutto il mondo è necessario mantenere un saldo minimo di credito e, per garantire la massima qualità del servizio a tutti gli utenti, si applicano sanzioni severe in caso di violazione delle norme.\n\n##### 🆔 Nomi dei mittenti\n\nQuando si inviano SMS con un mittente personalizzato, il sistema registra automaticamente il nome del mittente. Per la messaggistica professionale in conformità con le normative locali (in particolare per l'**Italia**), l'invio di messaggi è consentito solo alle **aziende registrate** che hanno completato la verifica aziendale. Per l'Italia è previsto un limite predefinito di **10 mittenti registrabili** per utente. Le richieste di registrazione di altri mittenti oltre questo limite saranno respinte, a meno che l'utente non sia stato inserito nella whitelist per una quota superiore.\n\n La scelta di nuovi alias può essere soggetta a verifica e approvazione da parte di Openapi e degli operatori di telefonia mobile. **Se i messaggi non vengono consegnati durante una prima fase di test, vi preghiamo di contattarci in modo da poter eseguire controlli specifici sulle richieste.** Una volta convalidato, l'alias sarà associato al cliente e potrà essere utilizzato regolarmente senza interruzioni del servizio.\n\n##### ⚠️ ATTENZIONE: Limitazioni di contenuto\n\n**Ambiente sandbox**: L'ambiente sandbox (test.sms.openapi.com) non prevede restrizioni sul contenuto dei messaggi, consentendo agli sviluppatori di testare liberamente l'integrazione. **Si prega di notare che i messaggi inviati nell'ambiente Sandbox non saranno effettivamente consegnati **\n\n**Ambiente di produzione**: L'ambiente di produzione (sms.openapi.com) implementa una rigorosa scansione automatica delle parole proibite. L'invio di messaggi con contenuti proibiti in Produzione senza utilizzare l'opzione \"**dryRun**\" per la pre-verifica comporterà il blocco immediato e l'inserimento dell'utente in una blocklist con relative sanzioni.\n\n##### 🌐 **Copertura e connettività**: Per qualsiasi riferimento ai requisiti e alla copertura degli invii per paese, consultare la seguente pagina: [https://docs.openapi.it/smsv2/sms-coverage-and-connectivity.html](https://docs.openapi.it/smsv2/sms-coverage-and-connectivity.html)","version":"1.3.6","contact":{"url":"https://openapi.it/en/support","name":"Support"},"license":{"name":"Apache 2.0","url":"http://www.apache.org/licenses/LICENSE-2.0.html"},"termsOfService":"https://openapi.it/en/terms-and-conditions"},"externalDocs":{"description":"Prima volta qui? Generare un nuovo token di accesso","url":"https://console.openapi.com/it/oauth"},"security":[{"bearerAuth":[]}],"servers":[{"url":"https://sms.openapi.com","description":"Produzione"},{"url":"https://test.sms.openapi.com","description":"Sandbox"}],"tags":[{"name":"Messages","description":"Operazioni di invio e recupero di messaggi SMS."},{"name":"Senders","description":"Operazioni per la gestione dei mittenti di messaggi."}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"SendMessageRequest":{"type":"object","description":"Corpo della richiesta per l'invio di un nuovo messaggio SMS.","required":["recipient","message"],"properties":{"sender":{"type":"string","nullable":true,"description":"Il mittente del messaggio. Deve essere un nome alfanumerico (tra 3 e 11 caratteri, spazi consentiti) e non può essere puramente numerico. Se nullo o vuoto, 'Openapi' sarà usato come mittente predefinito.","minLength":3,"maxLength":11,"default":"Openapi","example":"Openapi"},"recipient":{"type":"string","description":"Il numero del destinatario nel formato internazionale E.164.","example":"+393331234567"},"message":{"type":"string","description":"Il testo del messaggio da inviare. La segmentazione è gestita automaticamente. La codifica GSM-7 consente fino a 160 caratteri per parte (153 se multipart), mentre UCS-2 consente fino a 70 caratteri (67 se multipart).","example":"Hello! This is a test message."},"options":{"$ref":"#/components/schemas/MessageOptions"},"callback":{"$ref":"#/components/schemas/CallbackOptions"}}},"SendOTPRequest":{"type":"object","description":"Corpo della richiesta per l'invio di un messaggio di verifica OTP.","required":["recipient"],"properties":{"recipient":{"type":"string","description":"Il numero del destinatario nel formato internazionale E.164.","example":"+393331234567"},"alphanumeric":{"type":"boolean","description":"Se impostato su \"true\", l'OTP generato sarà alfanumerico. Se impostato su 'false' (valore predefinito), sarà puramente numerico.","default":false},"length":{"type":"integer","description":"La lunghezza del codice OTP (min 4, max 10).","minimum":4,"maximum":10,"default":5},"cacheSeconds":{"type":"integer","description":"Numero di secondi entro i quali lo stesso codice OTP sarà riutilizzato per lo stesso destinatario (max 600).","minimum":0,"maximum":600,"default":0},"options":{"$ref":"#/components/schemas/MessageOptions"},"callback":{"$ref":"#/components/schemas/CallbackOptions"}}},"MessageOptions":{"type":"object","properties":{"dryRun":{"type":"boolean","description":"Se impostato su \"true\", la richiesta viene convalidata e calcolata, ma il messaggio non viene effettivamente inviato.","default":false},"failOnMultipleMessages":{"type":"boolean","description":"Se impostato su \"true\", la richiesta fallirà se il testo del messaggio supera la lunghezza di una singola parte di SMS.","default":false}}},"CallbackOptions":{"type":"object","description":"È il nostro sistema di callback OpenAPI standardizzato. Consente di configurare i parametri per ricevere notifiche sugli aggiornamenti di stato delle richieste asincrone a questo endpoint.","properties":{"method":{"type":"string","description":"Specifica il metodo di richiamo. Se impostato su \"POST\", verrà avviata una richiesta HTTP POST standard con l'intestazione Content-Type impostata su application/x-www-form-urlencoded. I dati JSON saranno codificati in una coppia chiave-valore denominata data (personalizzabile tramite il parametro field) all'interno del corpo della richiesta. Se il metodo è impostato su \"JSON\", verrà effettuata una richiesta HTTP POST diretta con l'intestazione Content-Type impostata su application/json. I dati JSON grezzi saranno inseriti direttamente nel corpo della richiesta, senza alcuna codifica.","enum":["POST","JSON"],"default":"JSON"},"field":{"type":"string","description":"Questo parametro funziona insieme al parametro \"metodo\" impostato su \"POST\". Se fornito come stringa, determina il nome del parametro che sarà inviato nella richiesta POST.","example":"data","default":"data"},"url":{"type":"string","format":"uri","description":"In questo parametro deve essere inserito un URL valido in grado di gestire richieste POST. Per gli endpoint che richiedono l'autenticazione, il parametro \"headers\" può essere usato per specificare \"basic auth\" o \"bearer auth\". Il timeout massimo è di 30 secondi. Se è impostato \"retry\", il sistema riproverà fino a un massimo di \"retry\" fino a quando non viene ricevuto un codice di stato 200.","example":"https://www.mysite.com/myEndpoint"},"retry":{"type":"integer","description":"Il numero massimo di tentativi è definito dal parametro \"retry\". Se il numero massimo di tentativi viene raggiunto senza un codice di stato di successo (ad esempio, 200 OK), la richiesta viene considerata un fallimento definitivo. Spesso viene introdotto un intervallo di tempo tra i tentativi per evitare di sovraccaricare il server. Questo intervallo può aumentare esponenzialmente a ogni tentativo per ridurre l'impatto su un server sovraccarico. Il parametro \"retry\" è configurato per riprovare la richiesta solo in caso di codici di stato specifici, in genere quelli che indicano errori temporanei (ad esempio, 502, 503) o problemi di rete.","example":3,"maximum":5,"minimum":0,"default":0},"headers":{"type":"object","properties":{"key":{"type":"string"}},"description":"Un insieme di intestazioni HTTP da inviare con la richiesta. Ogni intestazione è definita come una coppia chiave-valore. Le intestazioni possono essere utilizzate per vari scopi, tra cui l'autenticazione, la negoziazione dei contenuti e i metadati personalizzati.","example":{"session_id":"9834r5fh589494"}},"custom":{"type":"object","description":"Questo oggetto può essere popolato con qualsiasi dato aggiuntivo che si desidera includere nella risposta della richiamata. Questi dati saranno accessibili nel parametro 'custom' della funzione di callback. È possibile utilizzarlo per memorizzare e recuperare qualsiasi informazione rilevante necessaria per l'applicazione.","example":{"my_custom_id":"123456789"}}},"required":["url"]},"OTPOptions":{"type":"object","description":"Configurazione utilizzata per la generazione di OTP.","properties":{"length":{"type":"integer","description":"Lunghezza del codice OTP.","example":5},"alphanumeric":{"type":"boolean","description":"Se il codice è alfanumerico.","example":false},"cacheSeconds":{"type":"integer","description":"Durata della cache per l'OTP.","example":300}}},"BaseMessageResponse":{"type":"object","description":"Oggetto che rappresenta un messaggio.","properties":{"id":{"type":"string","description":"L'ID univoco del messaggio nel nostro sistema.","example":"633aabe3e4a9a0e69811ad7f"},"username":{"type":"string","description":"SENT dell'account che ha inviato il messaggio."},"state":{"type":"string","description":"Lo stato attuale del messaggio. Il tempo massimo di scadenza per i tentativi di consegna è di 48 ore. Se un messaggio non può essere consegnato entro questo periodo, il suo stato cambia in EXPIRED.","enum":["NEW","PENDING","UNDELIVERABLE","DELIVERED","EXPIRED","REJECTED"]},"sender":{"type":"string","nullable":true,"description":"Il mittente utilizzato per la consegna."},"recipient":{"type":"string","description":"Il destinatario del messaggio."},"internationalPrefix":{"type":"string","description":"Il prefisso internazionale del numero del destinatario.","example":"39"},"countryCode":{"type":"string","description":"Il codice ISO del paese del destinatario.","example":"IT"},"message":{"type":"string","description":"Il testo del messaggio inviato."},"encoding":{"type":"string","description":"La codifica rilevata per il messaggio.","enum":["GSM-7","UCS-2"]},"charactersCount":{"type":"integer","description":"Il numero di caratteri calcolato in base alle regole di codifica."},"messageCount":{"type":"integer","description":"Il numero di segmenti SMS necessari per inviare il messaggio."},"price":{"type":"number","format":"float","default":0,"description":"Il costo per singolo SMS. Per i messaggi WW, questo valore è inizialmente pari a 0 e viene aggiornato dopo l'accettazione del provider."},"totalPrice":{"type":"number","format":"float","default":0,"description":"Il costo totale del messaggio (prezzo * messageCount). Per i messaggi WW, questo valore è inizialmente pari a 0 e viene aggiornato dopo l'accettazione del fornitore."},"blocklisted":{"type":"boolean","description":"Indica se il messaggio è stato bloccato a causa di contenuti vietati."},"blocklistedReason":{"type":"string","description":"Il motivo per cui il messaggio è stato bloccato (se applicabile)."},"options":{"$ref":"#/components/schemas/MessageOptions"},"callback":{"$ref":"#/components/schemas/CallbackOptions"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"sentAt":{"type":"string","format":"date-time","nullable":true},"deliveredAt":{"type":"string","format":"date-time","nullable":true}}},"MessageResponse":{"$ref":"#/components/schemas/BaseMessageResponse"},"OTPMessageResponse":{"allOf":[{"$ref":"#/components/schemas/BaseMessageResponse"},{"type":"object","properties":{"isOtp":{"type":"boolean","description":"Indica se il messaggio è un OTP."},"otp":{"type":"string","description":"Il codice OTP generato (presente solo per le richieste OTP).","example":"5F8A2"},"otpOptions":{"$ref":"#/components/schemas/OTPOptions"}}}]},"ErrorResponse":{"type":"object","properties":{"code":{"type":"integer","description":"Un codice di errore interno per una rapida identificazione del problema."},"message":{"type":"string","description":"Una descrizione chiara dell'errore."}}},"Sender":{"type":"object","description":"Rappresenta un mittente di messaggi registrato da un utente.","properties":{"_id":{"type":"string","description":"Identificatore univoco del mittente."},"sender":{"type":"string","description":"Il nome del mittente."},"countryCode":{"type":"string","description":"Il codice del Paese (ad esempio, IT, ES)."},"state":{"type":"string","description":"Lo stato attuale della registrazione del mittente.","enum":["APPROVED","PENDING","DELETING"]}}}},"requestBodies":{"CallbackStatusUpdate":{"description":"L'oggetto messaggio aggiornato.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageResponse"}}}},"CallbackOTPStatusUpdate":{"description":"L'oggetto messaggio OTP aggiornato che include i campi OTP.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OTPMessageResponse"}}}}},"responses":{"Callback200":{"description":"Richiamo di successo."},"Callback400":{"description":"Inserimento non valido."}}},"paths":{"/senders":{"get":{"tags":["Senders"],"summary":"Elenco dei mittenti","description":"Recupera l'elenco dei mittenti registrati dall'utente autenticato. I mittenti vengono registrati automaticamente quando si invia un SMS con un mittente personalizzato.","parameters":[{"name":"skip","in":"query","description":"Numero di record da saltare per la paginazione.","schema":{"type":"integer","default":0}},{"name":"limit","in":"query","description":"Numero massimo di record da restituire (max 100).","schema":{"type":"integer","default":100}},{"name":"country_code","in":"query","description":"Filtrare per codice paese (ad es. IT, ES).","schema":{"type":"string"}}],"responses":{"200":{"description":"Recupero di successo dell'elenco dei mittenti","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Sender"}}}}}}},"404":{"description":"Nessun mittente trovato.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/senders/{id}":{"delete":{"tags":["Senders"],"summary":"Contrassegnare un mittente per l'eliminazione","description":"Imposta lo stato di un mittente specifico su \"CANCELLAZIONE\". Questa richiesta è asincrona e conforme alle norme AGCOM.","parameters":[{"name":"id","in":"path","required":true,"description":"L'ID univoco (ObjectId) del mittente da contrassegnare per l'eliminazione.","schema":{"type":"string"}}],"responses":{"200":{"description":"Mittente contrassegnato per la cancellazione","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}},"400":{"description":"Formato ID mittente non valido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Mittente non trovato.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/WW-messages":{"post":{"tags":["Messages"],"summary":"Inviare un nuovo messaggio SMS (in tutto il mondo)","description":"Crea e mette in coda un nuovo messaggio SMS da inviare in tutto il mondo. Si noti che per questo endpoint il costo del messaggio viene calcolato e addebitato solo dopo l'invio del messaggio. Il prezzo finale varia a seconda dell'operatore del destinatario.\n\nSe l'utente ha un piano di abbonamento attivo, le parti del messaggio saranno detratte dal bundle disponibile prima di addebitare l'eventuale saldo residuo dal wallet.\n\nPer inviare un messaggio tramite questo endpoint, è necessario disporre di un credito minimo sul proprio conto pari a 1 euro moltiplicato per il numero di parti di messaggio (messageCount) nel caso in cui il bundle non sia disponibile o sia insufficiente.\n\n**IMPORTANTE**: Se il contenuto del messaggio o il mittente contengono parole proibite, il messaggio verrà bloccato, l'account verrà inserito nella lista di blocco e verrà addebitata una penale di 1 euro per ogni parte del messaggio.\n\n#### 🌐 Copertura e connettività: Per qualsiasi riferimento ai requisiti e alla copertura degli invii per paese, consultare la seguente pagina: [https://docs.openapi.it/smsv2/sms-coverage-and-connectivity.html](https://docs.openapi.it/smsv2/sms-coverage-and-connectivity.html)","requestBody":{"description":"Dati del messaggio da inviare.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageRequest"}}}},"responses":{"201":{"description":"Messaggio accettato e messo in coda","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MessageResponse"}}}}}},"403":{"description":"Vietato (ad esempio, l'utente è inserito in una lista di blocco)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"code":2020,"message":"The user is blocklisted. Please contact support for assistance."}}}},"422":{"description":"Unprocessable Entity (ad esempio, formato dati non valido, parole proibite)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"Invalid Sender":{"value":{"code":2021,"message":"Sender name must be between 3 and 11 alphanumeric characters."}},"Numeric Sender":{"value":{"code":2024,"message":"Sender name cannot be purely numeric."}},"Invalid Recipient":{"value":{"code":2011,"message":"Invalid mobile phone number. Use E.164 format."}},"Forbidden Content":{"value":{"code":2044,"message":"The sent message does not comply with the legal requirements."}}}}}}},"callbacks":{"callback":{"{$request.body#/callback/url}":{"post":{"summary":"Callback per gli aggiornamenti di stato dei messaggi","description":"Quando nella richiesta viene fornito un URL di callback, il nostro sistema invierà una richiesta POST asincrona a tale URL ogni volta che lo stato del messaggio cambia.","requestBody":{"$ref":"#/components/requestBodies/CallbackStatusUpdate"},"responses":{"200":{"$ref":"#/components/responses/Callback200"},"400":{"$ref":"#/components/responses/Callback400"}}}}}}}},"/IT-messages":{"post":{"tags":["Messages"],"summary":"Inviare un nuovo messaggio SMS (Italia)","description":"Crea e mette in coda un nuovo messaggio SMS da inviare specificamente in Italia. Applica regole e prezzi specifici per il Paese.\n\n**Registrazione dell'azienda**: In conformità alla normativa italiana (AGCOM), l'invio di messaggi verso l'Italia è consentito solo alle aziende registrate che hanno completato la verifica della propria attività.\n\n**Nomi dei mittenti**: Per rispettare la normativa locale, per l'Italia è previsto un limite predefinito di **10 mittenti registrabili** per utente. Se avete bisogno di un limite più alto, contattate l'assistenza.\n\n**IMPORTANTE**: Se il contenuto del messaggio o il mittente contengono parole proibite, il messaggio verrà bloccato, l'account verrà inserito nella lista di blocco e verrà addebitato il costo del messaggio.","requestBody":{"description":"Dati del messaggio da inviare.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageRequest"}}}},"responses":{"201":{"description":"Messaggio accettato e messo in coda","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MessageResponse"}}}}}},"403":{"description":"Vietato (ad esempio, l'utente è inserito in una lista di blocco)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"code":2020,"message":"The user is blocklisted. Please contact support for assistance."}}}},"422":{"description":"Unprocessable Entity (ad esempio, formato dati non valido, parole proibite, paese sbagliato)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"Wrong Country":{"value":{"code":2013,"message":"The recipient number does not belong to the supported country for this endpoint (IT)."}},"Forbidden Content":{"value":{"code":2050,"message":"The sent message does not comply with the legal requirements."}},"Forbidden Content (Dry Run)":{"value":{"code":2044,"message":"The sent message does not comply with the legal requirements."}},"Sender Limit Reached":{"value":{"code":5010,"message":"Maximum limit of 10 senders reached for country: IT"}}}}}}},"callbacks":{"callback":{"{$request.body#/callback/url}":{"post":{"summary":"Callback per gli aggiornamenti di stato dei messaggi","description":"Quando nella richiesta viene fornito un URL di callback, il nostro sistema invierà una richiesta POST asincrona a tale URL ogni volta che lo stato del messaggio cambia.","requestBody":{"$ref":"#/components/requestBodies/CallbackStatusUpdate"},"responses":{"200":{"$ref":"#/components/responses/Callback200"},"400":{"$ref":"#/components/responses/Callback400"}}}}}}}},"/ES-messages":{"post":{"tags":["Messages"],"summary":"Inviare un nuovo messaggio SMS (Spagna)","description":"Crea e mette in coda un nuovo messaggio SMS da inviare specificamente in Spagna. Applica regole e prezzi specifici per il Paese.\n\n**IMPORTANTE**: Se il contenuto del messaggio o il mittente contengono parole proibite, il messaggio verrà bloccato, l'account verrà inserito nella lista di blocco e verrà addebitato il costo del messaggio.","requestBody":{"description":"Dati del messaggio da inviare.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageRequest"}}}},"responses":{"201":{"description":"Messaggio accettato e messo in coda","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MessageResponse"}}}}}},"403":{"description":"Vietato (ad esempio, l'utente è inserito in una lista di blocco)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"code":2020,"message":"The user is blocklisted. Please contact support for assistance."}}}},"422":{"description":"Unprocessable Entity (ad esempio, formato dati non valido, parole proibite, paese sbagliato)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"Wrong Country":{"value":{"code":2013,"message":"The recipient number does not belong to the supported country for this endpoint (ES)."}},"Forbidden Content":{"value":{"code":2050,"message":"The sent message does not comply with the legal requirements."}},"Forbidden Content (Dry Run)":{"value":{"code":2044,"message":"The sent message does not comply with the legal requirements."}}}}}}},"callbacks":{"callback":{"{$request.body#/callback/url}":{"post":{"summary":"Callback per gli aggiornamenti di stato dei messaggi","description":"Quando nella richiesta viene fornito un URL di callback, il nostro sistema invierà una richiesta POST asincrona a tale URL ogni volta che lo stato del messaggio cambia.","requestBody":{"$ref":"#/components/requestBodies/CallbackStatusUpdate"},"responses":{"200":{"$ref":"#/components/responses/Callback200"},"400":{"$ref":"#/components/responses/Callback400"}}}}}}}},"/otp":{"post":{"tags":["Messages"],"summary":"Inviare un messaggio di verifica OTP","description":"Genera un codice OTP sicuro e lo invia via SMS al destinatario utilizzando 'OTP MOBILE' come mittente predefinito (il mittente potrebbe essere diverso a seconda delle normative nazionali). Il corpo del messaggio viene tradotto automaticamente in base al Paese del destinatario. I prezzi seguono il modello Worldwide (WW).","requestBody":{"description":"Dati per il messaggio OTP.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendOTPRequest"}}}},"responses":{"201":{"description":"SENT inviato","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OTPMessageResponse"}}}}}},"403":{"description":"Vietato (ad esempio, l'utente è inserito in una lista di blocco)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"code":2020,"message":"The user is blocklisted. Please contact support for assistance."}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"Invalid Length":{"value":{"code":1020,"message":"Length must be between 4 and 10."}},"Invalid Recipient":{"value":{"code":2011,"message":"Invalid mobile phone number. Use E.164 format."}}}}}}},"callbacks":{"callback":{"{$request.body#/callback/url}":{"post":{"summary":"Callback per gli aggiornamenti di stato OTP","description":"Quando nella richiesta viene fornito un URL di callback, il nostro sistema invierà una richiesta POST asincrona a tale URL ogni volta che lo stato del messaggio cambia.","requestBody":{"$ref":"#/components/requestBodies/CallbackOTPStatusUpdate"},"responses":{"200":{"$ref":"#/components/responses/Callback200"},"400":{"$ref":"#/components/responses/Callback400"}}}}}}}},"/messages":{"get":{"tags":["Messages"],"summary":"Recuperare l'elenco dei messaggi inviati","description":"Restituisce un elenco impaginato dei messaggi inviati dall'account.","parameters":[{"name":"skip","in":"query","description":"Numero di messaggi da saltare per la paginazione.","schema":{"type":"integer","default":0}},{"name":"limit","in":"query","description":"Numero massimo di messaggi da restituire.","schema":{"type":"integer","default":100}}],"responses":{"200":{"description":"Operazione Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MessageResponse"}}}}}}},"401":{"description":"Non autorizzato"}}}},"/messages/{id}":{"get":{"tags":["Messages"],"summary":"Recuperare un singolo messaggio","description":"Restituisce i dettagli di un messaggio specifico tramite il suo ID.","parameters":[{"name":"id","in":"path","description":"L'ID univoco del messaggio da recuperare.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Operazione Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MessageResponse"}}}}}},"401":{"description":"Non autorizzato"},"404":{"description":"Messaggio Not Found"}}}}}}