Socialmailer API

Introduzione alle API

Scritto da - marketing@socialmailer.it

Pubblicato il 16/02/2016

Le API (Application Programming Interface) di Socialmailer ti consentono di interfacciare la piattaforma con il tuo software o un qualsiasi software di terze parti per lo scambio dei dati quali contatti, campagne di marketing, statistiche sulle campagne inviate.

Mediante l'utilizzo di Web Service in tecnologia XML SOAP (Simple Object Access Protocol), un protocollo che permette di scambiare messaggi tra componenti software anche scritti in linguaggi differenti, Socialmailer mette a disposizione una serie di funzioni che possono essere invocate per esempio per recuperare  i  contatti della rubrica, le statistiche sull'esito dell'invio delle campagne di email marketing, la lista delle campagne inviate, per inserire nuovi contatti in rubrica, per creare un nuovo messaggio, settarne i contenuti e i destinatari.

L'utilizzo delle funzioni messe a disposizione dalle API del Web Service avviene mediante una comunicazione definita RPC-Call (Remote Procedure Call), che consente a un software qualsiasi di eseguire operazioni sulla piattaforma sfruttando la comunicazione web.

Il software richiedente dovrà inviare una comunicazione definita SOAP Request, alla quale Socialmailer risponderà con una SOAP Response.

SOAP Request e SOAP Response sono chiamati Messaggi SOAP, e sono contenuti in un documento in formato XML che prende il nome di SOAP Envelope.

Un messaggio SOAP è costituito da due parti, l'header e il body (intestazione e corpo del messaggio).

L'header non è obbligatorio, e contiene informazioni di meta-data facoltative.

Il body è invece quello che contiene le informazioni necessarie alla chiamata e il contenuto della risposta, che si definiscono payload, secondo una struttura definita da uno schema XML.

Gli schemi dei metodi disponibili, del formato delle chiamate, delle risposte, del formato dati compositi da passare come parametri in richiesta o da interpretare dalla risposta, sono contenuti nel documento di descrizione del Web Service, chiamato WSDL (Web Services Description Language).

Per poter utilizzare le API di Socialmailer, un software deve implementare un Web Service Client che gli permetta di inviare le SOAP Request e di interpretare le SOAP Response ricevute.

Puoi analizzare il documento WSDL del Web Service offerto da Socialmailer all'indirizzo

http://app.socialmailer.it/api/codice_cliente?wsdl

dove codice_cliente è il tuo codice cliente, lo stesso che utilizzi per accedere alla piattaforma sul web.

Per esaminare agevolmente le chiamate e le risposte SOAP e per eseguire dei test, puoi utilizzare il software SoapUI (https://www.soapui.org/).

SoapUI costruisce un Web Service Client in base a un documento WSDL indicato e implementa una serie di chiamate ai metodi del Web Service, che potrai utilizzare come test.

Su SoapUI crea un nuovo progetto di tipo SOAP e inserisci l'indirizzo su cui è pubblicato il file WSDL del Web Service di Socialmailer relativo al tuo dominio (codice cliente):

Procedi con il pulsante "OK" e attendi il caricamento e la costruzione del client Web Service con l'elenco dei metodi disponibili.

Troverai l'elenco delle chamate/procedure messe a disposizione dal Web Service sulla barra di sinistra.

Per eseguire una qualsiasi chiamata, dovrai inserire le credenziali di autenticazione (username e password) dell'account sulla piattaforma  oppure il token dell'account.

Puoi eseguire una chiamata selezionando la procedura desiderata dalla barra a sinistra di SoapUI, espandendo la voce mediante click sulla freccia a sinistra della voce e selezionando con doppio click la voce "Request 1" che compare sotto la voce espansa.

Nel box che compare, nella parte sinistra dovrai inserire le credenziali di accesso o con il token dell'account e gli eventuali altri parametri richiesti dalla procedura.

Puoi eseguire la chiamata selezionando l'icona verde "Play" posta in alto a sinistra nel box della richiesta.

Sullo stesso box della richiesta, nella parte destra comparirà la risposta: