metel web service gestione giacenze...
TRANSCRIPT
Dicembre 2016
Pagina 1
Emesso da: Studi e Analisi Funzionali Versione: 1.4
METEL WEB SERVICE
GESTIONE GIACENZE
DOCUMENTAZIONE
DISTRIBUTORE
Dicembre 2016
Pagina 2
OBBIETTIVO DEL DOCUMENTO .................................................................................................................................. 3
DISCLAIMER ....................................................................................................................................................................... 3
DESCRIZIONE DEL SERVIZIO ....................................................................................................................................... 3
ARCHITETTURA ................................................................................................................................................................ 4
TECNOLOGIE DI BASE ..................................................................................................................................................... 4
CLIENT DISTRIBUTORE .................................................................................................................................................. 5
LIBRERIE ............................................................................................................................................................................. 5
Esempio 1 ...................................................................................................................................................................... 6
Esempio 2 ...................................................................................................................................................................... 8
Esempio 3 .................................................................................................................................................................... 10
Esempio 4 .................................................................................................................................................................... 13
Esempio 5 .................................................................................................................................................................... 15
CLIENT .............................................................................................................................................................................. 18
WSDL .............................................................................................................................................................................. 18
TRACCIATI ........................................................................................................................................................................ 20
INVIO ................................................................................................................................................................................ 20
Descrizione campi ....................................................................................................................................................... 22
Ricezione ..................................................................................................................................................................... 24
Descrizione campi ....................................................................................................................................................... 25
CONTROLLI COLLETTORE.......................................................................................................................................... 27
LIMITATORE ...................................................................................................................................................................... 27
Limitazione frequenza Distributore ............................................................................................................................. 27
Limitazione frequenza Produttore ............................................................................................................................... 27
Vincolo numero di richieste per fascia oraria / giornaliera ....................................................................................... 28
CODICI DI ERRORE ............................................................................................................................................................. 29
IMPLEMENTAZIONE ORDINE URGENTE ................................................................................................................. 34
POLICY E REGOLE DEI SINGOLI PRODUTTORI .................................................................................................... 35
Dicembre 2016
Pagina 3
ERRATA CORRIGE
Ver. 1.4 corretto formato quantità da n15.5 a n10
OBBIETTIVO DEL DOCUMENTO
Fornire tutte le informazioni tecniche e funzionali necessarie ai fornitori di software dei Distributori
per integrare il servizio Metel di gestione delle giacenze in tempo reale.
DISCLAIMER
In questa fase dello sviluppo i tracciati di comunicazione non sono consolidati, nel corso dello
sviluppo delle prossime versioni questi potrebbero cambiare introducendo altri campi oppure
eliminandone di esistenti.
DESCRIZIONE DEL SERVIZIO
Il servizio Gestione Giacenze mette in grado i Distributori di interrogare la disponibilità prodotti
presso i Produttori ed eventualmente inviare un ordine urgente, secondo questo flusso di lavoro:
Il Distributore compila l’ordine dal suo gestionale.
Durante la compilazione delle singole righe o prima dell’evasione dell’intero ordine invoca
l’interrogazione dei dati tramite una funzionalità fruibile direttamente da un comando presente
sull’interfaccia del suo gestionale.
I dati sono inviati a Metel, che ha sua volta tramite accesso sicuro ribalterà la richiesta al
servizio messo a disposizione dal produttore.
Il Produttore risponde confermando o meno i dati richiesti ed eventualmente fornendo un ID
della transazione specifica da collocare nell’ordine EDI successivamente spedito dal
distributore.
Il Distributore potrà in seguito utilizzare un ulteriore funzionalità presente nel proprio
gestionale per confermare l’acquisto del materiale di cui ha chiesto la disponibilità di giacenza.
Dicembre 2016
Pagina 4
ARCHITETTURA
L’architettura generale della soluzione è descritta in figura.
Distributore Produ oreColle ore( (
Metel
1. Distributore è il sistema informativo / gestionale del Distributore;
2. Il riquadro chiaro è la componente client di interrogazione giacenza (predisposta da Metel);
3. Collettore è il componente Metel per la mediazione tra distributori e produttori.
4. Produttore è il sistema informativo del produttore.
TECNOLOGIE DI BASE
Il Collettore espone Web Service con tecnologia SOAP (binding su HTTPS). L’autenticazione del
Distributore avviene con WS-Security (limitatamente ai protocolli di autenticazione UsernameToken).
Il supporto ai Web Services è dato dall’uso di Axis2 1.6. Il supporto a WS-Security da Apache
Rampart.
Il client richiede Java 1.5.
Dicembre 2016
Pagina 5
CLIENT DISTRIBUTORE
Lato distributore l’integrazione potrà avvenire con due modalità:
1. Impiego di librerie Java basate su Axis2.
2. Utilizzo di un componente applicativo esterno (client).
3. Integrazione diretta tramite WSDL (SOAP).
LIBRERIE
È possibile interfacciare il servizio utilizzando la libreria Java integrata nel client (punto 2 dell’elenco
precedente) attraverso la classe MetelStocksClient. L’invocazione del servizio può avvenire con
due modalità:
1. passando le informazioni in una struttura dati Java;
2. passando l’input sotto forma di documento XML (vedi schema DTD in allegato);
La risposta è ottenibile in due modalità:
1. tramite una struttura dati Java;
2. sotto forma di flusso XML.
I passaggi per l’utilizzo della classe MetelStocksClient utilizzando flussi XML in richiesta e
risposta sono i seguenti. Per prima cosa è necessario istanziare la classe client:
MetelWebEDIStocksClient client = new MetelWebEDIStocksClient();
Quindi è necessario impostare le opzioni di connessione (username, password, endpoint del servizio
Metel). Questi sono passati come vettore di stringhe al metodo configure() della classe Options:
Options.configure({"MTL0001", "passwd",
"http://localhost:8105/axis2/services/StocksService"});
Quindi è necessario specificare il percorso di scrittura del file di output:
client.setOutputPath(outputPath);
Fatto questo è possibile invocare il servizio:
GetStocksRequestMessage request = new GetStocksRequestMessage();
// … valorizzazione campi
Dicembre 2016
Pagina 6
client.send(request);
Il risultato è prodotto nel file response.xml nel percorso di output.
A seguire alcuni esempi.
ESEMPIO 1
Il programma che segue valorizza una richiesta con il minimo numero di campi possibile e la invia al
servizio. Alla fine del programma, il file di output viene letto e stampato a console.
package it.metel.webedi.stocks.client.samples;
import it.metel.webedi.stocks.StocksServiceStub.GetStocksRequestMessage;
import it.metel.webedi.stocks.StocksServiceStub.StocksRequestHeader;
import it.metel.webedi.stocks.StocksServiceStub.StocksRequestRow;
import it.metel.webedi.stocks.client.MetelWebEDIStocksClient;
import it.metel.webedi.stocks.client.Options;
import java.io.File;
import java.io.FileReader;
import java.math.BigDecimal;
import java.math.BigInteger;
import org.apache.commons.io.IOUtils;
/**
* Minimal Sample - Stocks Service Invocation - Input passed by code, Output to
filesystem
*
* @author Administrator
*/
public class SampleClientInvocation1 {
public static void main(String[] args) throws Exception {
String v[] = {"MTL0001", "passwd",
"http://localhost:8105/axis2/services/StocksService"};
MetelWebEDIStocksClient client = new MetelWebEDIStocksClient();
Options.configure(v);
Dicembre 2016
Pagina 7
final String outputPath = System.getProperty("java.io.tmpdir") +
File.separator;
client.setOutputPath(outputPath);
//
// comment following block to show logs
//
System.setProperty("org.apache.commons.logging.Log",
"org.apache.commons.logging.impl.SimpleLog");
System.setProperty("org.apache.commons.logging.simplelog.showdatetime",
"false");
System.setProperty("org.apache.commons.logging.simplelog.log.httpclient.wire",
"error");
System.setProperty("org.apache.commons.logging.simplelog.log.org.apache.commons.h
ttpclient", "error");
//
// build minimal request
//
GetStocksRequestMessage request = new GetStocksRequestMessage();
StocksRequestHeader header = new StocksRequestHeader();
header.setType("G");
header.setPart("UNB:0006");
header.setMitt("UNB:0000");
header.setTa1154A("11036210158");
header.setTa1154B("11036210158");
StocksRequestRow row = new StocksRequestRow();
row.setRa1082A(BigInteger.ZERO);
row.setRa7140B("53087173");
row.setRa6060A(BigDecimal.TEN);
row.setRa7140C("DIS");
request.setHeader(header);
request.addRows(row);
Dicembre 2016
Pagina 8
//
// send request
//
client.send(request);
//
// print output
//
String response = IOUtils.toString( new FileReader(new File(outputPath,
"response.xml")));
System.out.println(response);
}
}
ESEMPIO 2
L’esempio che segue è simile al precedente, ma con la differenza che invece che impostare un
percorso di output viene impostato sul client un oggetto Writer, che viene impiegato per scrivere
l’output. Questo consente di reindirizzare l’output in memoria e quindi di non scrivere il file
response.xml sul filesystem.
package it.metel.webedi.stocks.client.samples;
import it.metel.webedi.stocks.StocksServiceStub.GetStocksRequestMessage;
import it.metel.webedi.stocks.StocksServiceStub.StocksRequestHeader;
import it.metel.webedi.stocks.StocksServiceStub.StocksRequestRow;
import it.metel.webedi.stocks.client.MetelWebEDIStocksClient;
import it.metel.webedi.stocks.client.Options;
import java.io.StringWriter;
import java.math.BigDecimal;
import java.math.BigInteger;
/**
* Minimal Sample - Stocks Service Invocation - Input passed by code, Output to
memory
*
* @author Administrator
*/
Dicembre 2016
Pagina 9
public class SampleClientInvocation2 {
public static void main(String[] args) throws Exception {
String v[] = {"MTL0001", "passwd",
"http://localhost:8105/axis2/services/StocksService"};
MetelWebEDIStocksClient client = new MetelWebEDIStocksClient();
Options.configure(v);
StringWriter writer = new StringWriter();
client.setWriter( writer );
//
// comment following block to show logs
//
System.setProperty("org.apache.commons.logging.Log",
"org.apache.commons.logging.impl.SimpleLog");
System.setProperty("org.apache.commons.logging.simplelog.showdatetime",
"false");
System.setProperty("org.apache.commons.logging.simplelog.log.httpclient.wire",
"error");
System.setProperty("org.apache.commons.logging.simplelog.log.org.apache.commons.h
ttpclient", "error");
//
// build minimal request
//
GetStocksRequestMessage request = new GetStocksRequestMessage();
StocksRequestHeader header = new StocksRequestHeader();
header.setType("G");
header.setPart("UNB:0006");
header.setMitt("UNB:0000");
header.setTa1154A("11036210158");
header.setTa1154B("11036210158");
StocksRequestRow row = new StocksRequestRow();
row.setRa1082A(BigInteger.ZERO);
Dicembre 2016
Pagina 10
row.setRa7140B("53087173");
row.setRa6060A(BigDecimal.TEN);
row.setRa7140C("DIS");
request.setHeader(header);
request.addRows(row);
//
// send request
//
client.send(request);
//
// print output
//
System.out.println(writer.toString());
}
}
ESEMPIO 3
Questo esempio mostra come valorizzare l’input partendo da un flusso presente in memoria.
package it.metel.webedi.stocks.client.samples;
import it.metel.webedi.stocks.client.MetelWebEDIStocksClient;
import it.metel.webedi.stocks.client.Options;
import java.io.StringReader;
import java.io.StringWriter;
/**
* Minimal Sample - Stocks Service Invocation - Input from memory, Output to
memory
*
* @author Administrator
*/
public class SampleClientInvocation3 {
Dicembre 2016
Pagina 11
static String request = "<?xml version=\"1.0\" encoding=\"UTF-8\"?> "
+ "<!DOCTYPE request SYSTEM
\"http://www.metel.it/webedi/stocks/StocksRequest.dtd\">"
+ "<request>"
+ " <header>"
+ " <type>G</type>"
+ " <ta1004a>000002847</ta1004a>"
+ " <part>UNB:0006</part>"
+ " <mitt>UNB:0000</mitt>"
+ " <ta1154a>piva001</ta1154a>"
+ " <ta1154b>piva002</ta1154b>"
+ " <ta1154c>pc001</ta1154c>"
+ " <ta1154d>piva003</ta1154d>"
+ " <tb3036></tb3036>"
+ " <tb3042a></tb3042a>"
+ " <tb3164a></tb3164a>"
+ " <tb3229a></tb3229a>"
+ " <tb3251a></tb3251a>"
+ " <tb3207a></tb3207a>"
+ " <fl_fc_extra>N</fl_fc_extra>"
+ " <tc4440/>"
+ " <tc4453a>1</tc4453a>"
+ " <no_resrv></no_resrv>"
+ " <mail>[email protected]</mail>"
+ " <requestId></requestId>"
+ " <sessionId></sessionId>"
+ " </header>"
+ " <rows>"
+ " <row id=\"1\">"
+ " <ra1082a>1</ra1082a>"
+ " <ra7140b>53087173</ra7140b>"
+ " <ra6060a>3</ra6060a>"
+ " <ra7140c>DIS</ra7140c>"
+ " <fl_qty_nc></fl_qty_nc>"
+ " <fl_data_chged></fl_data_chged>"
+ " </row>"
+ " </rows>"
Dicembre 2016
Pagina 12
+ "</request>";
public static void main(String[] args) throws Exception {
String v[] = {"MTL0001", "passwd",
"http://localhost:8105/axis2/services/StocksService"};
MetelWebEDIStocksClient client = new MetelWebEDIStocksClient();
Options.configure(v);
StringWriter writer = new StringWriter();
client.setWriter( writer );
client.setReader( new StringReader(request) );
//
// comment following block to show logs
//
System.setProperty("org.apache.commons.logging.Log",
"org.apache.commons.logging.impl.SimpleLog");
System.setProperty("org.apache.commons.logging.simplelog.showdatetime",
"false");
System.setProperty("org.apache.commons.logging.simplelog.log.httpclient.wire",
"error");
System.setProperty("org.apache.commons.logging.simplelog.log.org.apache.commons.h
ttpclient", "error");
//
// send request
//
client.send();
//
// print output
//
System.out.println(writer.toString());
}
}
Dicembre 2016
Pagina 13
ESEMPIO 4
Il programma che segue valorizza una richiesta con il minimo numero di campi possibile e la invia al
servizio. Alla fine del programma, alcuni campi della struttura dati di ritorno vengono stampati a
console.
package it.metel.webedi.stocks.client.samples;
import it.metel.webedi.stocks.StocksServiceStub.GetStocksRequestMessage;
import it.metel.webedi.stocks.StocksServiceStub.GetStocksResponseMessage;
import it.metel.webedi.stocks.StocksServiceStub.StocksRequestHeader;
import it.metel.webedi.stocks.StocksServiceStub.StocksRequestRow;
import it.metel.webedi.stocks.client.MetelWebEDIStocksClient;
import it.metel.webedi.stocks.client.Options;
import java.io.File;
import java.math.BigDecimal;
import java.math.BigInteger;
/**
* Minimal Sample - Stocks Service Invocation - Input and Output managed by code
*
* @author Administrator
*/
public class SampleClientInvocation4 {
public static void main(String[] args) throws Exception {
String v[] = {"TST0001", "passwd",
"http://localhost:8105/axis2/services/StocksService"};
MetelWebEDIStocksClient client = new MetelWebEDIStocksClient();
Options.configure(v);
final String outputPath = System.getProperty("java.io.tmpdir") +
File.separator;
client.setOutputPath(outputPath);
//
Dicembre 2016
Pagina 14
// comment following block to show logs
//
System.setProperty("org.apache.commons.logging.Log",
"org.apache.commons.logging.impl.SimpleLog");
System.setProperty("org.apache.commons.logging.simplelog.showdatetime",
"false");
System.setProperty("org.apache.commons.logging.simplelog.log.httpclient.wire",
"error");
System.setProperty("org.apache.commons.logging.simplelog.log.org.apache.commons.h
ttpclient", "error");
//
// build minimal request
//
GetStocksRequestMessage request = new GetStocksRequestMessage();
StocksRequestHeader header = new StocksRequestHeader();
header.setType("G");
header.setPart("UNB:0006");
header.setMitt("UNB:0000");
header.setTa1154A("11036210158");
header.setTa1154B("11036210158");
StocksRequestRow row = new StocksRequestRow();
row.setRa1082A(BigInteger.ZERO);
row.setRa7140B("53087173");
row.setRa6060A(BigDecimal.TEN);
row.setRa7140C("DIS");
request.setHeader(header);
request.addRows(row);
//
// send request
//
client.send(request);
GetStocksResponseMessage response = client.getResponse();
Dicembre 2016
Pagina 15
System.out.println("========================================");
System.out.println("session id " + response.getHeader().getSessionId());
System.out.println("request id " + response.getHeader().getRequestId());
System.out.println("rows " + response.getRows().length);
}
}
ESEMPIO 5
Questo esempio mostra come gestire eventuali errori restituiti dal server.
package it.metel.webedi.stocks.client.samples;
import it.metel.webedi.stocks.Fault;
import it.metel.webedi.stocks.StocksServiceStub.GetStocksRequestMessage;
import it.metel.webedi.stocks.StocksServiceStub.StocksRequestHeader;
import it.metel.webedi.stocks.StocksServiceStub.StocksRequestRow;
import it.metel.webedi.stocks.client.MetelWebEDIStocksClient;
import it.metel.webedi.stocks.client.Options;
import java.math.BigDecimal;
import java.math.BigInteger;
/**
* Minimal Sample - Stocks Service Invocation - Input and Output managed by code
*
* @author Administrator
*/
public class SampleClientInvocation5 {
public static void main(String[] args) throws Exception {
String v[] = {"TST0001", "passwd",
"http://localhost:8105/axis2/services/StocksService"};
MetelWebEDIStocksClient client = new MetelWebEDIStocksClient();
Options.configure(v);
//
Dicembre 2016
Pagina 16
// comment following block to show logs
//
System.setProperty("org.apache.commons.logging.Log",
"org.apache.commons.logging.impl.SimpleLog");
System.setProperty("org.apache.commons.logging.simplelog.showdatetime",
"false");
System.setProperty("org.apache.commons.logging.simplelog.log.httpclient.wire",
"error");
System.setProperty("org.apache.commons.logging.simplelog.log.org.apache.commons.h
ttpclient", "error");
//
// build minimal request
//
GetStocksRequestMessage request = new GetStocksRequestMessage();
StocksRequestHeader header = new StocksRequestHeader();
header.setType("G");
header.setPart("UNB:0006");
header.setMitt(" ");
header.setTa1154A("11036210158");
header.setTa1154B("11036210158");
StocksRequestRow row = new StocksRequestRow();
row.setRa1082A(BigInteger.ZERO);
row.setRa7140B("53087173");
row.setRa6060A(BigDecimal.TEN);
row.setRa7140C("DIS");
request.setHeader(header);
request.addRows(row);
//
// send request
//
try {
client.send(request);
} catch (Exception e) {
Dicembre 2016
Pagina 17
if (e instanceof Fault) {
Fault f = (Fault)e;
System.err.println("Ricevuto SOAP Fault");
System.err.println("=============================================================
===================");
System.err.println("Codice errore : " +
f.getFaultMessage().getErrorCode());
System.err.println("Descrizione : " +
f.getFaultMessage().getErrorMessage());
System.err.println("=============================================================
===================");
}
}
}
}
Dicembre 2016
Pagina 18
CLIENT
Nell’interfacciamento tramite client, invece, la comunicazione dati è svolta dal componente
applicativo esterno. Il passaggio dei dati dal sistema software del distributore (in breve SSD) al client
è responsabilità del primo e avviene tramite scambio file. La sequenza è la seguente:
1. SSD produce un file nella directory d’installazione del client che contiene le informazioni di
richiesta secondo il tracciato sopra indicato (vedi schema DTD nelle appendici).
2. SSD lancia come processo esterno il client e attende il suo termine.
3. Il client restituisce il codice d’errore (o zero nel caso di esito positivo) e produce un file di
risposta nella directory di cui sopra. Il formato del file potrebbe essere differente nel caso di
errore di comunicazione o esito positivo. Se il file esiste (per esempio per una comunicazione
precedente) viene sovrascritto. Nel file è presente un timestamp e un ID della richiesta per
correlare la risposta a una richiesta specifica.
4. SSD riceve il codice d’errore dal client e legge il file di risposta elaborandolo opportunamente.
WSDL
In questo caso è responsabilità del sistema software del distributore implementare il binding su
HTTPS e la compilazione delle intestazioni di sicurezza richieste da WS-Security. La policy di
sicurezza è la seguente:
<!-- WS-Policy -->
<wsp:Policy xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
wssecurity-utility-1.0.xsd"
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
wsu:Id="UTOverTransport">
<wsp:ExactlyOne>
<wsp:All>
<sp:TransportBinding
xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
<wsp:Policy>
<sp:TransportToken>
<wsp:Policy>
<sp:HttpsToken RequireClientCertificate="false"/>
</wsp:Policy>
</sp:TransportToken>
<sp:AlgorithmSuite>
<wsp:Policy>
<sp:Basic128/>
</wsp:Policy>
</sp:AlgorithmSuite>
Dicembre 2016
Pagina 19
<sp:Layout>
<wsp:Policy>
<sp:Lax/>
</wsp:Policy>
</sp:Layout>
<!--sp:IncludeTimestamp/-->
</wsp:Policy>
</sp:TransportBinding>
<sp:SignedSupportingTokens
xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
<wsp:Policy>
<sp:UsernameToken
sp:IncludeToken="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToke
n/AlwaysToRecipient"/>
<!--wsp:Policy>
<sp:WssUsernameToken10/>
</wsp:Policy-->
</wsp:Policy>
</sp:SignedSupportingTokens>
</wsp:All>
</wsp:ExactlyOne>
</wsp:Policy>
Dicembre 2016
Pagina 20
TRACCIATI
Le funzioni esposte dal servizio Giacenza sono due: verifica giacenza e conferma ordine. Entrambe le
funzionalità espongono lo stesso tracciato.
Definizione del WSDL : http://webservice.cloudmetel.com/WebService/services/StocksService?wsdl
INVIO
(rif. Standard Metel, tracciato Ordine)
Gruppo Campo Dim. Tipo Descrizione G O
Testata TYPE 1 C Tipo richiesta
Valori Ammessi:
G – giacenza, O – ordine.
M M
TA1004A 16 C Numero dell’ordine O M
PART 20 C UNB destinatario M M
MITT 20 C UNB mittente M M
TA1154A 20 C P.IVA compratore M M
TA1154B 20 C P.IVA venditore M M
TA1154C 20 C Punto di consegna O C
TA1154D 20 C P.IVA dest.fattura O O
TB3036 70 C Nome del destinatario O C
TB3042A 35 C Via e numero / Casella postale O C
TB3164A 35 C Nome della città O C
TB3229A 9 C Codice provincia O C
TB3251A 9 C Codice CAP O C
TB3207A 3 C Codice nazione O C
FL_FC_EXTRA 1 C Spedizione espressa
Valori Ammessi: S / N
O O
TC4440 350 C Note operative sul documento.
Nota: Il Produttore ha facoltà
di ignorare l’indicazione
operativa (campi TC4440 e
TC4453A)
O O
Dicembre 2016
Pagina 21
TC4453A 3 N Flag nota rilevante all’ordine
Valori Ammessi
1 – non determina intervento,
3 – determina intervento
C C
NO_RESERV 20 C O O
MAIL 20 C Indirizzo di posta utente O O
SESSIONID 36 C ID univoco di sessione C M
REQUESTID 36 C ID univoco di richiesta N/A N/A
Righe RA1082A 6 N Numero di riga M M
RA7140B 16 C Codice articolo M M
RA6060A 10 N Quantità M M
RA7140C 3 C Sigla marchio M M
FL_QTY_NC 1 C Solo se la quantità non è
variata (richiede al Produttore
di rispondere solo Si/No e di
non proporre quantità
differenti).
Valori Ammessi: S / N
O O
FL_DATA_CHGED 1 C Flag dati variati rispetto alla
precedente verifica di
giacenza.
Valori Ammessi: S / N
N/A N/A
Dicembre 2016
Pagina 22
DESCRIZIONE CAMPI
TESTATA
TYPE
Indica il tipo di richiesta. Valori ammessi:
G – Verifica di giacenza;
O – Invio di un ordine.
Per poter inviare un ordine è necessario prima aver eseguito un controllo di giacenza e fornire l’ID
Sessione ricevuto in risposta alla prima richiesta.
TA1154C, TB3036, TB3042A, TB3164A, TB3229A, TB3251A, TB3207A
In caso d’ordine, se specificato TA1154C i campi da TB3042A a TB3207A non sono obbligatori; se
TA1154C non è specificato i campi da TB3042A a TB3207A sono obbligatori.
TC4453A
Obbligatorio se TC4440 è valorizzato.
Indirizzo di comunicazione con il cliente. Se non è specificato viene utilizzato quello censito in
WebEDI.
SESSIONID
Il Distributore è potenzialmente in grado di eseguire più richieste di giacenza consecutive e terminare
o meno la sequenza con una richiesta di ordine (ovviamente all’interno dei limiti d’uso imposti dal
Collettore). Il sistema offre la possibilità di correlare più richieste che sono relative alla stessa
sessione d’utilizzo attraverso un ID di sessione.
Questa informazione è generata dal Collettore sulla prima richiesta di giacenza; la prima richiesta di
una sessione è tale se il campo SESSIONID in input è vuoto. Il Distributore ha quindi l’onere di
gestire l’avvio delle sessioni attraverso elementi opportuni del software gestionale. Ogni richiesta
successiva, ma correlata dal punto di vista logico alla precedente, dovrà vedere valorizzato, nel
tracciato di input, il campo SESSIONID con il valore opportuno.
REQUESTID
(Informazione generata dal Collettore Metel)
Il campo REQUESTID è un UUID generato dal Collettore che identifica ogni singola richiesta
eseguita dal Distributore. È un’informazione obbligatoria generata dal Collettore e inviata al
Produttore; sebbene sia presente nel tracciato che utilizza il Distributore, un eventuale dato generato
da quest’ultimo viene ignorato. Allo stesso modo è ignorato nel tracciato di risposta ricevuto dal
Produttore, in quanto è compito del Collettore valorizzarlo nella risposta restituita al Distributore.
Dicembre 2016
Pagina 23
RIGHE
FL_QTY_NC
Flag che indica se la quantità non è variata (richiede al Produttore di rispondere solo Si/No e di non
proporre quantità differenti).
Valori Ammessi: S / N
Il produttore potrebbe non gestire questa informazione. Se fosse gestito, su richiesta del distributore
restituirà la riga valorizzando il campo RA1229A con il valore 7 (Annullato).
FL_DATA_CHGED
Indica al Produttore che i dati della richiesta attuale sono variati rispetto a richieste precedenti
all’interno della stessa sessione di lavoro. Questo dato ha semplice valenza informativa ed è
determinato dal Collettore Metel.
Dicembre 2016
Pagina 24
RICEZIONE
(rif. Standard Metel, tracciato Conferma d’Ordine)
Gruppo Campo Dim. Tipo Descrizione G O
Testata TYPE 1 C Tipo richiesta M M
TA4343A 3 C Esito richiesta
Valori Ammessi:
AP = accettato
CA = accettato con modifiche
RE = rifiutato
M M
TC4440 350 C Descrizione esito O O
NO_TA1004 16 C Numero di conferma ordine O C
NO_RESERV 20 C Numero prenotazione O C
TD5004A 18.5 N Costi di trasporto (FC) O O
SESSIONID 36 C ID univoco sessione M M
REQUESTID 36 C ID univoco transazione Metel M M
RESULT_LEVEL 1 C Esito tecnico richiesta
(controlli Collettore). Valori
ammessi:
E – errore;
W – warning;
I – info.
O O
RESULT_CODE 5 C Codice di errore C C
RESULT_MSG 350 C Descrizione esito tecnico
richiesta
C C
Righe RA1082A 6 N Numero di riga M M
RA7140B 16 C Codice articolo M M
RA7140C 3 C Sigla marchio M M
RA1229A 3 C Accettato / Modificato /
Rifiutato
Valori Ammessi: 5, 6, 7
M M
Dicembre 2016
Pagina 25
RB4440 350 C Note automatiche da sistema O O
RA2380A 8 D Data consegna
(f.to ISO 8601, AAAA-MM-
GG)
C C
RA2380F 8 D Data di consegna garantita
(f.to ISO 8601, AAAA-MM-
GG)
O O
RA6060B 10 N Quantità C C
VA_RA5118 15.5 N Prezzo C C
VA_CHARGE 15.5 N Sovrapprezzo O O
FL_DATA_CHGED 1 C Flag dati variati rispetto alla
richiesta. Valori ammessi: S /
N.
O O
DESCRIZIONE CAMPI
TESTATA
TC4440
Si consiglia di valorizzare opportunamente il campo in caso di rifiuto.
RESULT_CODE, RESULT_MSG
Restituiti nel caso RESULT_LEVEL sia valorizzato.
RA2380A, RA6060B
Valorizzati nel caso RA1229A vale 5 o 6.
risposta del produttore a fronte di un richiesta di ordine urgente (TYPE=O)
NO_TA1004
Numero conferma d’ordine restituito dal produttore
NO_RESERV
Numero prenotazione Merce restituito dal produttore (se non gestisce la conferma d’ordine via WS)
A fronte di una Conferma Accettata (TA4343A = AP) il produttore dovrà restituire il numero della
Conferma (NO_TA1004A) o il numero di Prenotazione Merce (NO_RESERV)
Nel caso la Conferma Accettata modifichi la quantità richiesta (TA4343A = CA) o rifiuti la quantità
richiesta (TA4343A = RE), come avviene sul sito del produttore, entrambi i campi che rappresentano
il numero di conferma o di prenotazione devono essere vuoti (NO_TA1004A e NO_RESERV).
Dicembre 2016
Pagina 26
.
LEGENDA
Tipi di dato: C – Carattere, N – Numerico, D – Data.
(**) Obbligatorietà: O – Opzionale, M – Mandatorio, C – Condizionato.
Dicembre 2016
Pagina 27
CONTROLLI COLLETTORE
Il collettore esegue una serie di controlli sulle richieste ricevute dai Distributori:
1. Verifica correttezza credenziali d’accesso (username / password);
2. Verifica delle relazioni tra distributore / produttore;
3. Controllo consistenza richiesta / risposta;
4. Gestione sessioni di lavoro;
5. Limitatore frequenza richieste al produttore (tempo minimo tra una richiesta e l’altra / limite
numero massimo di richieste orarie);
Le informazioni relative alle richieste ricevute dai Distributori sono memorizzate nel sistema in
un opportuno sistema di tracking.
LIMITATORE
Verifica che il mittente non stia richiedendo troppe informazioni o con una frequenza troppo elevata
sulla base delle politiche impostate. Dai dati di tracking il sistema è in grado di rilevare la storia delle
richieste di un determinato mittente (Distributore):
nei confronti di qualsiasi destinatario;
nei confronti di uno specifico destinatario.
Il sistema può anche determinare, sempre analizzando i dati di tracking, la storia delle richieste
arrivate a un determinato destinatario (Produttore):
da qualsiasi mittente;
da parte di uno specifico mittente.
Il componente di limitazione richieste ha lo scopo di evitare che un dato Produttore riceva troppe
richieste concorrenti / successive, indipendentemente dall’UNB mittente.
LIMITAZIONE FREQUENZA DISTRIBUTORE
Questo controllo viene eseguito sul Collettore. In fase di ricezione, dopo le prime verifiche di
relazione, viene controllata la storia recente (nel tracking) del mittente e individuato il timestamp T1
di ultima richiesta. Se questo è inferiore a una soglia definita nella configurazione del sistema (valida
per tutti i Distributori) la richiesta viene rifiutata.
LIMITAZIONE FREQUENZA PRODUTTORE
Questo controllo viene eseguito sul Collettore, dopo la verifica precedente. Vengono controllati i dati
di tracking del destinatario per individuare il timestamp T1 di ultima richiesta (indipendentemente dal
mittente). Se questo è inferiore a una soglia definita nel profilo Produttore (vedi par.succ.) la richiesta
viene rifiutata.
Dicembre 2016
Pagina 28
VINCOLO NUMERO DI RICHIESTE PER FASCIA ORARIA / GIORNALIERA
Un ulteriore verifica è relativa al numero di richieste inviate da ogni singolo Distributore nell’arco di
un’ora del giorno (p.e. dalle 14.00 alle 15.00) e nel corso di un giorno solare (dalle 0.00 alle 24.00).
Se questi valori superano una soglia definita da configurazione di sistema (valida per tutti i
Distributori), la richiesta viene rifiutata con opportuno messaggio d’errore. Il conteggio delle richieste
avviene solo sulle righe che fanno riferimento a richieste andate a buon fine (campo T4 valorizzato).
Dicembre 2016
Pagina 29
CODICI DI ERRORE
Tabella dei codici di errore restituiti dal sistema.
Le descrizioni restituite dal sistema sono orientati ad un operatore tecnico/funzionale, si consiglia
un’eventuale gestione interna del messaggio d’errore da erogare con informazioni più ergonomiche
rivolte all’utente finale. In questa lista sono contemplate sia errori tecnici che funzionali.
Gruppo Codice Descrizione Note
Interni ERR000 Internal error Generico errore di consistenza interna.
Gestione
sessioni
ERR101 Session expired La sessione specificata nella richiesta è
scaduta. Tra la richiesta attuale e la
precedente è passato un tempo superiore a
quello consentito. Far riferimento al
documento di politiche d’uso relativo al
servizio.
ERR102 Session not found Il codice di sessione passato non esiste.
La sessione specificata nella richiesta non è
presente nella tabella che contiene l’elenco
delle sessioni (ST_SESSION).
ERR103 Session not specified Nella richiesta non è stata indicata la
sessione: il relativo campo è vuoto.
Relazioni ERR201 Missing mitt Il campo MITT nella richiesta è vuoto.
ERR202 Mitt not active L’UNB specificato nel campo MITT non è
attivato nel sistema WebEDI (l’UNB ha
impostato a zero il campo ENABLED nella
tabella UNB).
ERR203 Mitt username
mismatch
Il MITT specificato non appartiene all’utente
con cui è stata fatta l’autenticazione.
ERR204 Service not enabled Per l’UNB mittente o destinatario, non è
attivo il servizio Giacenze nella
configurazione di WebEDI (Il servizio
giacenze non è attivo nella tabella
UNB_SIMPLE_SERVICES).
ERR205 Missing part Il campo PART nella richiesta è vuoto.
ERR206 Part not active L’UNB specificato nel campo PART non è
attivato nel sistema WebED (l’UNB ha
impostato a zero il campo ENABLED nella
Dicembre 2016
Pagina 30
tabella UNB).
ERR207 No relationship Non risulta che gli UNB indicati in PART e
MITT abbiano una relazione configurata in
WebEDI (tabella RELATIONSHIP per il
tipo di documento ORDERS).
ERR208 (riservato) (riservato)
ERR209 Service not
implemented by Seller
Indica che il servizio richiesto (Giacenza o
Ordine, in funzione del valore del campo
TYPE nella richiesta) non è supportato dal
Produttore. I Produttori che aderiscono al
servizio Giacenze mettono a disposizione il
servizio di richiesta giacenze, ma potrebbero
non rendere disponibile il servizio ordine
urgente (configurazione
ST_SELLER_PROFILES).
ERR210 Seller not activated La richiesta inviata è indirizzata a un
mittente che non è configurato nei profili dei
Produttori che aderiscono al servizio.
Validazione
richiesta
ricevuta dal
Distributore
ERR301 Too much request
rows
Il numero di righe di richiesta eccede il
numero massimo di righe messo a
disposizione dallo specifico Produttore a cui
è stata inviata la richiesta. Ciascun
Produttore ha la facoltà di definire il numero
massimo di righe che possono essere
veicolate a ogni richiesta. Questo parametro
è configurato in ST_SELLER_PROFILES
per l’utente destinatario.
ERR302 Request mandatory
fields not found
I campi obbligatori della richiesta non sono
valorizzati (vedi tracciato).
ERR303 Request fields size
error
Le lunghezze dei campi nella richiesta
eccedono la dimensione prevista (vedi
tracciato).
ERR304 Should have at least
one row
La richiesta è priva di righe: ciascuna
richiesta deve avere almeno una riga
prodotto per essere considerata valida.
ERR305 RA1082A progress
error
Il valore del campo RA1082A non è
numericamente progressivo nelle righe. È
necessario che all’interno di una stessa
Dicembre 2016
Pagina 31
richiesta i valori dei campi RA1082A nelle
diverse righe sia progressivo. Non è
necessario che la numerazione inizi da 1 o
che incrementi di 1 o 5 unità: la
progressione può essere arbitraria. Esempi
validi sono: 1, 2, 3. Oppure: 5, 15, 20, 25.
Oppure: 10, 20, 30, 40.
ERR306 RA6060A not positive Il valore del campo RA6060A non è
maggiore di zero. Non è possibile richiedere
la disponibilità di un prodotto indicando una
quantità uguale a zero: è necessario
richiedere almeno un prodotto.
Validazione
risposta
ricevuta dal
Produttore
(*) questi
codici di
errore non
sono
bloccanti e
constituiscono
controlli sulle
risposte
restituite dal
Produttore.
ERR351 Response mandatory
fields not found
I campi obbligatori della risposta non sono
valorizzati (vedi tracciato).
ERR352 Response fields size
error
Le lunghezze dei campi nella risposta
eccedono la dimensione prevista (vedi
tracciato).
ERR353 Response field value
not valid
Il contenuto dei campi di risposta non
assume nessun valore tra quelli previsti.
ERR354 RA2380A not valid La data RA2380A è inferiore a oggi. La data
di consegna deve essere oggi o una data
futura.
ERR355 RA2380F not valid La data RA2380F è inferiore a oggi. La data
di consegna garantita deve essere oggi o una
data futura.
ERR356 RA6060B not positive Il valore RA6060B non è un numero
maggiore di zero. Non è corretto restituire
una quantità a zero. Nel caso il Produttore
voglia annullare la riga deve valorizzare il
campo RA1229A a 7.
ERR357 No price found
(VA_RA5118)
L’importo VA_RA5118 non è un numero
maggiore di zero. Se questo campo (prezzo)
viene restituito, è necessario che sia
maggiore di zero. Il campo è mandatorio se
RA1229A vale 5 o 6. Se RA1229A vale 7 il
campo è opzionale. In questo caso può
essere inviato oppure no.
ERR358 No surprice found L’importo VA_CHARGE non è un numero
Dicembre 2016
Pagina 32
(VA_CHARGE) maggiore di zero. Se questo campo
(sovraprezzo) viene restituito, è necessario
che sia maggiore di zero. Il campo è
opzionale.
ERR359 Request row number
less than response row
number
Il numero di righe della richiesta è inferiore
al numero di righe nella risposta. È
necessario che il Produttore restituisca lo
stesso numero di righe ricevute nella
richiesta. Se desidera rifiutare una riga è
necessario valorizzare il campo RA1229A a
7.
ERR360 Response row number
less than request row
number
Il numero di righe della risposta è inferiore
al numero di righe nella richiesta. È
necessario che il Produttore restituisca lo
stesso numero di righe ricevute nella
richiesta. Se desidera rifiutare una riga è
necessario valorizzare il campo RA1229A a
7.
ERR361 RA1082A content
mismatch
Non conformità del campo indicato tra
richiesta e risposta. Il sistema confronta riga
per riga la richiesta inviata al Produttore e la
risposta ricevuta dallo stesso e verifica che i
campi RA1082A, RA7140B, RA7140C
(numero riga, codice articolo e sigla
marchio) siano corrispondenti. In caso
negativo solleva una segnalazione.
ERR362 RA7140B content
mismatch
ERR363 RA7140C content
mismatch
ERR364 RA6060B not greater
than request
RA6060A
La quantità di risposta nella riga i-esima non
è inferiore o uguale a quella di richiesta. Il
Produttore ha facoltà di soddisfare la
quantità richiesta oppure di offrire una
quantità inferiore, ma non di proporre un
numero maggiore di pezzi.
ERR365 No rows returned Il Produttore non ha restituito righe nella
struttura dati di risposta.
Limitatore
richieste
ERR401 Exceeded buyer
frequency
È stato superato il limite minimo temporale
tra le richieste impostato a livello di singolo
Distributore ovvero, uno stesso Distributore
ha inviato più richieste successive senza
rispettare il tempo minimo d’attesa tra una
richiesta e l’altra. Per conoscere il tempo
Dicembre 2016
Pagina 33
minimo tra le richieste far riferimento al
documento di politiche d’uso relativo al
servizio.
ERR402 Exceeded seller
frequency
È stato superato il limite minimo temporale
tra le richieste impostato per il singolo
Produttore (tabella
ST_SELLER_PROFILES).
Considerando tutti i Distributori con cui il
Produttore ha una relazione, la richiesta che
ha generato questo errore è stata ricevuta
prima del tempo minimo consentito.
Far riferimento al documento di politiche
d’uso relativo al servizio.
ERR403 Too many hourly
requests
Ciascun distributore può inviare un numero
massimo orario di richieste.
È stato superato il limite orario massimo di
richieste ammesso per singolo Distributore.
Far riferimento al documento di politiche
d’uso relativo al servizio.
ERR404 Too many daily
requests
Ciascun distributore può inviare un numero
massimo giornaliero di richieste.
È stato superato il limite giornaliero
massimo di richieste per il singolo
Distributore.
Far riferimento al documento di politiche
d’uso relativo al servizio.
Dicembre 2016
Pagina 34
IMPLEMENTAZIONE ORDINE URGENTE
In caso il produttore eroghi il servizio di evasione dell’ordine urgente tramite Web Service si
delineano quattro scenari di risposta verso il grossista:
1. Ordine rifiutato : transazione chiusa per questa richiesta
(Campi TA4343A = RE TYPE = O)
In questo caso il NO_1004A o il NO_RESERV devono essere vuoti. Il produttore considera
chiusa questa transazione.
2. Ordine rifiutato : restituisce una nuova disponibilità di giacenze
(Campi TA4343A = CA TYPE = O)
Il produttore restituisce una risposta che propone una alternativa al grossista : l’alternativa
viene rappresentata da un codice articolo sostitutivo o da una quantità diversa da quella
richiesta.
In questo caso il NO_1004A o il NO_RESERV devono essere vuoti.
3. Ordine confermato : transazione completa via Web Service
(Campi TA4343A = AP TYPE = O NO_1004A = ‘valorizzato’ )
4. Prenotazione Merce : richiede erogazione Ordine/Conferma EDI tradizionale con
riferimento alla prenotazione
(Campi TA4343A = AP TYPE = O NO_RESERV= ‘valorizzato’ )
Il grossista dovrà erogare l’ordine EDI con le seguenti regole :
TA1001A=224 (Ordine Urgente)
TC4441A=NPM (numero prenotazione merce)
TC4440A=”numero prenotazione merce assegnato dal produttore” (campo NO_RESERV)
Dicembre 2016
Pagina 35
POLICY E REGOLE DEI SINGOLI PRODUTTORI
Ogni produttore ha regole e policy operative diverse.
Il sistema è stato studiato per soddisfare l’erogazione di questo specifico servizio tenendo conto di
scenari ed esigenze di entrambe le parti.
Sarà cura dei singoli produttori comunicare eventuali regole e/o policy ulteriori che potrebbero
richiedere attenzione da parte del distributore nella fase implementativa e/o operativa.
Qui sotto alcuni esempi di differenze operative da parte dei produttori:
Il punto di consegna merce può essere richiesto anche in fase di richiesta di Giacenza
Alcuni produttori gestiscono soli i codici di consegna merce codificati.
Dalla fase di risposta di Giacenza alla fase di richiesta di evasione ordine se il grossista
cambia il codice articolo, il produttore potrebbe evadere l’ordine; si consiglia da parte del
distributore la massima attenzione nella gestione delle modifiche dei codici articolo nella
richiesta di evasione ordine.