createsession existssession alivesession deletesession deleteallsession getcredit getcreditsubaccount addtransactionsubaccount addsubaccount

Transcript

1 PROTOCOLLO DI INVIO SOAP SOAP è un protocollo per lo scambio di messaggi basato su protocollo HTTP e scambio dei dati in XML, quindi disponibile per qualsiasi piattaforma/linguaggio di programmazione, come ad esempio: ASP.NET Actionscript Java Ruby PERL PYTHON C, C#, C++ e molti altri ancora Gli esempi di questa documentazione si basano su PHP, sfruttando le potenzilità della Classe SoapClient nativa di PHP5 (richiede abilitazione, se non abilitata, via php.ini). Le stesse identiche funzioni si possono avere, sempre in PHP (5 o 4), usando l'ottima classe NUSOAP (scaricabile all'indirizzo ) Versione attuale di NUSOAP è la (documentazione scaricabile da questo indirizzo: ). WSDL (Web Services Description Language) E' il file xml dove viene indicata l'interfaccia del webservice SOAP. Questo file deve essere caricato dalla classe SOAP CLIENT. L'indirizzo è Dove: <ip-servizio> corrisponde all'ip del servizio, attualmente <chiave-api> chiave personale di accesso al servizio (32 caratteri alfanumerici) <nome-rivenditore> nome utente del rivenditore (url per reseller e subaccount) Ad esempio, se voglio usare SOAP per un subaccount del rivenditore NETFUN, inserisco: Changelog versione 1.1 Aggiunto supporto per le sessioni (permette di non inviare, ad ogni richiesta, user e psw): createsession existssession alivesession deletesession deleteallsession Altri metodi comuni: getcredit Metodi per rivenditori getcreditsubaccount addtransactionsubaccount addsubaccount 1

2 Funzioni SOAP (gestione sessioni) Protocollo di invio SOAP createsession (disponibile dalla versione 1.1) Permette la creazione di una sessione. Questo consente la possibilità di non inviare, per ogni richiesta, user e password username SI Stringa Nome utente accesso password SI Stringa Password di accesso expiryseconds NO Numero Indica i secondi di durata della sessione. Se non specificato la durata è di 3600 secondi (1 ora) deleteothersessions NO Numero Valori possibili 0 (zero) oppure 1 (uno) Se uno elimina le sessioni dello stesso utente disabilitando l'uso da altri client. OUTPUT Response Array/List/ Dictionary Array associativo/ Dictionary al cui interno contiene: sessionkey (stringa di 50 caratteri alfanumerici case sensitive): indica, in caso di successo, l'identificativo della sessione. Attenzione: maiuscole e minuscole sono differenti. Permette di cambiare la durata della sessione durante l'uso alivesession (disponibile dalla versione 1.1) sessionkey SI Stringa Chiave della sessione expiryseconds NO Numero Indica i secondi di durata della sessione a partire dalla richiesta Se non specificato la durata è di 3600 secondi (1 ora) OUTPUT Response Array/List/ Dictionary Array associativo/ Dictionary al cui interno contiene: expiryseconds (numero) indica il timestamp della scadenza impostata Interroga il database per controllare esistenza Sessione isvalidsession (disponibile dalla versione 1.1) sessionkey SI Stringa Chiave della sessione OUTPUT isvalid Numero indica se la chiave passata in sessionkey è valida (1 - uno) oppure no (0 - zero) 2

3 deletesession (disponibile dalla versione 1.1) Permette di eliminare una sessione sessionkey SI Stringa Chiave della sessione OUTPUT error Numero codice errore, se 0 nessun errore, altrimenti maggiore di 0 (vedi gestione errore) Permette di eliminare tutte le sessioni dell'utente. deleteallsession (disponibile dalla versione 1.1) username SI Stringa Nome utente accesso password SI Stringa Password di accesso OUTPUT error Numero codice errore, se 0 nessun errore, altrimenti maggiore di 0 (vedi gestione errore) 3

4 Funzioni SOAP (base) Protocollo di invio SOAP sendsmssimple (disponibile dalla versione 1.0) Permette invio semplice di SMS ad un contatto o lista di contatti. username / sessionkey password SI Stringa Nome utente accesso, se si utilizzano le sessioni passare la chiave della sessione (sessionkey) SI (solo se non si usano sessioni) Stringa Password di accesso Impostare stringa vuota se si usano le sessioni. numbers SI Stringa Destinatari (separati da spazio, virgola, punto e virgola o pipe ) Formato numero internazionale (se non specificato viene impostato automaticamente a +39) Esempio: , text SI Stringa Testo del messaggio. Può superare i 160 caratteri, viene concatenato automaticamente ed in modo trasparente. sender NO Stringa Mittente. Può essere numerico e/o alfanumerico Se vuoto viene inserito nome utente (=USERNAME) gateway NO Numero Gateway di invio, se non impostato o non valido viene spedito con il gateway 0 response -- Array/List/Di ctionary Array associativo/dictionary al cui interno contiene: sendingid (stringa di 7 caratteri case sensitive): indica, in caso di successo, l'identificativo alfanumerico di 7 caratteri. Attenzione: maiuscole e minuscole sono differenti. Serve per il recupero dei dati della spedizione. Esempio: trkgrab sendsmsadvanced (disponibile dalla versione 1.0) Permette invio SMS, sfruttando funzionalità avanzate. Questo metodo permette ad esempio di effettuare invii posticipati o di inviare sostituendo tokens o inviando ad esempio allo stesso numero in tutta tranquillità. Nome variabile Rich. Tipo Note username / sessionkey password SI Stringa Nome utente accesso, se si utilizzano le sessioni passare la chiave della sessione (sessionkey) SI (solo se non si usano sessioni) Stringa Password di accesso Impostare stringa vuota se si usano le sessioni. 4

5 numbers SI Array /List contenente tanti oggetti smsnumber (per ogni destinatario) Protocollo di invio SOAP Array/Dictionary/matrice di destinatari (smsnumber). Ogni smsnumber prevede: number numero formato internazionale tokens parti da sostituire nel testo, formato stringa query url, esempio: %NAME%=Mario+Rossi&%HELLO%=Ciao %DATE% e %TIME% sono riservate. id identificativo, per la spedizione. In caso di spedizione allo stesso numero, può essere necessario distinguere i vari SMS identificandoli. Se non viene specificato viene restituito uno 0. Vedi pagina esempi per maggiori dettagli text SI Stringa Testo del messaggio. Può superare i 160 caratteri, viene concatenato automaticamente ed in modo trasparente. sender NO Stringa Mittente. Può essere numerico e/o alfanumerico Se vuoto viene inserito nome utente (=USERNAME) options NO Oggetto: smsoptions Array/Matrice/Dictionary con opzioni. Attualmente le opzioni disponibili sono: gateway date (Accetta vari formati, indica la data di spedizione. Formati validi sono: :50:59 (YYYY-mm-dd HH:mm:ss) - +2 week (tra due settimane) - +1 month (tra un mese) - per altre opzioni vedi sintassi usata da strtotime di PHP. Attenzione non è legata a PHP, usa semplicemente la sintassi della stessa funzione. response -- Array/Dictionary Array/Dictionary/Matrice associativa al cui interno contiene: sendingid (stringa di 7 caratteri case sensitive): indica, in caso di successo, l'identificativo alfanumerico di 7 caratteri. Attenzione: maiuscole e minuscole sono differenti. Serve per il recupero dei dati della spedizione. Esempio: trkgrab Permette di ricevere i dati della consegna/spedizione. getdelivery (disponibile dalla versione 1.0) username / sessionkey password SI Stringa Nome utente accesso, se si utilizzano le sessioni passare la chiave della sessione (sessionkey) SI (solo se non si Stringa Password di accesso Impostare stringa vuota se si usano le sessioni. 5

6 usano sessioni) Protocollo di invio SOAP sendingid SI Stringa ID della spedizione, ricevuta in caso di spedizione. responsetype NO Stringa Default: JSON. Formati disponibili: JSON XML - CSV Vedi esempio per maggiori dettagli filters NO Oggetto: smsdeliveryfilters Array/Matrice/Dictionary Prevede vari filtri, sono: status (int), valori possibili sono: -2 (tutti, valore di default) -1 (in attesa) 0 (non consegnati) 1 (consegnati) 2 (non consegnati) + (consegnati) details (int) può assumero 0 per false o 1 per true. (in caso di true, carica dettagli/info extra valido solo per i formati JSON e XML) Vedi esempi per altri dettagli. response -- Array/Dictionary Array/Dictionary/Matrice associativa al cui interno contiene: error (numero) codice errore, se 0 nessun errore, altrimenti maggiore di 0 (vedi gestione errore) list (stringa)risultato della richiesta, dipende dal formato. (vedi esempi) format (stringa) restituisce il tipo di formato della lista. La lista dei dettagli, per ogni sms, include: (vedi struttura nella sezione Lista DELIVERY (risposta da getdelivery) sending_id solo in CSV - corrisponde ovviamente a response['sendingid'] negli altri due casi (vedi struttura risposta in esempi) sms_id attualmente non usato udh_num indica il numero dell'sms in caso di concatenato udh_max in caso di concatenato indica quanti sms udh_group in caso di concatenamento indica il gruppo dello stesso receiver destinatario custom_id l'id indicato (solo con spedizione advanced) dall'utente in fase di invio (solo per recuperare eventuali riferimenti) delivery_status (-1 = IN INVIO/DELIVERY NON RICHIESTO 0 = NON RICEVUTO 1 = RICEVUTO) indica lo stato della spedizione, vedere documentazione delivery_date in caso di ricezione/non ricezione indica la data dell'evento (formato: :23:05) delivery_code 6

7 in caso di errore ricezione indica il motivo, vedi documentazione netfun... date (solo con filters.details == 1) data di invio (che non corrisponde a quella di ricezione (formato: :23:05) text (solo con filters.details == 1) testo messaggio (con eventuali tokens sostituiti) gateway (solo con filters.details == 1) gateway di invio sender (solo con filters.details == 1) mittente delivery_idt (solo con filters.details == 1) non ancora usato, più che altro per assistenza. ATTENZIONE: la funzione getdelivery restituisce i numeri spediti. Eventuali numeri non spediti (o in fase di spedizione) e/o posticipati non verranno restituiti La funzione va richiamata in modo asincrono almeno 1 minuto dopo la spedizione (si consiglia 5 minuti) e ripeterla eventualmente solo se non si conosce lo status di tutti gli elementi della spedizione. nel caso di invio posticipato ovviamente va richiamata dopo la data. Tutti i numeri NON presenti in lista (ovviamente senza filtri sullo status) sono da considerare IN FASE DI INVIO. Infatti per velocizzare invii grossi l'invio tramite SOAP posticipa l'invio non aspettando l'invio dei singoli SMS Permette di ricevere il credito residuo username / sessionkey password getcredit (disponibile dalla versione 1.1) SI Stringa Nome utente accesso, se si utilizzano le sessioni passare la chiave della sessione (sessionkey) SI (solo se non si usano sessioni) Stringa response -- Array/Diction ary Password di accesso Impostare stringa vuota se si usano le sessioni. Array/Dictionary/Matrice associativa al cui interno contiene: credit (numero) restituisce il credito in millesimi, ad esempio per 12,45 restituisce Permette di ricevere la descrizione del codice errore. Attualmente solo in italiano. geterrordescr (disponibile dalla versione 1.0) errorcode SI Numero Codice errore numerico. errordescr -- Stringa Descrizione codice errore. Vedi gestione errori. Funzioni SOAP (rivenditori) 7

8 getcreditsubaccount (disponibile dalla versione 1.1) Permette di ricevere il credito residuo di un proprio subaccount username / sessionkey password SI Stringa Nome utente accesso, se si utilizzano le sessioni passare la chiave della sessione (sessionkey) SI (solo se non si usano sessioni) Stringa Password di accesso Impostare stringa vuota se si usano le sessioni. subaccountname SI Stringa Nome del proprio subaccount response -- Array/Diction ary Array/Dictionary/Matrice associativa al cui interno contiene: credit (numero) restituisce il credito in millesimi, ad esempio per 12,45 restituisce addtransactionsubaccount (disponibile dalla versione 1.1) Permette di aggiungere o togliere del credito ad un proprio subaccount username / sessionkey password SI Stringa Nome utente accesso, se si utilizzano le sessioni passare la chiave della sessione (sessionkey) SI (solo se non si usano sessioni) Stringa Password di accesso Impostare stringa vuota se si usano le sessioni. subaccountname SI Stringa Nome del proprio subaccount transactionvalue SI Numero Valore della transazione espresso in millesimi. Ad esempio per aggiungere il credito di 3,00 inserire 3000 Per togliere il credito di 0,50 inviare il valore (negativo) di -500 costsms NO Numero Solo se si usano i listini (abilitabili da area di amministrazione), se viene inviato questo valore e non si usano i listini viene restituito un errore 523 (vedi gestione errore per dettagli) Il valore deve essere espresso in millesimi (valore positivo), esempio per un costo di 7 centesimi inserire: 700 Se uguale a 0 viene usato il valore del listino base. transactiondescr NO Stringa Puoi specificare una descrizione della transazione, se vuota il valore sara: Addebito (per eliminazione credito) Ricarica credito (quando si aggiunge del credito) response -- Array/Diction ary Array/Dictionary/Matrice associativa al cui interno contiene: newcredit (numero) restituisce il credito risultante in 8

9 millesimi, ad esempio per 15,60 restituisce

10 Permette di aggiungere un nuovo subaccount Protocollo di invio SOAP addsubaccount (disponibile dalla versione 1.1) username / sessionkey password SI Stringa Nome utente accesso, se si utilizzano le sessioni passare la chiave della sessione (sessionkey) SI (solo se non si usano sessioni) Stringa subaccountinfo SI Oggetto subaccountinfo Password di accesso Impostare stringa vuota se si usano le sessioni. L'oggetto subaccountinfo è una matrice/array/dictionary che contiene le seguenti coppie chiave/valore: Chiave Richiesto Note username SI Nome utente univoco password SI Password di accesso E' richiesta particolare attenzione e soprattutto di non usare la stessa password per tutti i subaccount SI name NO Nome del cliente lastname NO Cognome del cliente tel NO Numero di telefono cel NO Numero mobile fax NO Numero fax address NO Indirizzo city NO Città cap NO C.A.P. province NO Provincia notes NO Eventuali note response -- Array/Dictionary Array/Dictionary/Matrice associativa al cui interno contiene: id (numero) restituisce l'id del subaccount appena inserito). 10

11 Lista DELIVERY (risposta da getdelivery) In base al formato richiesto, si possono ottenere le seguenti risposte. CSV (in rosso intestazione dati CSV) "sending_id";"sms_id";"udh_num";"udh_max";"udh_group";"receiver";"custom_id";"delivery_status";"delivery_date";"delivery_code" "at5w2ab";"4547";"1";"1";"";" ";"0";"-1";"---";"-" "at5w2ab";"4548";"1";"1";"";" ";"0";"-1";"---";"-" XML (sfondo in giallo solo se in filters details == 1; vedi getdelivery) <deliveryrequest sending_id="at5wab" version="1"> <items> <item id= 4547 > <udh group="" num="1" max="1"/> <receiver> </receiver> <delivery status="-1" code="-">---</delivery> <details> <sender></sender> <text>testo sms</text> <sms gateway="0" date=" :23:21" idt=" "/> </details> </item> </items> </deliveryrequest> JSON (sfondo in giallo solo se in filters details == 1; vedi getdelivery) Il formato JSON viene restituito come testo (come per XML e CSV) e va valutato per ottenere oggetto/matrice. In PHP5 esiste l'oggetto nativo json_decode { 'sendingid': 'at5wa', 'version': 1, 'items': [ { 'sms_id' : 4547, 'udh_num': 1, 'udh_max': 1, 'udh_group': '', 'receiver': ' ', 'custom_id': 0, 'delivery_status': -1, 'delivery_date': '---',//valorizzata solo se delivery_status == 1 oppure 0 'delivery_code': '-', 'date':' :23:21', 'text': 'Testo SMS', 'gateway': 4, 'sender': '', 'delivery_idt': ''//idt interno. } ] } 11

12 ERRORI Si possono avere 2 tipi di errori: Errori SOAP (in PHP5 usando soapclient si ha una eccezione di SoapFault) Questi devono essere gestiti internamente alla programmazione. Questo tipo di errori si verificano ad esempio, se il file wsdl indicato è irragiungibile o il percorso non valido, se si usano nomi funzioni non valide e/o se non si passano i tipi di variabili previste. Errori restituiti dalle funzioni. Questo genere di errore previsto, viene gestito dal webservice, in pratica ci sono condizioni in cui non è possibile procedere. Il codice dell'errore ha un suo significato, che volendo, è possibile recuperare tramite SOAP (funzione geterrordescr) Codice Errore Descrizione. 1 Dati login non impostati 2 Login non corretto 3 Chiave Sessione (sessionkey) non valida, non sei autorizzato a procedere 4 Chiave sessione (sessionkey) scaduta, ricreare sessione 5 Chiave API non abilitata. Entra nel pannello di controllo per recuperarla 6 La chiave che stai utilizzando non corrisponde con il profilo.se possiedi piu\' account devi utilizzare chiavi diverse. 10 Credito non sufficiente 11 Testo SMS vuoto 12 Data non valida 13 Data trascorsa 14 Gateway non valido 15 Mittente non valido 20 Nessun numero (destinatario) impostato 100 Codice spedizione non valido (in getdelivery) 500 Non sei un rivenditore abilitato 501 Nome subaccount vuoto o non valido 502 Subaccount inesistente o non attivo 510 Dati obbligatori assenti (in addsubaccount) 511 Username non valida (in addsubaccount) 512 Username esistente (in addsubaccount) 513 non valida (in addsubaccount) 514 esistente (in addsubaccount) 515 Password non valida (in addsubaccount) 516 Uno dei numeri indicati (cel, tel o fax) non e' valido (in addsubaccount) 517 Alcuni dei dati inviati non sono validi, controlla (in addsubaccount) 520 Transazione non puo' essere uguale a 0 (in addtransactionsubaccount) 521 Transazione di addebito superiore al credito del subaccount (in addtransactionsubaccount) 522 Costo SMS non puo' essere negativo (in addtransactionsubaccount) 523 Il tuo profilo non consente personalizzazione costo SMS. Abilita dal pannello di controllo i listini. (in addtransactionsubaccount) 999 Errore interno al server. Sovraccarico o problemi di altro genere. [nessuna risposta] In verde gli errori per gli strumenti dei soli rivenditori. Problemi di connessione o problemi interni allo script programmato. Va gestito internamente. 12

13 SOAP: Esempio avanzato in PHP5 Configurazione e inizializzazione tramite la classe SoapClient Inizio Sessione Uso delle funzioni tramite sessione 13

14 14