Questa API consente di creare e gestire ordini.
Per gestire le API degli ordini tramite autenticazione è necessario utilizzare lo scope: order_api_scope.
Operazioni
L'API espone i seguenti metodi:
Creazione ordini
Creazione ordini
Consente di caricare a sistema una lista di ordini
Risponde a richieste POST verso: /ordini/Order
Per identificare la lista degli ordini da inviare viene richiesto un oggetto JSON contenente i seguenti campi:
- header: intestazione dell'ordine.
- items: lista delle posizioni dell'ordine (ad ogni ordine possono essere associate una o più posizioni).
Intestazione dell'ordine
L’intestazione dell’ordine è un oggetto JSON che contiene i seguenti campi:
- orderNumber(opzionale): numero ordine cliente.
- orderDate(opzionale): data ordine cliente. Opzionale: se non fornita viene considerata la data corrente.
- owner: dettagli responsabile. Contiene:
- type(opzionale): responsabilità dell'ordine. Opzionale: se non fornito nessun valore viene considerato come default "customer".
- code: codice responsabile dell'ordine. Obbligatorio solo se la responsabilità dell’ordine è diversa da “customer”.
- customerCode: codice destinatario della merce.
- reason(opzionale): motivo dell'ordine.
- documentType(opzionale): tipo documento / fornitura. Opzionale: se non fornito nessun valore viene considerato come default "restock".
- expectedDeliveryDate(opzionale): data prevista consegna. Opzionale: se non fornita viene considerata la data ordine + 2 giorni.
- deliveryMode(opzionale): modalità di consegna / condizioni di spedizione. Opzionale: se non fornito nessun valore viene considerato come default "standard".
- recipient(opzionale): destinatario estemporaneo. Contiene:
- name: ragione sociale(obbligatorio),
- memberCard: tessera socio,
- address: via o piazza e n°(obbligatorio),
- co: presso,
- zipCode: CAP(obbligatorio),
- city: località(obbligatorio),
- district: frazione,
- province: provincia(obbligatorio),
- country: paese(obbligatorio),
- telephoneNumber: n° telefono,
- emailAddress: email,
- dataLine: linea dati,
- telebox: fax,
- notes: note
- codeOrdering(opzionale): codice dell'ordine.
- notes(opzionale): note di testata.
- senderOrderReference(opzionale): riferimento ordine mittente.
- promotionCampaignCode: inserire solo se documentType = Campaign.
- channel: Informazioni sul canale di acquisizione (max 4 caratteri) NB: il campo può essere specificato solo se l'utente ha la feature ORDER_CHANNEL
- expectedDeliveryReason: motivo tassatività, specificare solo quando deliveryMode = compulsory. Sono ammessi i seguenti valori: Presentazione, Fiera-Mostra e nuovo Punto Vendita.
- customerDecoder(opzionale): decodificatore cliente, accetta solo il valore GRCLI_FELTRINELLI.
Posizione dell'ordine
La posizione dell’ordine è un oggetto JSON che contiene i seguenti campi:
- eanCode: codice EAN del titolo da ordinare.
- location(opzionale): posizione del titolo
- plant: divisione
- storage: magazzino
- batch: partita
- quantity: quantità totale.
- discount(opzionale): sconto occasionale.
- paymentTerm(opzionale): termini di pagamento.
- booking(opzionale): Tenuta prenotazione. Può assumere i seguenti valori: true, false, replace.
- priority(opzionale): Evasione prioritaria. SVILUPPI FUTURI
- price(opzionale): netto unitario.
- notes(opzionale): nota di posizione.
- newLaunchYear(opzionale): anno lancio
- newLaunchNum(opzionale): numero lancio.
Controlli di validazione
Il metodo API effettua i seguenti controlli di validazione:
- la responsabilità dell'ordine (owner/type) deve avere uno dei seguenti valori: customer (cliente), vendor (editore), promotionalNetwork (rete), salesAgent (agente)
- il codice responsabile dell'ordine deve riferirsi a un responsabile censito a sistema
- il codice SAP o SAN del cliente destinatario (customerCode) deve corrispondere a un cliente presente a sistema
- il motivo dell'ordine (reason) deve avere uno dei seguenti valori: firstOrder, backOrder
- il tipo di documento deve avere uno dei seguenti valori: restock (Rifornimento), newTitle (Novità), campaign (Campagna), deposit (Deposito), freeOrder (Omaggi), specialOrder (Ordini Speciali), specialOrderE (Ordini Speciali E), publisherOffice (Reso ufficio editore), rifoVendorStock (Rifo Magedi Scorta).
- la modalità di consegna (deliveryMode) deve avere uno dei seguenti valori: standard, compulsory (tassativa), quick (veloce), pickup (ritiro diretto)
- se gli EAN esistono devono appartenere all'utente che ha generato l'ordine
- le quantità devono essere maggiori di 0
- controllo eseguito per tutti i tipi di ordine ad esclusione di quelli Novità:
un ordine viene rifiutato con motivo “ordine doppio” se esiste già un ordine con gli stessi valori per data di creazione, codice destinatario merce, tipo responsabilità ordine, tipo documento, data ordine cliente, numero ordine cliente e combinazione codice EAN-quantità.
L'API può restituire i seguenti codici di errore:
- 400 (Bad Request): query malformata.
- 401 (Unauthorized): il token di autenticazione non è valido oppure è scaduto.
Esempio richiesta
Il seguente esempio invia 2 ordini i quali contengono, rispettivamente, 3 e 2 titoli:
POST https://api.messaggerielibri.it/ordini/Order HTTP/1.1
Authorization: Bearer [TOKEN JWT]
Esempio body richiesta
[
{
"header": {
"orderNumber": "TEST-20200521.3",
"orderDate": "2020-05-21",
"customerCode": "0001115301",
"notes": "Ordine di prova - 21/05/2020 #3"
},
"items": [
{
"eanCode": "9788838925993",
"quantity": 30,
"price": 20,
"notes": "ALTRI CASI PER IL COMMISSARIO MONTALBANO"
},
{
"eanCode": "9788838938511",
"quantity": 10,
"price": 15,
"notes": "GLI ARANCINI DI MONTALBANO"
},
{
"eanCode": "9788838924200",
"quantity": 8,
"price": 20,
"notes": "ANCORA TRE INDAGINI PER IL COMMISSARIO MONTALBANO"
}
]
},
{
"header": {
"orderNumber": "TEST-20200521.4",
"orderDate": "2020-05-21",
"customerCode": "0001115301",
"notes": "Ordine di prova - 21/05/2020 #4"
},
"items": [
{
"eanCode": "9788884516121",
"quantity": 12,
"price": 14,
"notes": "HARRY POTTER E IL PRIGIONIERO DI AZKABAN"
},
{
"eanCode": "9788884516114",
"quantity": 10,
"price": 13,
"notes": "HARRY POTTER E LA CAMERA DEI SEGRETI"
}
]
}
]
Esempio risposta
Se l’esecuzione è terminata con successo, l’API restituisce un numero progressivo (batchId) che identifica l’operazione effettuata:
123
Features
Per utilizzare il metodo API è necessario possedere una o più delle seguenti
features:
altrimenti viene restituito 403 (Forbidden)
Recupero sommario ordini
Recupero sommario ordini
Consente il recupero del sommario degli ordini presenti a sistema
Risponde a richieste GET verso /ordini/OrderSummary
E' possibile passare in querystring i seguenti parametri, tutti opzionali:
- dateFrom: data dell'ordine (da)
- dateTo: data dell'ordine (a)
- orderDate: data dell'ordine
Se non vengono passati parametri viene restituito il sommario di tutti gli ordini che sono visibili all'utente.
L’operazione restituisce uno oggetto JSON contenente i seguenti campi:
- items: numero totale di ordini.
- acquired: numero di ordini acquisiti.
- refused: numero di ordini rifiutati.
- toBeSent: numero di ordini
- valid: numero di ordini validi.
- notValid: numero di ordini non validi.
- errors: errori, è una lista di oggetti contenenti i seguenti campi:
- propertyName: nome della proprietà errata.
- description: descrizione della proprietà errata.
- count: numero di ordini contenenti la proprietà errata.
- rejectionReason: motivi di rifiuto, è una lista di oggetti contenenti i seguenti campi:
- code: codice del motivo di rifiuto.
- description: descrizione del motivo di rifiuto.
- count: numero di ordini contenenti il motivo di rifiuto.
L'API può restituire i seguenti codici di errore:
- 400 (Bad Request): query malformata.
- 401 (Unauthorized): il token di autenticazione non è valido oppure è scaduto.
Esempio richiesta
GET https://api.messaggerielibri.it/ordini/orderSummary?&dateFrom=2022-05-27T22:00:00.000Z&dateTo=2022-05-31T22:00:00.000Z
Authorization: Bearer [TOKEN JWT]
Esempio risposta
Se la richiesta va a buon fine si ottiene in output il sommario degli ordini presenti a sistema divisi per tipo di ordine e filtrati per il range di date nel caso fossero passati in input:
{
"items":70226,
"acquired":67352,
"refused":2874,
"toBeSent":2334,
"valid":33341,
"notValid":31677,
"errors":[
{
"propertyName":"EanCode",
"description":"Codice EAN errato",
"count":2849
},
{
"propertyName":"Header.CustomerCode",
"description":"Codice Destinatario errato",
"count":27
},
{
"propertyName":"Header.Recipient.EmailAddress",
"description":"Indirizzo Email di consegna errato",
"count":5
},
{
"propertyName":"Header.Recipient.TelephoneNumber",
"description":"Telefono di consegna errato",
"count":5
}
],
"rejectionReasons":[
{
"code":"PN",
"description":"Prenotazione non ammessa",
"count":13415
},
{
"code":"CP",
"description":"Check Price",
"count":5813
},
{
"code":"M5",
"description":"Non fornibile per Stato Vendita",
"count":712
},
{
"code":"ME",
"description":"Fornitura bloccata da Editore",
"count":89
},
{
"code":"M7",
"description":"Non fornibile per Risposta Editore",
"count":52
},
{
"code":"MC",
"description":"Ammessa solo Resp. Cliente",
"count":25
},
{
"code":"EC",
"description":"Editore Cessato",
"count":9
}
]
}
Features
Per utilizzare il metodo API è necessario possedere una o più delle seguenti
features:
altrimenti viene restituito 403 (Forbidden)
Ricerca ordini
Ricerca ordini
Consente di effettuare una ricerca sugli ordini presenti a sistema
Risponde a richieste GET verso /ordini/Order
E' possibile passare in querystring i seguenti parametri, tutti opzionali:
- number: intestazione dell'ordine - string
- dateFrom: data creazione dell'ordine (da) - date
- dateTo: data creazione dell'ordine (a) - date
- orderDate: data dell'ordine - date formato ISO (yyyy-MM-dd)
- acquired: stato di acquisizione dell'ordine - boolean
- validated: stato di validazione dell'ordine - può assumere i seguenti valori di tipo string:
- toBeSent,
- valid,
- notValid,
- details: flag per indicare se includere anche le righe degli ordini - string
- error: nome della proprietà errata (può essere passato più volte)
- rejectionReason: codice del motivo di rifiuto (può essere passato più volte)
- archived: flag per indicare se filtrare per ordini archiviati - boolean
- orderBy: campo su cui effettuare l’ordinamento - può assumere i seguenti valori di tipo string:
- number,
- date,
- id,
- customer,
- owner,
- document
- orderDirection: direzione dell’ordinamento - può assumere i seguenti valori di tipo string:
- pageSize: numero massimo di risultati restituiti da una chiamata - number, può assumere valori tra 1 e 1000 e come default 50
- pageIndex: numero di pagina dei risultati da restituire - number, può assumere valore maggiore di 0 e come default 1
Se non vengono passati parametri vengono restituite tutti gli ordini che sono visibili all'utente.
Se l’esecuzione è terminata con successo, l’API restituisce il seguente oggetto JSON:
- totalCount: numero totale di ordini trovati.
- totalQuantity: Numero totale copie degli ordini trovati
- refusedQuantity: Numero totale copie rifiutate degli ordini trovati
- notValidQuantity: Numero totale copie non valide degli ordini trovati
- totalItems: Numero totale righe degli ordini trovati
- refusedItems: Numero totale righe rifiutate degli ordini trovati
- notValidItems: Numero totale righe non valide degli ordini trovati
- totalPages: numero totale di pagine previste.
- page: informazioni sulla pagina corrente:
- index: indice della pagine corrente.
- size: dimensione della pagina.
- from: indice del primo elemento della pagina (se la pagina ha elementi)
- to: indice dell’ultimo elemento della pagina (se la pagina ha elementi)
- orders: elenco degli ordini (vedi: dettaglio riga dell'ordine).
Elenco degli ordini: dettaglio riga dell'ordine
L’elenco degli ordini è un array di oggetti JSON aventi la seguente struttura:
- header: intestazione dell'ordine (vedi: dettaglio testata dell'ordine).
- items: lista delle posizioni dell'ordine, ad ogni ordine possono essere associate una o più posizioni (vedi: dettaglio posizioni dell'ordine).
- acquired: flag ordine acquisito.
- validated: stato validazione dell'ordine. I valori possibili sono: toBeSent, valid, notValid.
- rejectionReason: motivo del rifiuto dell'ordine identificato da:
- code: codice,
- description: descrizione.
- summary: recap contatori inerenti all'ordine (vedi: recap contatori).
- errors: lista di eventuali errori nella validazione (vedi: errori di validazione)
Elenco degli ordini: dettaglio testata dell'ordine
La testata dell’ordine è un oggetto JSON che contiene i seguenti campi:
- orderId: identificativo dell'ordine.
- orderNumber: numero ordine cliente.
- orderDate: data ordine cliente.
- owner: dettagli responsabile dell'ordine. Contiene:
- type: tipologia del responsabile dell'ordine. I valori possibili che può assumere sono: customer, vendor, promotionalNetwork, salesAgent.
- code: codice responsabile dell'ordine.
- name: nome del responsabile dell'ordine.
- customer: dettagli destinatario della merce. Contiene:
- code: codice,
- name: nome,
- address: indirizzo,
- zipCode: cap,
- city: città,
- province: provincia,
- country: paese.
- reason: motivo dell'ordine. I valori possibili che può assumere sono: firstOrder, backOrder.
- documentType: tipo documento / fornitura. I valori possibili che può assumere sono: restock, newTitle, campaign, deposit.
- expectedDeliveryDate: data prevista consegna.
- deliveryMode: modalità di consegna / condizioni di spedizione. I valori possibili che può assumere sono: standard, compulsory, quick, pickup.
- recipient: destinatario estemporaneo. Contiene:
- name: ragione sociale,
- memberCard: tessera socio,
- city: località,
- province: provincia,
- country: paese,
- zipCode: CAP,
- address: via o piazza e n°,
- district: frazione,
- co: presso,
- notes: note
- telephoneNumber: n° telefono,
- emailAddress: email,
- dataLine: linea dati,
- telebox,
- notes(opzionale): note di testata.
Elenco degli ordini: dettaglio posizioni dell'ordine
La posizione dell’ordine è un oggetto JSON che contiene i seguenti campi:
- title: informazioni sul titolo. Contiene:
- ean: codice EAN del prodotto,
- title: titolo del prodotto,
- author: autore del prodotto,
- publisher: editore del prodotto,
- vendor: venditore del prodotto identificato da
- code: codice,
- description: descrizione.
- location: posizionamento del titolo. Contiene:
- plant: impianto dove si trova il titolo identificato da
- code: codice,
- description: descrizione
- storage: magazzino dove si trova il titolo identificato da
- code: codice,
- description: descrizione
- batch: partita del titolo.
- quantity: quantità totale del titolo,
- discount: sconto occasionale,
- paymentTerm: termini di pagamento,
- booking: tenuta prenotazione. I valori possibili sono: true, false, replace,
- price: netto unitario,
- notes: nota di posizione,
- acquired: flag ordine acquisito,
- validated: stato validazione dell'ordine. I valori possibili sono: toBeSent, valid, notValid,
- reservedQuantity: quantità impegnata,
- bookedQuantity: quantità in prenotazione,
- bookingDeadlineDate: data scadenza prenotazione,
- notProcessedQuantity: quantità inevasa,
- errors: lista di eventuali errori nella validazione (vedi: errori di validazione)
- rejectionReason: motivo del rifiuto dell'ordine identificato da:
- code: codice,
- description: descrizione.
Elenco degli ordini: recap contatori
Il recap contatori è un oggetto JSON che contiene i seguenti campi:
- items: numero posizioni ordine,
- acquired: numero posizioni ordine acquisite,
- refused: numero posizioni ordine rifiutate,
- toBeSent: numero posizioni ordine in validazione,
- valid: numero posizioni ordine valide,
- notValid: numero posizioni ordine non valide
- quantity: Numero copie ordine
- refusedQuantity: Numero copie ordine rifiutate
- notValidQuantity: Numero copie ordine non valide
Elenco degli ordini: errori di validazione
Gli errori di validazione vengono definiti tramite un oggetto JSON che contiene i seguenti campi:
- propertyName: proprietà in errore,
- propertyValue: valore proprietà in errore,
- propertyDescription: descrizione proprietà in errore,
- errorCode: codice errore,
- errorMessage: messaggio di errore.
L'API può restituire i seguenti codici di errore:
- 400 (Bad Request): query malformata.
- 401 (Unauthorized): il token di autenticazione non è valido oppure è scaduto.
Esempio richiesta
GET https://api.messaggerielibri.it/ordini/order?pageIndex=1&pageSize=50&dateFrom=2022-05-27T22:00:00.000Z&dateTo=2022-05-31T22:00:00.000Z&details
Authorization: Bearer [TOKEN JWT]
Esempio risposta
Se la richiesta va a buon fine si ottiene in output una lista contente le informazioni principali sugli ordini trovati:
{
"totalCount": 1,
"totalQuantity": 16,
"refusedQuantity": 6,
"notValidQuantity": 0,
"totalItems": 3,
"refusedItems": 1,
"notValidItems": 0,
"totalPages": 1,
"page": {
"index": 1,
"size": 50,
"from": 1,
"to": 1
},
"orders": [
{
"header": {
"orderId": 9333,
"orderNumber": "test fa",
"orderDate": "2025-02-19",
"owner": {
"type": "salesAgent",
"code": "FL009",
"name": "PANACCIONE SALVATORE"
},
"customer": {
"code": "00021500",
"name": "HOEPLI SPA",
"address": "VIA HOEPLI, 5",
"zipCode": "20121",
"city": "MILANO",
"province": "MI",
"country": "IT"
},
"documentType": "restock",
"expectedDeliveryDate": "2025-02-21",
"deliveryMode": "standard",
"notes": "agente 01"
},
"items": [
{
"title": {
"ean": "9788807012259",
"title": "GIORNALISTA FELICE E SCONOSCIUTO",
"author": "GARCIA MARQUEZ GABRIEL",
"publisher": "FELTRINELLI EDITORE",
"vendor": {
"code": "243",
"description": "FELTRINELLI EDITORE"
}
},
"location": {
"plant": {
"code": "ME60",
"description": "MESSAGGERIE LIBRI"
},
"storage": {
"code": "11",
"description": "Principale"
},
"batch": "LIBERO"
},
"quantity": 2,
"acquired": true,
"validated": "toBeSent",
"reservedQuantity": 0,
"bookedQuantity": 0,
"notProcessedQuantity": 0,
"priority": false
},
{
"title": {
"ean": "9783833112362",
"title": "ART NOVEAU",
"author": "FAHR-BECKER GABRIELE",
"publisher": "GRIBAUDO - IF IDEE FELTRINELLI EDIT",
"vendor": {
"code": "175",
"description": "GRIBAUDO - IF IDEE FELTRINELLI EDIT"
}
},
"location": {
"plant": {
"code": "ME60",
"description": "MESSAGGERIE LIBRI"
},
"storage": {
"code": "11",
"description": "Principale"
},
"batch": "LIBERO"
},
"quantity": 8,
"acquired": true,
"validated": "toBeSent",
"reservedQuantity": 0,
"bookedQuantity": 0,
"notProcessedQuantity": 0,
"priority": false
},
{
"title": {
"ean": "9788862560337",
"title": "CHE ANIMALE SEI?",
"author": "MASTROCOLA PAOLA",
"publisher": "SALANI EDITORE S.P.A.",
"vendor": {
"code": "778",
"description": "SALANI EDITORE S.P.A."
}
},
"location": {
"plant": {
"code": "ME60",
"description": "MESSAGGERIE LIBRI"
},
"storage": {
"code": "11",
"description": "Principale"
},
"batch": "LIBERO"
},
"quantity": 6,
"acquired": false,
"validated": "toBeSent",
"errors": [
{
"propertyName": "Item.EanResponsability",
"propertyValue": "9788862560337",
"propertyDescription": "EAN non coerente con responsabilità ordine",
"errorCode": "Item.EanResponsability",
"errorMessage": "La condizione non è verificata per 'Ean Code'."
}
],
"reservedQuantity": 0,
"bookedQuantity": 0,
"notProcessedQuantity": 0,
"priority": false
}
],
"acquired": true,
"validated": "toBeSent",
"summary": {
"items": 3,
"acquired": 2,
"refused": 1,
"toBeSent": 2,
"valid": 0,
"notValid": 0,
"quantity": 16,
"refusedQuantity": 6,
"notValidQuantity": 0
},
"canResubmit": false,
"archived": false
}
]
}
Features
Per utilizzare il metodo API è necessario possedere una o più delle seguenti
features:
altrimenti viene restituito 403 (Forbidden)
Recupero set ordini
Recupero set ordini
Consente di ottenere l'elenco degli ordini presenti in un set
Risponde a richieste GET verso /ordini/OrderBatch/{batchId}, dove {batchId} rappresenta il batchId degli ordini di un determinato set che si vogliono recuperare.
Se l’esecuzione è terminata con successo, l’API restituisce uno o più oggetti JSON:
- header: intestazione dell'ordine (vedi: dettaglio testata dell'ordine).
- items: lista delle posizioni dell'ordine, ad ogni ordine possono essere associate una o più posizioni (vedi: dettaglio posizioni dell'ordine).
- acquired: flag ordine acquisito
- validated: stato validazione dell'ordine. I valori possibili sono: toBeSent, valid, notValid.
- rejectionReason: motivo del rifiuto dell'ordine identificato da:
- code: codice
- description: descrizione
- summary: recap contatori inerenti all'ordine (vedi: recap contatori).
- errors: lista di eventuali errori nella validazione (vedi: errori di validazione)
Elenco degli ordini: dettaglio testata dell'ordine
La testata dell’ordine è un oggetto JSON che contiene i seguenti campi:
- orderId: identificativo dell'ordine
- orderNumber: numero ordine cliente
- orderDate: data ordine cliente
- owner: dettagli responsabile dell'ordine. Contiene:
- type: tipologia del responsabile dell'ordine. I valori possibili che può assumere sono: customer, vendor, promotionalNetwork, salesAgent.
- code: codice responsabile dell'ordine
- name: nome del responsabile dell'ordine
- customer: dettagli destinatario della merce. Contiene:
- code: codice
- name: nome
- address: indirizzo
- zipCode: cap
- city: città
- province: provincia
- country: paese
- reason: motivo dell'ordine. I valori possibili che può assumere sono: firstOrder, backOrder.
- documentType: tipo documento / fornitura. I valori possibili che può assumere sono: restock, newTitle, campaign, deposit.
- expectedDeliveryDate: data prevista consegna
- deliveryMode: modalità di consegna / condizioni di spedizione. I valori possibili che può assumere sono: standard, compulsory, quick, pickup.
- recipient: destinatario estemporaneo. Contiene:
- name: ragione sociale
- memberCard: tessera socio
- city: località
- province: provincia
- country: paese
- zipCode: CAP
- address: via o piazza e n°
- district: frazione
- co: presso
- notes: note
- telephoneNumber: n° telefono
- emailAddress: email
- dataLine: linea dati
- telebox
- notes(opzionale): note di testata
Elenco degli ordini: dettaglio posizioni dell'ordine
La posizione dell’ordine è un oggetto JSON che contiene i seguenti campi:
- title: informazioni sul titolo. Contiene:
- ean: codice EAN del prodotto
- title: titolo del prodotto
- author: autore del prodotto
- publisher: editore del prodotto
- vendor: venditore del prodotto identificato da
- code: codice
- description: descrizione
- location: posizionamento del titolo. Contiene:
- plant: impianto dove si trova il titolo identificato da
- code: codice
- description: descrizione
- storage: magazzino dove si trova il titolo identificato da
- code: codice
- description: descrizione
- batch: partita del titolo
- quantity: quantità totale del titolo
- discount: sconto occasionale
- paymentTerm: termini di pagamento
- booking: tenuta prenotazione. I valori possibili sono: true, false, replace,
- price: netto unitario
- notes: nota di posizione
- acquired: flag ordine acquisito
- validated: stato validazione dell'ordine. I valori possibili sono: toBeSent, valid, notValid,
- errors: lista di eventuali errori nella validazione. Contiene:
- propertyName: proprietà in errore
- propertyValue: valore proprietà in errore
- propertyDescription: descrizione proprietà in errore
- errorCode: codice errore
- errorMessage: messaggio di errore
- rejectionReason: motivo del rifiuto dell'ordine identificato da:
- code: codice
- description: descrizione
Elenco degli ordini: recap contatori
Il recap contatori è un oggetto JSON che contiene i seguenti campi:
- items: numero posizioni ordine
- acquired: numero posizioni ordine acquisite
- refused: numero posizioni ordine rifiutate
- toBeSent: numero posizioni ordine in validazione
- valid: numero posizioni ordine valide
- notValid: numero posizioni ordine non valide
Elenco degli ordini: errori di validazione
Gli errori di validazione vengono definiti tramite un oggetto JSON che contiene i seguenti campi:
- propertyName: proprietà in errore
- propertyValue: valore proprietà in errore
- propertyDescription: descrizione proprietà in errore
- errorCode: codice errore
- errorMessage: messaggio di errore
L'API può restituire i seguenti codici di errore:
- 400 (Bad Request): query malformata.
- 401 (Unauthorized): il token di autenticazione non è valido oppure è scaduto.
- 404 (Not Found): al parametro fornito non corrisponde alcun set.
Esempio richiesta
GET https://api.messaggerielibri.it/ordini/OrderBatch/193
Authorization: Bearer [TOKEN JWT]
Esempio risposta
[
{
"header": {
"orderId": 253,
"orderNumber": "TEST-20220624.1",
"orderDate": "2022-01-27",
"owner": {
"type": "customer",
"code": "01115301",
"name": "RINASCITA DI PIGNOTTI GIORGIO"
},
"customer": {
"code": "01115301",
"name": "RINASCITA DI PIGNOTTI GIORGIO",
"address": "PIAZZA ROMA 7",
"zipCode": "63100",
"city": "ASCOLI PICENO",
"province": "AP",
"country": "IT"
},
"documentType": "newTitle",
"expectedDeliveryDate": "2022-01-29",
"deliveryMode": "standard",
"notes": "Ordine di prova - 27/01/2022 #1"
},
"items": [
{
"title": {
"ean": "9788838925993",
"title": "ALTRI CASI PER IL COMMISSARIO MONTALBANO",
"author": "CAMILLERI",
"publisher": "SELLERIO EDITORE SRL",
"vendor": {
"code": "017",
"description": "SELLERIO EDITORE SRL"
}
},
"location": {
"plant": {
"code": "ME60",
"description": "MESSAGGERIE LIBRI"
},
"storage": {
"code": "11",
"description": "Principale"
},
"batch": "LIBERO"
},
"quantity": 30,
"booking": "true",
"price": 20.00,
"notes": "ALTRI CASI PER IL COMMISSARIO MONTALBANO",
"acquired": true,
"validated": "toBeSent"
},
{
"title": {
"ean": "9788838938511",
"title": "GLI ARANCINI DI MONTALBANO",
"author": "CAMILLERI",
"publisher": "SELLERIO EDITORE SRL",
"vendor": {
"code": "017",
"description": "SELLERIO EDITORE SRL"
}
},
"location": {
"plant": {
"code": "ME60",
"description": "MESSAGGERIE LIBRI"
},
"storage": {
"code": "11",
"description": "Principale"
},
"batch": "LIBERO"
},
"quantity": 10,
"booking": "false",
"price": 15.00,
"notes": "GLI ARANCINI DI MONTALBANO",
"acquired": true,
"validated": "toBeSent"
},
{
"title": {
"ean": "19788838924200",
"vendor": {}
},
"location": {
"plant": {
"code": "ME60",
"description": "MESSAGGERIE LIBRI"
},
"storage": {
"code": "30",
"description": "Rese da versare"
},
"batch": "LIBERO"
},
"quantity": 8,
"booking": "replace",
"price": 20.00,
"notes": "ANCORA TRE INDAGINI PER IL COMMISSARIO MONTALBANO",
"acquired": false,
"validated": "toBeSent",
"errors": [
{
"propertyName": "EanCode",
"propertyValue": "19788838924200",
"propertyDescription": "Codice EAN errato",
"errorCode": "ExistingValidator",
"errorMessage": "'Ean Code' value '19788838924200' not found."
}
]
}
],
"acquired": false,
"validated": "toBeSent",
"summary": {
"items": 3,
"acquired": 0,
"refused": 3,
"toBeSent": 0,
"valid": 0,
"notValid": 0
},
"errors": [
{
"propertyName": "Header.CustomerCode",
"propertyValue": "0001115301",
"propertyDescription": "Destinatario errato",
"errorCode": "ExistingValidator",
"errorMessage": "'Customer Code' value '0001115301' not found."
}
],
"canResubmit": false
},
{
"header": {
"orderId": 254,
"orderNumber": "TEST-20220624.2",
"orderDate": "2022-01-27",
"owner": {
"type": "customer",
"code": "01115301",
"name": "RINASCITA DI PIGNOTTI GIORGIO"
},
"customer": {
"code": "01115301",
"name": "RINASCITA DI PIGNOTTI GIORGIO",
"address": "PIAZZA ROMA 7",
"zipCode": "63100",
"city": "ASCOLI PICENO",
"province": "AP",
"country": "IT"
},
"documentType": "restock",
"expectedDeliveryDate": "2022-01-29",
"deliveryMode": "standard",
"notes": "Ordine di prova - 27/01/2022 #2"
},
"items": [
{
"title": {
"ean": "9788884516121",
"title": "HARRY POTTER E IL PRIGIONIERO DI AZKABAN",
"author": "ROWLING J.K.",
"publisher": "SALANI EDITORE S.P.A.",
"vendor": {
"code": "778",
"description": "SALANI EDITORE S.P.A."
}
},
"location": {
"plant": {
"code": "ME61",
"description": "MESSAGGERIE LIBRI"
},
"storage": {
"code": "20",
"description": "Rese"
},
"batch": "LIBERO"
},
"quantity": 12,
"price": 14.00,
"notes": "HARRY POTTER E IL PRIGIONIERO DI AZKABAN",
"acquired": true,
"validated": "toBeSent"
},
{
"title": {
"ean": "9788884516114",
"title": "HARRY POTTER E LA CAMERA DEI SEGRETI",
"author": "ROWLING J.K.",
"publisher": "SALANI EDITORE S.P.A.",
"vendor": {
"code": "778",
"description": "SALANI EDITORE S.P.A."
}
},
"location": {
"plant": {
"code": "ME60",
"description": "MESSAGGERIE LIBRI"
},
"storage": {
"code": "11",
"description": "Principale"
},
"batch": "LIBERO"
},
"quantity": 10,
"price": 13.00,
"notes": "HARRY POTTER E LA CAMERA DEI SEGRETI",
"acquired": true,
"validated": "toBeSent"
}
],
"acquired": false,
"validated": "toBeSent",
"summary": {
"items": 2,
"acquired": 0,
"refused": 2,
"toBeSent": 0,
"valid": 0,
"notValid": 0
},
"errors": [
{
"propertyName": "Header.CustomerCode",
"propertyValue": "0001115301",
"propertyDescription": "Destinatario errato",
"errorCode": "ExistingValidator",
"errorMessage": "'Customer Code' value '0001115301' not found."
}
],
"canResubmit": false
}
]
Features
Per utilizzare il metodo API è necessario possedere una o più delle seguenti
features:
altrimenti viene restituito 403 (Forbidden)
Ricerca riferimento ordini
Ricerca riferimento ordini
Consente di effettuare una ricerca sugli ordini presenti a sistema
Risponde a richieste GET verso /ordini/OrderNumber
E' possibile passare in querystring i seguenti parametri, tutti opzionali:
- number: intestazione dell'ordine - string
- dateFrom: data creazione dell'ordine (da) - date
- dateTo: data creazione dell'ordine (a) - date
- details: flag per indicare se includere anche i dettagli degli ordini - string
- orderBy: campo su cui effettuare l’ordinamento - può assumere i seguenti valori di tipo string:
- orderDirection: direzione dell’ordinamento - può assumere i seguenti valori di tipo string:
- pageSize: numero massimo di risultati restituiti da una chiamata - number, può assumere valori tra 1 e 1000 e come default 50
- pageIndex: numero di pagina dei risultati da restituire - number, può assumere valore maggiore di 0 e come default 1
Se non vengono passati parametri vengono restituite tutti gli ordini che sono visibili all'utente.
Se l’esecuzione è terminata con successo, l’API restituisce il seguente oggetto JSON:
- totalCount: numero totale di riferimento ordini trovati.
- totalPages: numero totale di pagine previste.
- page: informazioni sulla pagina corrente:
- index: indice della pagine corrente.
- size: dimensione della pagina.
- from: indice del primo elemento della pagina (se la pagina ha elementi)
- to: indice dell’ultimo elemento della pagina (se la pagina ha elementi)
- orders: elenco degli ordini (vedi: dettaglio riga dell'ordine).
Elenco degli ordini: dettaglio riga dell'ordine
L’elenco degli ordini è un array di oggetti JSON aventi la seguente struttura:
- header: intestazione del riferimento ordine (vedi: dettaglio testata del riferimento ordine).
- items: lista delle posizioni dell'ordine, ad ogni ordine possono essere associate una o più posizioni (vedi: dettaglio dell'ordine).
Elenco degli ordini: dettaglio testata dell'ordine
La testata dell’ordine è un oggetto JSON che contiene i seguenti campi:
- orderNumber: numero ordine cliente.
- orderDate: data ordine cliente.
- orderCount: conteggio degli ordini
- quantity: Totale quantità copie
- items: Numero di righe
- notValidatedCount: Numero di righe non valide
- validatedCount: Numero di righe in validazione
- orders: elenco dettaglio degli ordini
Elenco degli ordini: dettaglio posizioni dell'ordine
Il dettaglio dell’ordine è un oggetto JSON che contiene i seguenti campi:
- orderId: sconto occasionale,
- items: termini di pagamento,
- notValid: tenuta prenotazione. I valori possibili sono: true, false, quantity,
- createdDate
L'API può restituire i seguenti codici di errore:
- 400 (Bad Request): query malformata.
- 401 (Unauthorized): il token di autenticazione non è valido oppure è scaduto.
Esempio richiesta
GET https://api.messaggerielibri.it/ordini/OrderNumber?dateFrom=2025-03-25&dateTo=2025-03-26&details
Authorization: Bearer [TOKEN JWT]
Esempio risposta
Se la richiesta va a buon fine si ottiene in output una lista contente le informazioni principali sugli ordini trovati:
{
"totalCount": 4,
"totalPages": 1,
"page": {
"index": 1,
"size": 20,
"from": 1,
"to": 4
},
"orderNumbers": [
{
"header": {
"orderNumber": "newApi",
"orderDate": "2025-03-25",
"ordersCount": 2,
"quantity": 4,
"items": 2,
"notValidatedCount": 0,
"validatedCount": 2,
"orders": [
{
"orderId": 27669,
"items": 1,
"notValid": 0,
"quantity": 0,
"createdDate": "2025-03-25T08:57:28.1922277"
},
{
"orderId": 27670,
"items": 1,
"notValid": 0,
"quantity": 0,
"createdDate": "2025-03-25T09:04:23.596302"
}
]
}
},
{
"header": {
"orderNumber": "newApi1",
"orderDate": "2025-03-25",
"ordersCount": 1,
"quantity": 1,
"items": 1,
"notValidatedCount": 0,
"validatedCount": 1,
"orders": [
{
"orderId": 27671,
"items": 1,
"notValid": 0,
"quantity": 0,
"createdDate": "2025-03-25T11:46:05.9636654"
}
]
}
},
{
"header": {
"orderNumber": "newApi2",
"orderDate": "2025-03-25",
"ordersCount": 2,
"quantity": 6,
"items": 4,
"notValidatedCount": 2,
"validatedCount": 2,
"orders": [
{
"orderId": 27672,
"items": 2,
"notValid": 0,
"quantity": 0,
"createdDate": "2025-03-25T13:39:28.2072582"
},
{
"orderId": 27673,
"items": 2,
"notValid": 2,
"quantity": 0,
"createdDate": "2025-03-25T14:00:39.9187829"
}
]
}
},
{
"header": {
"orderNumber": "newApi",
"orderDate": "2025-03-26",
"ordersCount": 3,
"quantity": 27,
"items": 6,
"notValidatedCount": 1,
"validatedCount": 5,
"orders": [
{
"orderId": 27674,
"items": 1,
"notValid": 1,
"quantity": 0,
"createdDate": "2025-03-26T11:37:10.9121263"
},
{
"orderId": 27675,
"items": 3,
"notValid": 0,
"quantity": 0,
"createdDate": "2025-03-26T15:48:06.7336153"
},
{
"orderId": 27676,
"items": 2,
"notValid": 0,
"quantity": 0,
"createdDate": "2025-03-26T15:48:47.3271307"
}
]
}
}
]
}
Features
Per utilizzare il metodo API è necessario possedere una o più delle seguenti
features:
altrimenti viene restituito 403 (Forbidden)
Recupero dettaglio singolo ordine
Recupero dettaglio singolo ordine
Consente di effettuare una ricerca sugli ordini presenti a sistema
Risponde a richieste GET verso /ordini/order/{orderId}, dove {orderId} rappresenta l'Id dell'ordine che si vuole recuperare.
L’operazione restituisce un oggetto JSON contenente i seguenti campi:
- header: intestazione dell'ordine (vedi: dettaglio testata dell'ordine).
- items: lista delle posizioni dell'ordine, ad ogni ordine possono essere associate una o più posizioni (vedi: dettaglio posizioni dell'ordine).
- acquired: flag ordine acquisito.
- validated: stato validazione dell'ordine. I valori possibili sono: toBeSent, valid, notValid.
- rejectionReason: motivo del rifiuto dell'ordine identificato da:
- code: codice,
- description: descrizione.
- summary: recap contatori inerenti all'ordine (vedi: recap contatori).
- errors: lista di eventuali errori nella validazione (vedi: errori di validazione)
Elenco degli ordini: dettaglio testata dell'ordine
La testata dell’ordine è un oggetto JSON che contiene i seguenti campi:
- orderId: identificativo dell'ordine.
- orderNumber: numero ordine cliente.
- orderDate: data ordine cliente.
- owner: dettagli responsabile dell'ordine. Contiene:
- type: tipologia del responsabile dell'ordine. I valori possibili che può assumere sono: customer, vendor, promotionalNetwork, salesAgent.
- code: codice responsabile dell'ordine.
- name: nome del responsabile dell'ordine.
- customer: dettagli destinatario della merce. Contiene:
- code: codice,
- name: nome,
- address: indirizzo,
- zipCode: cap,
- city: città,
- province: provincia,
- country: paese.
- reason: motivo dell'ordine. I valori possibili che può assumere sono: firstOrder, backOrder.
- documentType: tipo documento / fornitura. I valori possibili che può assumere sono: restock, newTitle, campaign, deposit.
- expectedDeliveryDate: data prevista consegna.
- deliveryMode: modalità di consegna / condizioni di spedizione. I valori possibili che può assumere sono: standard, compulsory, quick, pickup.
- recipient: destinatario estemporaneo. Contiene:
- name: ragione sociale,
- memberCard: tessera socio,
- city: località,
- province: provincia,
- country: paese,
- zipCode: CAP,
- address: via o piazza e n°,
- district: frazione,
- co: presso,
- notes: note
- telephoneNumber: n° telefono,
- emailAddress: email,
- dataLine: linea dati,
- telebox,
- notes(opzionale): note di testata.
Elenco degli ordini: dettaglio posizioni dell'ordine
La posizione dell’ordine è un oggetto JSON che contiene i seguenti campi:
- title: informazioni sul titolo. Contiene:
- ean: codice EAN del prodotto,
- title: titolo del prodotto,
- author: autore del prodotto,
- publisher: editore del prodotto,
- vendor: venditore del prodotto identificato da
- code: codice,
- description: descrizione.
- location: posizionamento del titolo. Contiene:
- plant: impianto dove si trova il titolo identificato da
- code: codice,
- description: descrizione
- storage: magazzino dove si trova il titolo identificato da
- code: codice,
- description: descrizione
- batch: partita del titolo.
- quantity: quantità totale del titolo,
- discount: sconto occasionale,
- paymentTerm: termini di pagamento,
- booking: tenuta prenotazione. I valori possibili sono: true, false, replace,
- price: netto unitario,
- notes: nota di posizione,
- acquired: flag ordine acquisito,
- validated: stato validazione dell'ordine. I valori possibili sono: toBeSent, valid, notValid,
- reservedQuantity: quantità impegnata,
- bookedQuantity: quantità in prenotazione,
- bookingDeadlineDate: data scadenza prenotazione,
- notProcessedQuantity: quantità inevasa,
- errors: lista di eventuali errori nella validazione (vedi: errori di validazione)
- rejectionReason: motivo del rifiuto dell'ordine identificato da:
- code: codice,
- description: descrizione.
Elenco degli ordini: recap contatori
Il recap contatori è un oggetto JSON che contiene i seguenti campi:
- items: numero posizioni ordine,
- acquired: numero posizioni ordine acquisite,
- refused: numero posizioni ordine rifiutate,
- toBeSent: numero posizioni ordine in validazione,
- valid: numero posizioni ordine valide,
- notValid: numero posizioni ordine non valide
- quantity: numero copie ordine
- refusedQuantity: numero copie ordine rifiutate
- notValidQuantity: numero copie ordine non valide
Elenco degli ordini: errori di validazione
Gli errori di validazione vengono definiti tramite un oggetto JSON che contiene i seguenti campi:
- propertyName: proprietà in errore,
- propertyValue: valore proprietà in errore,
- propertyDescription: descrizione proprietà in errore,
- errorCode: codice errore,
- errorMessage: messaggio di errore.
L'API può restituire i seguenti codici di errore:
- 400 (Bad Request): query malformata.
- 401 (Unauthorized): il token di autenticazione non è valido oppure è scaduto.
- 404 (Not Found): ai parametri forniti non corrisponde alcun ordine.
Esempio richiesta
GET https://api.messaggerielibri.it/ordini/order/3126
Authorization: Bearer [TOKEN JWT]
Esempio risposta
Se la richiesta va a buon fine si ottiene in output una lista contente le informazioni principali sugli ordini trovati:
{
"header": {
"orderId": 3126,
"orderNumber": "3126",
"orderDate": "2025-01-07",
"owner": {
"type": "promotionalNetwork",
"code": "FL",
"name": "FELTRINELLI"
},
"customer": {
"code": "00173800",
"name": "FAGNANI IDEALE DI P.FAGNANI",
"address": "C.SO STAMIRA 31",
"zipCode": "60122",
"city": "ANCONA",
"province": "AN",
"country": "IT"
},
"documentType": "newTitle",
"expectedDeliveryDate": "2025-01-09",
"deliveryMode": "standard"
},
"items": [
{
"title": {
"ean": "9788874967858",
"title": "MAI PIU PAURA DELLA FISICA",
"author": "FILOCAMO GIOVANNI",
"publisher": "KOWALSKI - IF IDEA ED. FELTRIN",
"vendor": {
"code": "285",
"description": "KOWALSKI - IF IDEA ED. FELTRIN"
}
},
"location": {
"plant": {
"code": "ME60",
"description": "MESSAGGERIE LIBRI"
},
"storage": {
"code": "11",
"description": "Principale"
},
"batch": "LIBERO"
},
"quantity": 1,
"acquired": true,
"validated": "toBeSent",
"reservedQuantity": 0,
"bookedQuantity": 0,
"notProcessedQuantity": 0,
"priority": false
},
{
"title": {
"ean": "9788874967858",
"title": "MAI PIU PAURA DELLA FISICA",
"author": "FILOCAMO GIOVANNI",
"publisher": "KOWALSKI - IF IDEA ED. FELTRIN",
"vendor": {
"code": "285",
"description": "KOWALSKI - IF IDEA ED. FELTRIN"
}
},
"location": {
"plant": {
"code": "ME60",
"description": "MESSAGGERIE LIBRI"
},
"storage": {
"code": "11",
"description": "Principale"
},
"batch": "LIBERO"
},
"quantity": 1,
"acquired": true,
"validated": "toBeSent",
"reservedQuantity": 0,
"bookedQuantity": 0,
"notProcessedQuantity": 0,
"priority": false
},
{
"title": {
"ean": "9788874967858",
"title": "MAI PIU PAURA DELLA FISICA",
"author": "FILOCAMO GIOVANNI",
"publisher": "KOWALSKI - IF IDEA ED. FELTRIN",
"vendor": {
"code": "285",
"description": "KOWALSKI - IF IDEA ED. FELTRIN"
}
},
"location": {
"plant": {
"code": "ME60",
"description": "MESSAGGERIE LIBRI"
},
"storage": {
"code": "11",
"description": "Principale"
},
"batch": "LIBERO"
},
"quantity": 1,
"acquired": true,
"validated": "toBeSent",
"reservedQuantity": 0,
"bookedQuantity": 0,
"notProcessedQuantity": 0,
"priority": false
},
{
"title": {
"ean": "9788874967858",
"title": "MAI PIU PAURA DELLA FISICA",
"author": "FILOCAMO GIOVANNI",
"publisher": "KOWALSKI - IF IDEA ED. FELTRIN",
"vendor": {
"code": "285",
"description": "KOWALSKI - IF IDEA ED. FELTRIN"
}
},
"location": {
"plant": {
"code": "ME60",
"description": "MESSAGGERIE LIBRI"
},
"storage": {
"code": "11",
"description": "Principale"
},
"batch": "LIBERO"
},
"quantity": 1,
"acquired": true,
"validated": "toBeSent",
"reservedQuantity": 0,
"bookedQuantity": 0,
"notProcessedQuantity": 0,
"priority": false
},
{
"title": {
"ean": "9788874967858",
"title": "MAI PIU PAURA DELLA FISICA",
"author": "FILOCAMO GIOVANNI",
"publisher": "KOWALSKI - IF IDEA ED. FELTRIN",
"vendor": {
"code": "285",
"description": "KOWALSKI - IF IDEA ED. FELTRIN"
}
},
"location": {
"plant": {
"code": "ME60",
"description": "MESSAGGERIE LIBRI"
},
"storage": {
"code": "11",
"description": "Principale"
},
"batch": "LIBERO"
},
"quantity": 1,
"acquired": true,
"validated": "toBeSent",
"reservedQuantity": 0,
"bookedQuantity": 0,
"notProcessedQuantity": 0,
"priority": false
},
{
"title": {
"ean": "9788874967858",
"title": "MAI PIU PAURA DELLA FISICA",
"author": "FILOCAMO GIOVANNI",
"publisher": "KOWALSKI - IF IDEA ED. FELTRIN",
"vendor": {
"code": "285",
"description": "KOWALSKI - IF IDEA ED. FELTRIN"
}
},
"location": {
"plant": {
"code": "ME60",
"description": "MESSAGGERIE LIBRI"
},
"storage": {
"code": "11",
"description": "Principale"
},
"batch": "LIBERO"
},
"quantity": 1,
"acquired": true,
"validated": "toBeSent",
"reservedQuantity": 0,
"bookedQuantity": 0,
"notProcessedQuantity": 0,
"priority": false
},
{
"title": {
"ean": "9788874967858",
"title": "MAI PIU PAURA DELLA FISICA",
"author": "FILOCAMO GIOVANNI",
"publisher": "KOWALSKI - IF IDEA ED. FELTRIN",
"vendor": {
"code": "285",
"description": "KOWALSKI - IF IDEA ED. FELTRIN"
}
},
"location": {
"plant": {
"code": "ME60",
"description": "MESSAGGERIE LIBRI"
},
"storage": {
"code": "11",
"description": "Principale"
},
"batch": "LIBERO"
},
"quantity": 1,
"acquired": true,
"validated": "toBeSent",
"reservedQuantity": 0,
"bookedQuantity": 0,
"notProcessedQuantity": 0,
"priority": false
},
{
"title": {
"ean": "9788874967858",
"title": "MAI PIU PAURA DELLA FISICA",
"author": "FILOCAMO GIOVANNI",
"publisher": "KOWALSKI - IF IDEA ED. FELTRIN",
"vendor": {
"code": "285",
"description": "KOWALSKI - IF IDEA ED. FELTRIN"
}
},
"location": {
"plant": {
"code": "ME60",
"description": "MESSAGGERIE LIBRI"
},
"storage": {
"code": "11",
"description": "Principale"
},
"batch": "LIBERO"
},
"quantity": 1,
"acquired": true,
"validated": "toBeSent",
"reservedQuantity": 0,
"bookedQuantity": 0,
"notProcessedQuantity": 0,
"priority": false
},
{
"title": {
"ean": "9788874967858",
"title": "MAI PIU PAURA DELLA FISICA",
"author": "FILOCAMO GIOVANNI",
"publisher": "KOWALSKI - IF IDEA ED. FELTRIN",
"vendor": {
"code": "285",
"description": "KOWALSKI - IF IDEA ED. FELTRIN"
}
},
"location": {
"plant": {
"code": "ME60",
"description": "MESSAGGERIE LIBRI"
},
"storage": {
"code": "11",
"description": "Principale"
},
"batch": "LIBERO"
},
"quantity": 3,
"discount": 20.00,
"paymentTerm": "83",
"notes": "prova",
"acquired": true,
"validated": "toBeSent",
"reservedQuantity": 0,
"bookedQuantity": 0,
"notProcessedQuantity": 0,
"priority": false
},
{
"title": {
"ean": "9788874967858",
"title": "MAI PIU PAURA DELLA FISICA",
"author": "FILOCAMO GIOVANNI",
"publisher": "KOWALSKI - IF IDEA ED. FELTRIN",
"vendor": {
"code": "285",
"description": "KOWALSKI - IF IDEA ED. FELTRIN"
}
},
"location": {
"plant": {
"code": "ME60",
"description": "MESSAGGERIE LIBRI"
},
"storage": {
"code": "11",
"description": "Principale"
},
"batch": "LIBERO"
},
"quantity": 3,
"discount": 20.00,
"paymentTerm": "83",
"notes": "prova",
"acquired": true,
"validated": "toBeSent",
"reservedQuantity": 0,
"bookedQuantity": 0,
"notProcessedQuantity": 0,
"priority": false
},
{
"title": {
"ean": "9788874967858",
"title": "MAI PIU PAURA DELLA FISICA",
"author": "FILOCAMO GIOVANNI",
"publisher": "KOWALSKI - IF IDEA ED. FELTRIN",
"vendor": {
"code": "285",
"description": "KOWALSKI - IF IDEA ED. FELTRIN"
}
},
"location": {
"plant": {
"code": "ME60",
"description": "MESSAGGERIE LIBRI"
},
"storage": {
"code": "11",
"description": "Principale"
},
"batch": "LIBERO"
},
"quantity": 3,
"discount": 20.00,
"paymentTerm": "83",
"notes": "prova",
"acquired": true,
"validated": "toBeSent",
"reservedQuantity": 0,
"bookedQuantity": 0,
"notProcessedQuantity": 0,
"priority": false
},
{
"title": {
"ean": "9788874967858",
"title": "MAI PIU PAURA DELLA FISICA",
"author": "FILOCAMO GIOVANNI",
"publisher": "KOWALSKI - IF IDEA ED. FELTRIN",
"vendor": {
"code": "285",
"description": "KOWALSKI - IF IDEA ED. FELTRIN"
}
},
"location": {
"plant": {
"code": "ME60",
"description": "MESSAGGERIE LIBRI"
},
"storage": {
"code": "11",
"description": "Principale"
},
"batch": "LIBERO"
},
"quantity": 1,
"acquired": true,
"validated": "toBeSent",
"reservedQuantity": 0,
"bookedQuantity": 0,
"notProcessedQuantity": 0,
"priority": false
},
{
"title": {
"ean": "9788874967858",
"title": "MAI PIU PAURA DELLA FISICA",
"author": "FILOCAMO GIOVANNI",
"publisher": "KOWALSKI - IF IDEA ED. FELTRIN",
"vendor": {
"code": "285",
"description": "KOWALSKI - IF IDEA ED. FELTRIN"
}
},
"location": {
"plant": {
"code": "ME60",
"description": "MESSAGGERIE LIBRI"
},
"storage": {
"code": "11",
"description": "Principale"
},
"batch": "LIBERO"
},
"quantity": 1,
"acquired": true,
"validated": "toBeSent",
"reservedQuantity": 0,
"bookedQuantity": 0,
"notProcessedQuantity": 0,
"priority": false
}
],
"acquired": false,
"validated": "toBeSent",
"summary": {
"items": 13,
"acquired": 0,
"refused": 13,
"toBeSent": 0,
"valid": 0,
"notValid": 0,
"quantity": 19,
"refusedQuantity": 19,
"notValidQuantity": 0
},
"errors": [
{
"propertyName": "Header.CustomerStatusCode",
"propertyValue": "0000173800",
"propertyDescription": "Destinatario sospeso",
"errorCode": "Header.CustomerStatusCode",
"errorMessage": "'Customer Code' value '0000173800' not found."
}
],
"canResubmit": true,
"archived": false
}
Features
Per utilizzare il metodo API è necessario possedere una o più delle seguenti
features:
altrimenti viene restituito 403 (Forbidden)
Richiesta modifica riga d'ordine
Richiesta modifica riga d'ordine
Consente di inviare una richiesta di modifica su una riga d'ordine
Risponde a richieste POST verso: /ordini/Order/{orderId}/ean/{eanCode}/update, dove {orderId} rappresenta l'Id dell'ordine che si vuole modificare e {eanCode} la riga.
Vanno passati tramite un oggetto JSON i seguenti campi:
- NewBookedQuantiity: quantità in prenotazione
- NewTermsOfPaymentCode: pagamento occasionale
- NewItemNote: note
- NewOccasionalDiscountPercentage: sconto occasionale
Controlli di validazione
Il metodo API effettua i seguenti controlli di validazione:
- OrderID esista e appartiene all'utenza che richiama il metodo di modifica
- Per EAN modificato non deve esserci due righe d'ordine con lo stesso EAN
- La riga d'ordine deve essere stata acquisita correttamente
- Per l'OrderID & EAN modificato non deve esserci nessuna modifica in stato PENDING
- Deve esserci almeno uno dei 4 campi NEW valorizzato
- Deve esserci almeno uno dei 4 campi NEW differente da quanto già presente a DB
- Se NewBookedQuantity è diverso da NULL deve essere : >=0
- Se viene valorizzato NewOccasionalDiscountPercentage deve essere >= 0 & < 100
L'API può restituire i seguenti codici di errore:
- 400 (Bad Request): query malformata.
- 401 (Unauthorized): il token di autenticazione non è valido oppure è scaduto.
Esempio richiesta
Il seguente esempio invia 2 ordini i quali contengono, rispettivamente, 3 e 2 titoli:
POST https://api.messaggerielibri.it/ordini/Order/27917/ean/9788832700415/update HTTP/1.1
Authorization: Bearer [TOKEN JWT]
Esempio body richiesta
{
"NewBookedQuantity": 5,
"NewTermsOfPaymentCode": 21,
"NewItemNote": "note nuove",
"NewOccasionalDiscountPercentage": 35
}
Esempio risposta
Se l’esecuzione è terminata con successo, l’API restituisce un numero progressivo che identifica l’operazione effettuata:
123
Features
Per utilizzare il metodo API è necessario possedere una o più delle seguenti
features:
altrimenti viene restituito 403 (Forbidden)
Ricerca richieste modifica ordine
Ricerca richieste modifica ordine
Consente di effettuare una ricerca sulle richieste di modifica ordine presenti a sistema
Risponde a richieste POST verso /ordini/OrderChangeRequest
Per identificare effettuare una ricerca viene richiesto un oggetto JSON contenente i seguenti campi opzionali:
- requestChangeIds: lista degli ID delle richieste di modifica.
- orderLines: lista di oggetti contenenti i seguenti campi:
- orderId: ID dell'ordine
- eanCode: codice EAN della riga ordine
- orderBy: campo su cui effettuare l'ordinamento. Può assumere uno dei seguenti valori:
- changeId
- orderId
- rowNumber
- ean
- status
- reason
- orderDirection: direzione dell'ordinamento. Può assumere il valore asc per l'ordinamento crescente o il valore desc per l'ordinamento decrescente.
- pageSize: numero massimo di risultati restituiti da una chiamata. Se non specificato, saranno restituiti al massimo 50 risultati.
- pageIndex: numero di pagina dei risultati da restituire. Se non specificato, è restituita la prima pagina.
Controlli di validazione
Il metodo API effettua i seguenti controlli di validazione:
- deve essere indicato o una lista di requestChangeIds oppure l'oggetto orderLines contenente una lista di orderId - eanCode
L'API può restituire i seguenti codici di errore:
- 400 (Bad Request): query malformata.
- 401 (Unauthorized): il token di autenticazione non è valido oppure è scaduto.
L’operazione restituisce un oggetto JSON contenente i seguenti campi:
- totalCount: numero totale di richieste di modifica ordine trovati.
- totalPages: numero totale di pagine previste.
- page: informazioni sulla pagina corrente:
- index: indice della pagine corrente.
- size: dimensione della pagina.
- from: indice del primo elemento della pagina (se la pagina ha elementi)
- to: indice dell’ultimo elemento della pagina (se la pagina ha elementi)
- rows: elenco di richieste di modifica ordine. Contiene:
- requestChangeId: Id della richiesta di modifica.
- orderId: Id dell'ordine.
- rowNumber: Numero di riga dell'ordine.
- eanCode: Codice EAN della riga ordine.
- bookedQuantity: Quantità in prenotazione.
- occasionalDiscountPercentage: Percentuale di sconto occasionale.
- termsOfPaymentCode: Codice termini di pagamento.
- itemNote: Nota associata alla riga ordine.
- newBookedQuantity: Nuova quantità prenotata
- newOccasionalDiscountPercentage: Nuova percentuale di sconto occasionale.
- newTermsOfPaymentCode: Nuovo codice termini di pagamento.
- newItemNote: Nuova nota per la riga ordine.
- updatedDate: Data di ultimo aggiornamento della richiesta di modifica.
- status: Stato della richiesta di modifica.
- sapChangeDate: Data di modifica su SAP.
- sapReasonNotChange: Motivazione SAP per cui la modifica non è stata applicata.
Esempio richiesta
POST https://api.messaggerielibri.it/ordini/OrderChangeRequest
Authorization: Bearer [TOKEN JWT]
Body (I Esempio):
{
"RequestChangeIds" : [130, 134, 135]
}
Body (II Esempio):
{
"OrderLines" : [
{
"OrderId": 27960,
"EanCode": "9788838925993"
},
{
"OrderId": 27959,
"Eancode": "9788838925993"
}
]
}
Esempio risposta
Se la richiesta va a buon fine si ottiene in output una lista contente le informazioni principali sugli ordini trovati:
{
"totalCount": 2,
"totalPages": 1,
"page": {
"index": 1,
"size": 20,
"from": 1,
"to": 2
},
"rows": [
{
"requestChangeId": 134,
"orderId": 27959,
"rowNumber": 1,
"eanCode": "9788838925993",
"itemNote": "ALTRI CASI PER IL COMMISSARIO MONTALBANO",
"newBookedQuantity": 10,
"newOccasionalDiscountPercentage": 35.00,
"newTermsOfPaymentCode": "21",
"newItemNote": "note nuove",
"updatedDate": "2025-09-10T14:55:54.5733333",
"status": "Pending"
},
{
"requestChangeId": 135,
"orderId": 27960,
"rowNumber": 1,
"eanCode": "9788838925993",
"bookedQuantity": 1,
"itemNote": "ALTRI CASI PER IL COMMISSARIO MONTALBANO",
"newBookedQuantity": 10,
"newOccasionalDiscountPercentage": 35.00,
"newTermsOfPaymentCode": "21",
"newItemNote": "note nuove",
"updatedDate": "2025-09-10T16:29:43.19",
"status": "Pending"
}
]
}
Features
Per utilizzare il metodo API è necessario possedere una o più delle seguenti
features:
altrimenti viene restituito 403 (Forbidden)
Consultazione condizioni di vendita
Consultazione condizioni di vendita
Consente di consultare le condizioni di vendita
Risponde a richieste POST verso /ordini/SalesConditions
Per identificare effettuare una ricerca viene richiesto un oggetto JSON contenente i seguenti campi obbligatori:
- CustomerCode: codice cliente
- DocumentType: tipo di ordine
- Eans: lista di EAN
Controlli di validazione
Il metodo API effettua i seguenti controlli di validazione:
- deve essere indicato almeno un EAN, massimo 100
- codici EAN congruenti all'utenza chiamante
- codice cliente obbligatorio
- tipo di ordine obbligatorio e appartenente alla seguente lista:
- restock (Rifornimento),
- newTitle (Novità),
- campaign (Campagna),
- deposit (Deposito),
- freeOrder (Omaggi),
- specialOrder (Ordini Speciali),
- specialOrderE (Ordini Speciali E),
- publisherOffice (Reso ufficio editore),
- rifoVendorStock (Rifo Magedi Scorta)
L'API può restituire i seguenti codici di errore:
- 400 (Bad Request): query malformata.
- 401 (Unauthorized): il token di autenticazione non è valido oppure è scaduto.
- 404 (Not Found): non sono stati trovate informazioni per i dati indicati.
L’operazione restituisce un oggetto JSON contenente i seguenti campi:
- ean: codice EAN
- occasionalDiscountPercentage: percentuale di sconto
- termsOfPaymentCode: codice termini di pagamento
Esempio richiesta
POST https://api.messaggerielibri.it/ordini/SalesConditions
Authorization: Bearer [TOKEN JWT]
Body di esempio:
{
"CustomerCode": "0000021500",
"Eans": ["9788807880414", "9788838925993"],
"DocumentType": "NewTitle"
}
Esempio risposta
Se la richiesta va a buon fine si ottiene in output una lista contente le condizioni di vendita:
[
{
"ean": "9788807880414",
"occasionalDiscountPercentage": 0.0,
"termsOfPaymentCode": "6"
},
{
"ean": "9788838925993",
"occasionalDiscountPercentage": 0.0,
"termsOfPaymentCode": "6"
}
]
Features
Per utilizzare il metodo API è necessario possedere una o più delle seguenti
features:
altrimenti viene restituito 403 (Forbidden)
|
