Creazione prenotazione

Consente di caricare a sistema una lista di prenotazioni

Risponde a richieste POST verso: /ordini/Reservation

Per identificare la lista delle prenotazioni da inviare viene richiesto un oggetto JSON contenente i seguenti campi:

• couponCode: codice cedola.
• customerCode: codice destinatario.
• orderNumber(opzionale): numero/riferimento ordine cliente.
• titles: lista delle posizioni della prenotazione(ad ogni prenotazione possono essere associate una o più posizioni).

Posizione dell'ordine

La posizione della prenotazione è un oggetto JSON che contiene i seguenti campi:

• ean: codice EAN del titolo da ordinare.
• quantity: quantità totale.
• occasionalDiscount(opzionale): sconto occasionale.
• occasionalPayment(opzionale): pagamento occasionale.
• notes(opzionale): nota di posizione.

Controlli di validazione

Il metodo API effettua i seguenti controlli di validazione:

• couponCode deve esistere e appartenente alla rete creatrice della cedola.
• customerCode deve essere valido.
• eanCode valido e presente all'interno della cedola.
• occasionalDiscount deve essere una percentuale  > di 0 e < di 100.
• occasionalPayment deve essere un valore > 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 1 prenotazionoe la quale contiene 3 titoli:

POST https://api.messaggerielibri.it/ordini/Reservation
Authorization: Bearer [TOKEN JWT]

Esempio body richiesta

{
    "couponCode": "cedola2",
    "customerCode": "0000008400",
    "titles":  [     
        {
        "ean": "9782849075883",
        "quantity": 3,
				"OccasionalDiscountPercentage": 23.64,
				"OccasionalPayment": 83.5,
        "notes": "000000"
      },
			{
        "ean": "9788876180088",
        "quantity": 21,
				"OccasionalDiscountPercentage": 76.3,
        "notes": "000000"
      },
			{
        "ean": "9788876180101",
        "quantity": 86,
				"OccasionalDiscountPercentage": 1.7,
        "notes": "000000"
      }
    ]
}

Features

Per utilizzare il metodo API è necessario possedere una o più delle seguenti features:

• RESERVATION_ADD

altrimenti viene restituito 403 (Forbidden)

Modifica prenotazione

Consente di modificare una prenotazione

Risponde a richieste PUT verso: /ordini/reservation/{id}/{item}, dove {id} rappresenta l'identificativo della prenotazione e {item} rappresenta la riga della prenotazione da modificare.

La modifica di una prenotazione richiede un oggetto JSON contenente i seguenti campi:

• quantity: quantità prenotata - int
• occasionalDiscountPercentage: sconto occasionale - decimal 
• occasionalPayment: pagamento occasionale - decimal
• orderId: identificativo dell'ordine - string

Controlli di validazione

Il metodo API effettua i seguenti controlli di validazione:

• la percentuale di sconto occasionale (occasionalDiscountPercentage) deve  deve essere una percentuale  >= di 0 e <= di 100.
• l'ordine (orderId) deve esistere.
• la rete utilizzatrice delle API può modificare solo prenotazioni novità collegate ad una cedola associata alla Rete.

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 alcuna prenotazione visibile.

Esempio richiesta

PUT https://api.messaggerielibri.it/ordini/reservation/6/1
Authorization: Bearer [TOKEN JWT]
{
	"quantity": "5",
	"occasionalDiscountPercentage": "23.50",
	"occasionalPayment": "83",
	"orderId": 123
}

Esempio risposta

Se l’esecuzione è terminata con successo, l’API restituisce 200 OK senza alcun body.

Features

Per utilizzare il metodo API è necessario possedere una o più delle seguenti features:

• reservation_edit

altrimenti viene restituito 403 (Forbidden)

Recupero dettaglio prenotazione

Consente di recuperare i dettagli di una prenotazione.

Risponde a richieste GET verso: /ordini/coupon/{couponCode}/ean/{ean}/reservation, dove {couponCode} rappresenta il codice della cedola e {ean} il codice ean.

E' possibile passare in querystring i seguenti parametri, tutti opzionali:

• customer: lista codici clienti
• startDate: data creazione della prenotazione (da) - date 
• endDate: data creazione della prenotazione (a) - date 

L’operazione restituisce uno oggetto JSON contenente i seguenti campi:

La testata del coupon è un oggetto JSON che contiene i seguenti campi:

• id: Id prenotazione,
• rowNumber: riga prenotazione,
• couponCode: codice cedola,
• salesAgent: agente 
  • code: codice,
  • description: descrizione.
• customer: cliente 
  • code: codice,
  • description: descrizione.
• eanCode: codice ean,
• quantity: quantità prenotata,
• occasionalDiscountPercentage: sconto occasionale,
• occasionalPayment: pagamento occasionale
• notes: note collegate alla riga prenotazione
• order: informazioni sull'ordine
  • id: id ordine
  • rowNumber: numero riga ordine
  • type: tipo di ordine
  • customerNumber: numero ordine cliente

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 alcuna cedola visibile.

Esempio richiesta: 

GET
https://api.messaggerielibri.it/ordini/coupon/cedolaRR1/ean/9788876670817/reservation?customer=0000008400&startDate=2024-01-25&endDate=2025-06-14
Authorization: Bearer[TOKEN JWT]

Esempio risposta

Se la richiesta va a buon fine si ottiene in output una lista contente le informazioni principali sulla cedola:

[
	{
		"id": 69,
		"rowNumber": 1,
		"couponCode": "API8561",
		"salesAgent": {
			"code": "UD191",
			"description": "MAGELLI DANIELE"
		},
		"customer": {
			"code": "0000008400",
			"description": "CATTANEO L. DI C. CATTANEO."
		},
		"eanCode": "9788874714445",
		"quantity": 10,
		"occasionalDiscountPercentage": 15.00,
		"occasionalPayment": 30.00,
		"notes": "nessuna",
		"order": {
			"id": 3134,
			"rowNumber": 1,
			"type": "newTitle",
			"customerNumber": "3134"
		}
	}
]

Features

Per utilizzare il metodo API è necessario possedere una o più delle seguenti features:

• RESERVATION_READ

altrimenti viene restituito 403 (Forbidden)

Rimozione titolo dalla prenotazione

Consente di rimuovere un titolo dalla prenotazione.

Risponde a richieste DELETE verso: /ordini/reservation/{id}/{item}, dove {id} rappresenta il codice della prenotazione e {item} rappresenta il codice del titolo da rimuovere.

Se l’esecuzione è terminata con successo, l’API restituisce 204 No Content senza alcun body.

Controlli di validazione

Il metodo API effettua i seguenti controlli di validazione:

• il codice prenotazione(id) deve corrispondere ad una prenotazione esistente.
• l'item(item) da rimuovere deve essere presente nella prenotazione.
• la rete utilizzatrice delle API può eliminare solo le righe delle prenotazioni novità collegate ad una cedola associata alla Rete.

Se l’esecuzione è terminata con successo, l’API restituisce 204 No Content senza alcun body.

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 alcuna cedola visibile o alcun ean.

Esempio richiesta: 

DELETE
https://api.messaggerielibri.it/ordini/reservation/1/3
Authorization: Bearer[TOKEN JWT]

Features

Per utilizzare il metodo API è necessario possedere una o più delle seguenti features:

• RESERVATION_EDIT

altrimenti viene restituito 403 (Forbidden)

Trasmissione prenotazioni

Consente di caricare a sistema una lista di ordini

Risponde a richieste POST verso: /ordini/Reservation/transmit

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.
• customerCodes(opzionale): lista codici destinatario della merce.
• documentType: tipo documento / fornitura. Valori ammessi "restock" e "newTitle".
• notes(opzionale): note di testata.
• startDate(opzionale): data creazione della prenotazione
• endDate(opzionale): data creazione della prenotazione

Items dell'ordine

Elenco delle righe cedole da convertire in ordini, un singolo rigo è formato da:

• eanCode: codice ean.
• couponCode: codice coupon.

Controlli di validazione

Il metodo API effettua i seguenti controlli di validazione:

• DocumentType: deve avere uno dei seguenti valori: "restock" (rifornimento), "newTitle" (novità)
• La "Data Prenotazione (dal)" è antecedente alla "Data Prenotazione (al)"

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

POST https://api.messaggerielibri.it/ordini/Reservation/transmit HTTP/1.1
Authorization: Bearer [TOKEN JWT]

Esempio body richiesta

{
	"header": {
			"orderNumber": "test",	 
			"documentType": "restock",	  
            "customerCodes": ["0000008400", "0000021500"]
			"notes": "prova"
	},
	"items": [
		{
				"eanCode": "9788874714445"
		},
		{
				"eanCode": "9788874719636",
			  "couponCode": "cedola1"	
		}	
	]
}

Esempio risposta

Se l’esecuzione è terminata con successo, l’API restituisce i numeri d'ordine (orderId) che identifica gli ordini creati:

[
	"3045",
	"3044",
	"3046"
]

Features

Per utilizzare il metodo API è necessario possedere una o più delle seguenti features:

• RESERVATION_TRANSMIT

altrimenti viene restituito 403 (Forbidden)

Ricerca Prenotazioni Raccolte per Riga-Cedola

Consente il recupero delle prenotazioni raccolte per Riga-Cedola

Risponde a richieste GET verso /ordini/reservation

E' possibile passare in querystring i seguenti parametri, tutti opzionali:

• coupon: lista dei codici coupon
• ean: lista dei codici ean
• Customer: lista dei codici cliente
• launchYear: anno di lancio
• launchNumber: numero lancio
• startDate: data di inizio
• endDate: data di fine
• details: flag per indicare se includere anche i dettagli delle prenotazioni - string
• orderBy: campo su cui effettuare l’ordinamento - può assumere i seguenti valori di tipo string:
  • coupon,
  • ean,
  • vendorCode,
  • vendorName,
  • title,
  • author
• orderDirection: direzione dell’ordinamento - può assumere i seguenti valori di tipo string:
  • asc,
  • desc
• 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 viene restituito il sommario di tutte le raccolta per riga-cedola.

L’operazione restituisce uno oggetto JSON contenente i seguenti campi:

• totalCount: numero totale di raccolte trovate.
• 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 delle raccolte (vedi: elenco delle raccolte).

Elenco delle raccolte

L’elenco degli raccolte riga-cedola è un array di oggetti JSON aventi la seguente struttura:

• couponCode: codice coupon
• eanCode: codice ean
• vendor: 
  • code: codice,
  • description: descrizione.
• title: titolo
• author: autore
• quantity: informazioni sulla quantità
  • reserved: quantità prenotata
  • transmitted:
    • newOrder: quantità trasmessa come nuovo ordine
    • restock: quantità trasmessa come restock
  • toBeTransmitted: quantità non trasmessa
• reservations: dettaglio delle prenotazioni (vedi: dettaglio prenotazione)

Dettaglio prenotazione

Il dettaglio prenotazione è un array di oggetti JSON aventi la seguente struttura:

• id: id prenotazione
• rowNumber: numero riga prenotazione
• salesAgent:  agente
  • code: codice,
  • description: descrizione.
• customer: cliente
  • code: codice,
  • description: descrizione.
• quantity: quantità
• occasionalDiscountPercentage: sconto occasionale
• occasionalPayment: pagamento occasionale
• notes: note
• order: informazioni sull'ordine
  • id: id ordine
  • rowNumber: numero riga ordine
  • type: tipo di ordine
  • customerNumber: numero ordine cliente

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/reservation?coupon=API8561.2&ean=9788874714445&details
Authorization: Bearer [TOKEN JWT]

Esempio risposta

Se la richiesta va a buon fine si ottiene in output il sommario delle raccolte riga-cedola presenti a sistema.

{
	"totalCount": 1,
	"totalPages": 1,
	"page": {
		"index": 1,
		"size": 50,
		"from": 1,
		"to": 1
	},
	"rows": [
		{
			"couponCode": "API8561.2",
			"eanCode": "9788874714445",
			"vendor": {
				"code": "542",
				"description": "KAPPA EDIZIONI - PEGASUS"
			},
			"title": "KAPPA  LA SCENA DELL'INFERNO",
			"author": "AKUTAGAWA RYUNOSUKE -",
			"quantity": {
				"reserved": 72,
				"transmitted": {
					"newOrder": 60,
					"restock": 0
				},
				"toBeTransmitted": 12
			},
			"reservations": [
				{
					"id": 66,
					"rowNumber": 1,
					"salesAgent": {
						"code": "UD191",
						"description": "MAGELLI DANIELE"
					},
					"customer": {
						"code": "00021500",
						"description": "HOEPLI SPA"
					},
					"quantity": 30,
					"occasionalDiscountPercentage": 15.00,
					"occasionalPayment": 30.00,
					"notes": "nessuna",
					"order": {
						"id": 3118,
						"rowNumber": 1,
						"type": "newTitle",
						"customerNumber": "1912.02"
					}
				},
				{
					"id": 67,
					"rowNumber": 1,
					"salesAgent": {
						"code": "UD191",
						"description": "MAGELLI DANIELE"
					},
					"customer": {
						"code": "00173800",
						"description": "FAGNANI IDEALE DI P.FAGNANI"
					},
					"quantity": 20,
					"occasionalDiscountPercentage": 15.00,
					"occasionalPayment": 30.00,
					"notes": "nessuna",
					"order": {
						"id": 3119,
						"rowNumber": 1,
						"type": "newTitle",
						"customerNumber": "1912.02"
					}
				},
				{
					"id": 68,
					"rowNumber": 1,
					"salesAgent": {
						"code": "UD191",
						"description": "MAGELLI DANIELE"
					},
					"customer": {
						"code": "00008400",
						"description": "CATTANEO L. DI C. CATTANEO."
					},
					"quantity": 10,
					"order": {
						"id": 3120,
						"rowNumber": 1,
						"type": "newTitle",
						"customerNumber": "1912.02"
					}
				},
				{
					"id": 74,
					"rowNumber": 1,
					"salesAgent": {
						"code": "UD191",
						"description": "MAGELLI DANIELE"
					},
					"customer": {
						"code": "00008400",
						"description": "CATTANEO L. DI C. CATTANEO."
					},
					"quantity": 12,
					"occasionalDiscountPercentage": 12.00,
					"occasionalPayment": 12.00,
					"notes": "12",
					"order": {
						"id": 0,
						"rowNumber": 0
					}
				}
			]
		}
	]
}

Features

Per utilizzare il metodo API è necessario possedere una o più delle seguenti features:

• Resevation_Read

altrimenti viene restituito 403 (Forbidden)