Creazione cedola

Consente di creare una cedola

Risponde a richieste POST verso: /ordini/coupon

La creazione di una nuova cedola richiede un oggetto JSON contenente i seguenti campi:

• code: codice della cedola - string (max 10 caratteri alfanumerici) [obbligatorio]
• description: descrizione della cedola - string (max 50 caratteri) [obbligatorio]
• startDate: data inizio giro - string date (formato yyyy-mm-dd) [obbligatorio]
• endDate: data fine giro - string date (formato yyyy-mm-dd) [obbligatorio]

Controlli di validazione

Il metodo API effettua i seguenti controlli di validazione:

• il codice cedola(code) non deve già essere presente a sistema per la rete che la crea
• la data inzio giro(startDate) deve essere inferiore alla data fine giro(endDate)
• la data fine giro(endDate) deve essere superiore alla data inizio giro(startDate)

L'API può restituire i seguenti codici di errore:

• 400 (Bad Request): query malformata (il messaggio di risposta contiene indicazioni sugli errori di validazione riscontrati). 
• 401 (Unauthorized): il token di autenticazione non è valido oppure è scaduto.
• 409 (Conflict): cedola già esistente per la rete.

Esempio richiesta

POST https://api.messaggerielibri.it/ordini/coupon
Authorization: Bearer [TOKEN JWT]
{
	"code": "cedola1",
	"description": "cedola 1",
	"startDate": "2024-08-01",
	"endDate": "2024-08-31"
}

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:

• coupon_add

altrimenti viene restituito 403 (Forbidden)

Aggiunta titoli alla cedola

Consente di aggiungere una lista di titoli ad una cedola.

Risponde a richieste POST verso: /ordini/coupon/{code}/titles, dove {code} rappresenta il codice della cedola.

Per identificare i titoli da aggiungere alla cedola viene richiesto un oggetto JSON contenente una lista di ean.

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 cedola(code) deve corrispondere ad una cedola esistente, non pubblica e deve appartenere alla Rete utilizzatrice dell'API.
• ogni ean della lista deve essere presente nell'Anagrafica Materiale, deve appartenere ad Editori promossi dalla stessa Rete utilizzatrice dalla API e non deve essere già presente nella cedola indicata.

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.
• 409 (Conflict): titolo già presente nella cedola.

Esempio richiesta: 

POST
https://api.messaggerielibri.it/ordini/coupon/cedola1/titles
Authorization: Bearer[TOKEN JWT]

Esempio body richiesta

["9788876180088", "9788876180101"]

Features

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

• coupon_add

altrimenti viene restituito 403 (Forbidden)

Rimozione titoli dalla cedola

Consente di rimuovere una lista di titoli da una cedola.

Risponde a richieste POST verso: /ordini/coupon/{code}/titlesDelete, dove {code} rappresenta il codice della cedola.

Per identificare i titoli da rimuovere dalla cedola viene richiesto un oggetto JSON contenente una lista di ean.

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 cedola(code) deve corrispondere ad una cedola esistente, non pubblica e deve appartenere alla Rete utilizzatrice dell'API.
• ogni ean della lista di titoli da rimuovere deve essere presente nella cedola.

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.

Esempio richiesta: 

POST
https://api.messaggerielibri.it/ordini/coupon/cedola1/titlesDelete
Authorization: Bearer[TOKEN JWT]

Esempio body richiesta

["9788876180088", "9788876180101"]

Features

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

• coupon_add

altrimenti viene restituito 403 (Forbidden)

Recupero dettaglio singola cedola

Consente di recuperare i dettagli di una cedola.

Risponde a richieste GET verso: /ordini/coupon/{code}, dove {code} rappresenta il codice della cedola.

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

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

• state: stato della cedola
• public: flag che indica se la cedola è pubblica
• code: codice cedola
• description: descrizione
• startDate: data di inizio cedola
• endDate: data di fine cedola

Il dettaglio posizioni della cedola:

• eanCode: codice EAN del prodotto
• vendorCode: codice editore
• vendor: editore
• shortArticleTitle: titolo del prodotto
• author: autore del prodotto
• vatCode: codice aliquota IVA
• vatDescription: aliquota IVA
• priceList: prezzo
• articleSaleStatusCode: codice stato vendita
• articleSaleStatusDescription: stasto vendita
• articleStatusCode: codice risposta editore
• articleStatusDescription: risposta editore

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: 

POST
https://api.messaggerielibri.it/ordini/coupon/cedola1
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:

{
	"coupon": {
		"state": "Open",
		"public": true,
		"code": "cedola3",
		"description": "cedola 3",
		"startDate": "2023-08-01T00:00:00",
		"endDate": "2024-08-25T00:00:00"
	},
	"titles": [
		{
			"eanCode": "9788876537035",
			"vendorCode": "A33",
			"vendor": "G&B PRESS",
			"shortArticleTitle": "NUMERISECONDI",
			"author": "AUTORI VARI",
			"vatCode": "L",
			"vatDescription": "ART. 74 IVA LIBRO ASSOLTA",
			"priceList": 38.00,
			"articleSaleStatusCode": "1",
			"articleSaleStatusDescription": "IN COMMERCIO",
			"articleStatusCode": "1",
			"articleStatusDescription": "DISPONIBILE"
		},
		{
			"eanCode": "9788876612718",
			"vendorCode": "0000000300",
			"vendor": "CELID",
			"shortArticleTitle": "CASTELLO DI MONCALIERI",
			"author": "PERNICE F. (CUR.)",
			"vatCode": "L",
			"vatDescription": "ART. 74 IVA LIBRO ASSOLTA",
			"priceList": 11.00,
			"articleSaleStatusCode": "1",
			"articleSaleStatusDescription": "IN COMMERCIO",
			"articleStatusCode": "1",
			"articleStatusDescription": "DISPONIBILE"
		}
	]
}

Features

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

• coupon_read

altrimenti viene restituito 403 (Forbidden)

Modifica cedola

Consente di modificare una cedola

Risponde a richieste PUT verso: /ordini/coupon/{code}, dove {code} rappresenta il codice della cedola.

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

• description: descrizione della cedola - string (max 50 caratteri) [obbligatorio]
• startDate: data inizio giro - string date (formato yyyy-mm-dd) [obbligatorio]
• endDate: data fine giro - string date (formato yyyy-mm-dd) [obbligatorio]

Controlli di validazione

Il metodo API effettua i seguenti controlli di validazione:

• il codice cedola (code) deve corrispondere ad una cedola esistente, non pubblica e deve appartenere alla Rete utilizzatrice dell'API.
• la data inzio giro (startDate) deve essere inferiore alla data fine giro(endDate).
• la data fine giro (endDate) deve essere superiore alla data inizio giro(startDate).

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

PUT https://api.messaggerielibri.it/ordini/Coupon/cedola1
Authorization: Bearer [TOKEN JWT]
{
	"description": "cedola 1",
	"startDate": "2024-07-01",
	"endDate": "2024-08-31"
}

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:

• coupon_add

altrimenti viene restituito 403 (Forbidden)

Elimina cedola

Consente di eliminare una cedola.

Risponde a richieste DELETE verso: /ordini/coupon/{code}, dove {code} rappresenta il codice della cedola.

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.

Controlli di validazione

Il metodo API effettua i seguenti controlli di validazione:

• code deve esistere e appartenente alla rete creatrice della cedola.
• La cedola non deve essere pubblica.

Esempio richiesta: 

DELETE
https://api.messaggerielibri.it/ordini/coupon/cedola1
Authorization: Bearer[TOKEN JWT]

Pubblicazione/Depubblicazione cedola

Consente di pubblicare/depubblicare una cedola.

Risponde a richieste POST verso: /ordini/coupon/{code}/publish - /ordini/coupon/{code}/unpublish, dove {code} rappresenta il codice della cedola.

Controlli di validazione

Il metodo API effettua i seguenti controlli di validazione:

• code deve esistere e appartenente alla rete creatrice della cedola.
• In caso di pubblicazione la cedola non deve essere già pubblica.
• In caso di depubblicazione la cedola deve essere pubblica.

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: 

POST
https://api.messaggerielibri.it/ordini/coupon/cedola1/publish
Authorization: Bearer[TOKEN JWT]

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:

• coupon_add

altrimenti viene restituito 403 (Forbidden)

Ricerca cedole

Consente di effettuare una ricerca sulle cedole

Risponde a richieste GET verso /ordini/coupon

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

• code: codice cedola - string
• startDate: data inizio giro - date 
• endDate: data fin giro - date
• state: stato della cedola - può assumere i seguenti valori di tipo string:
  • open,
  • closed,
  • pending
• public: flag che indica se la cedola è pubblica (true/false)
• ean: codice EAN - string
• promotionalNetwork: codice rete promozionale - string
• orderBy: campo su cui effettuare l’ordinamento - può assumere i seguenti valori di tipo string:
  • code,
  • startDate,
  • endDate,
  • titleCount
• 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

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

• totalCount: numero totale di 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)
• coupons: elenco delle cedole. Contiene:
  
  • code: codice cedola
  • description: descrizione cedola
  • state: stato della cedola. Può assumere i seguenti valori: open, closed, pending
  • startDate: data inizio giro
  • endDate: data fine giro
  • titleCount: numero di titoli presenti nella cedola
    
    

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/coupon?code=cedola1
Authorization: Bearer [TOKEN JWT]

Esempio risposta

{
	"totalCount": 1,
	"totalPages": 1,
	"page": {
		"index": 1,
		"size": 50,
		"from": 1,
		"to": 1
	},
	"coupons": [
		{
			"code": "cedola1",
			"description": "cedola 1",
			"state": "Closed",
                        "public": true,
			"startDate": "2024-07-01T00:00:00",
			"endDate": "2024-07-31T00:00:00",
                        "public": false,
			"titleCount": 3
		}
	]
}

Features

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

• coupon_read

altrimenti viene restituito 403 (Forbidden)

Rimozione titolo dalla cedola

Consente di rimuovere un titolo dalla cedola.

Risponde a richieste DELETE verso: /ordini/coupon/{code}/title/{eanCode}, dove {code} rappresenta il codice della cedola e {eanCode} rappresenta il codice EAN 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 cedola(code) deve corrispondere ad una cedola esistente, non pubblica e deve appartenere alla Rete utilizzatrice dell'API.
• l'ean(eanCode) da rimuovere deve essere presente nella cedola.

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/coupon/cedola1/title/9788876180101
Authorization: Bearer[TOKEN JWT]