Il web service risponde a un solo indirizzo per sito, con la chiave e le opzioni nella query string.
IndirizzoPOST https://<tuo-dominio>/webservice.aspx?Key=<chiave>&serialize=json
Il nome della pagina è webservice.aspx (maiuscole e minuscole sono indifferenti); l'estensione .aspx è necessaria. Usa sempre HTTPS: la chiave viaggia nell'indirizzo.
Parametri della query string
| Parametro | Valori | Obbligatorio | A cosa serve |
|---|
Key | la chiave ricevuta | Sì | Identifica chi chiama e i permessi. Senza una chiave valida e attiva la richiesta viene rifiutata. |
serialize | json oppure xml | No | Formato di richiesta e risposta. Con json si usa JSON; con qualsiasi altro valore, o senza parametro, XML. |
directshow | true | No | La risposta contiene solo l'elenco dei record del tipo richiesto, senza l'involucro WebServiceResponse (quindi senza stato ed errori). |
operationmulti | importmulti | No | Usa il protocollo ImportMulti: più tipi di dato in lettura nella stessa chiamata. |
operationbie | recreateafterexport | No | Esegue la ricostruzione che segue una pubblicazione completa: vedi qui. |
compression | true | No | Compatibilità con i client vecchi che inviavano il corpo compresso e poi codificato in Base64. Non usarlo nelle integrazioni nuove. |
La chiave e i permessi
L'amministratore del sito attiva il web service e crea una chiave per ogni programma che si collega. Per ogni chiave decide:
- se la chiave è attiva: una chiave disattivata viene rifiutata senza eseguire nulla;
- per ogni tipo di dato (per nome, per esempio
PRODUCT o DOCUMENT) se è permessa la lettura e se è permessa la scrittura. Un tipo che non compare nell'elenco della chiave non è accessibile.
| Operazione | Permesso richiesto |
|---|
QUERY | lettura sul tipo |
INSERTORMODIFY, DELETE, TRUNCATETABLE | scrittura sul tipo |
DELETEALLIMPORTCORRISPONDENZE, DELETEIMPORTCORRISPONDENZEBYTABLE | il tipo indicato in TypeObject deve essere nell'elenco della chiave |
| Conferme di ricezione | scrittura su RECEVEIDCLASS |
| ImportMulti | lettura su ogni tipo richiesto; per le conferme, scrittura su RECEVEIDCLASS e lettura sul tipo confermato |
Dai a ogni programma la sua chiave, con i soli permessi che gli servono: un sito che riceve il catalogo non ha bisogno di scrivere i documenti, un'app che legge gli ordini non ha bisogno di cancellare gli articoli.
Le risposte di rifiuto
Quando la chiamata viene rifiutata ricevi comunque un WebServiceResponse nel formato richiesto, con lo stato e il messaggio in ResponseString e in ErrorList.
| Messaggio | Status | Causa |
|---|
| Web Service disattivo. Nessuna richiesta disponibile | keyinvalid | Il web service non è attivo su questo sito. |
| Key non valida per la richiesta | keyinvalid | La chiave non esiste. |
| Key disattivata. Impossibile eseguire richieste | keyinvalid | La chiave esiste ma è disattivata. |
| Key non autorizzata per l'operazione richiesta | keyinvalid | Il tipo di dato non è tra quelli della chiave. |
| Key non autorizzata per l'operazione di scrittura | keyinvalid | Scrittura, cancellazione o svuotamento senza permesso di scrittura. |
| Key non autorizzata per l'operazione di lettura | keyinvalid | QUERY senza permesso di lettura. |
| Errore: Deserializzazione oggetto richiesta: … | ko | Il corpo non è un WebServiceRequest valido: in ErrorList trovi anche il testo ricevuto e la diagnostica del corpo. |
Le richieste rifiutate vengono anche scritte nel registro giornaliero degli errori del web service, che l'amministratore del sito può consultare quando un'integrazione non funziona.