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
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)
|
