ITA – Protocollo HTTP

PROTOCOLLO HTTP #

E’ possibile inviare SMS tramite HTTP Rest Api attraverso una chiamata così strutturata:

• URL: https://secure.agiletelecom.com/services/sms/send
• METODO: POST
• AUTENTICAZIONE: Basic / Api-Key / OAuth1.1 (tutte nell’header)
• BODY: JSON come da esempio qui di seguito:

{
  "globalId" : "f9b865ef-5ce3-4e44-b65c-615fd71bbd09",
  "maxIdLen" : 64,
  "enableConcatenated": true,
  "enableUnicode": true,
  "enableDelivery": true,
  "simulation": false,
  "messages":[
    {
      "destinations": ["41793026727", "417930254674"],
      "ids": ["157d541b-e0cd-4340-ac77-bc5d530dd90e", "d0f2e3c1-a043-418d-ad5e-0248184b9833"],
      "sender": "InfoSMS",
      "body": "This is a message.",
      "hexBody": false,
      "udhData": "070645670000",
      "scheduling": "2022-05-09 09:00:00.002+0200"
    },
    ...
  ]
}

Le variabili da inviare sono le seguenti:

CAMPO	TIPO	OBBLIGATORIO	DEFAULT	NOTE
globalId	string	no		Identificativo univoco di invio per il cliente
maxIdLen	integer	no	64	Lunghezza massima (caratteri) degli id
enableConcatenated	boolean	no	true	Abilita i concatenati se necessario
enableUnicode	boolean	no	true	Abilita testo in unicode
enableDelivery	boolean	no	true	Abilita la consegna del delivery al cliente
simulation	boolean	no	false	Consente la simulazione, senza reale invio del messaggio
messages	array	si		Elenco dei messaggi da inviare. Ogni messaggio può avere più destinatari.
destinations	array	si		Elenco dei destinatari di un messaggio
ids	array	no		Elenco degli id relativi ai messaggi
sender	string	si		Mittente dei messaggi da inviare
body	string	si		Testo dei messaggi
hexBody	boolean	no	false	Indica se il testo è inserito in HEX o se in normale UTF8/16
udhData	string	no		Se presente indica il codice UDH da inserire nel messaggio
scheduling	string	no		Data di programmazione, in formato “yyyy-MM-dd HH:mm:ss.SSSZ“

La risposta sarà in formato JSON (con specifica Jsend in caso di errori):

• 2XX (messaggio accettato dal server)

{
  "globalId": "f9b865ef-5ce3-4e44-b65c-615fd71bbd09",
  "processedMessages": 2,
  "processedSmsParts": 4,
  "credit": 10.324
}

CAMPO	TIPO	NOTE
globalId	string	Valore del globalid riportato dalla richiesta
processedMessages	integer	Messaggi accettati come da sezione messages sulla richiesta
processedSmsParts	integer	Parti che verranno spedite (differisce dal precedente in caso di concatenati)
credit	double	Credito residuo dell’account espresso in €

• 4XX (richiesta rifiutata per errori formali nei parametri)

{
    "status": "fail",
    "data": { 
		"body": "Missing message body(ies)" 
		"number": "Wrong destination number(s)"
		
	},
	"code": 6
}

CAMPO	TIPO	NOTE
status	string	Vale sempre “fail” per gli errori 4XX
data	object / string	Contiene un elenco di chiave-valore, dove le chiavi indicano il campo da passare in ingresso e il valore indica il problema riscontrato su tale campo. Oppure una stringa che descrive il problema.
body/number/…	string	Sono due possibili esempi di campi passati all’API in cui siano stati riscontrati dei problemi
code	integer	Codice di errore custom. Indica la tipologia di problema secondo quanto specificato nella tabella dei codici di errore riportata successivamente

• 5XX (richiesta non processata per errori lato server)

{
    "status": "error",
    "message": "Number check service unavailable",
	"code": 9
}

CAMPO	TIPO	NOTE
status	string	Vale sempre “error” per gli errori 5XX
message	string	Descrive il tipo di problema riscontrato lato server durante l’elaborazione della richiesta
code	integer	Codice di errore custom. Indica la tipologia di problema secondo quanto specificato nella tabella dei codici di errore riportata successivamente

Tabella dei codici di errore:

CODICE	DESCRIZIONE
1	Wrong credentials
2	Insufficient credit
8	Server error
9	Server error (service timeout)
26	Alias (Sender) non autorizzato
100	Source IP is not allowed

HTTP Delivery #

Utilizzato da AgileTelecom per l’invio della conferma di consegna SMS ai clienti che ne hanno fatto richiesta.

I clienti riceveranno una chiamata HTTP Rest API all’URL che hanno specificato così strutturata:

• URL: definito dal cliente
• METODO: POST
• AUTENTICAZIONE: nessuna
• BODY: JSON (segue un esempio)

{ 
  "messageId": "157d541b-e0cd-4340-ac77-bc5d530dd90e", 
  "destination": "41793026727",
  "statusCode": 3,
  "description": "Delivered",
  "doneDate": "2022-05-09 09:00:05.002+0200",
  "concatTotal": 2,
  "concatProgressive": 1,
  "lcrOperator": "22210",
  "realOperator": "22201",
  "price": 0.003
}

CAMPO	TIPO	NOTE
messageId	string	ID che identifica in modo univoco per il cliente i messaggio spedito
destination	string	Numero di telefono del destinatario del messaggio spedito
statusCode	integer	Codice che identifica lo status di ricezione del messaggio1: Accepted2: Rejected3: Delivered4: Expired5: Deleted6: Undeliverable
description	string	Descrizione dello status
doneDate	string	Data relativa al delivery
concatTotal	integer	Numero di parti totali in caso di messaggio concatenato
concatProgressive	integer	Numero della parte del messaggio in caso di messaggio concatenato
lcrOperator	string	(Opzionale, attivabile con parametro cliente) Operatore individuato dal servizio LCR
realOperator	string	(Opzionale, attivabile con parametro cliente) Operatore reale del numero di destinazione
price	double	(Opzionale, attivabile con parametro cliente) Costo dell’invio