Questa API consente di consultare, creare e modificare dei titoli.

Per gestire le API delle rese tramite autenticazione è necessario utilizzare lo scope: title_api_scope.

Operazioni

L'API espone i seguenti metodi:

Ricerca titoli

Consente di ricercare i titoli presenti a catalogo in base ai parametri di ricerca forniti.

Risponde a richieste GET verso: /titoli/title

La ricerca accetta i seguenti parametri: 

Nome Campo

Descrizione Campo

Tipo Dato 

Note 

search 

Testo di ricerca 

string 

Stringa di ricerca per testo libero. Se non specificato, sono restituiti tutti i titoli presenti. 

La ricerca è effettuata nei seguenti campi: 

  • Titolo 
  • Autore 
  • Editore 

ean 

Filtro per codice EAN 

string 

Può essere passato più volte per filtrare su più EAN 

title 

Filtro di ricerca all’interno del titolo 

string 

 

author 

Filtro di ricerca all’interno dell’autore 

string 

 

authorEx

Filtro per autore (corrispondenza esatta)

string

Può essere passato più volte per filtrare su più autori

vendor 

Filtro per codice editore 

string 

Può essere passato più volte per filtrare su più editori 

series 

Filtro per codice collana 

string 

Può essere passato più volte per filtrare su più collane 

language 

Filtro per codice lingua 

string 

Può essere passato più volte per filtrare su più lingue 

creationDateFrom 

Filtro per data creazione (da) 

date 

 

creationDateTo 

Filtro per data creazione (a) 

date 

 

launchDateFrom 

Filtro per data lancio (da) 

date 

 

launchDateTo 

Filtro per data lancio (a) 

date 

 

lastChangeDate

Filtro per data ultima modifica

date

 

price 

Filtro per prezzo 

object

Può essere passato più volte per filtrare su più fasce di prezzo. Contiene:

  • from: dal prezzo (decimal)
  • to: al prezzo (decimal)

Se "to" non è presente, cerca tutti i titoli con prezzo maggiore di "from". 

published 

Filtro di ricerca sul fatto che un titolo sia pubblicato o meno. 

boolean 

 

articleSaleStatus 

Filtro per stato vendita 

enum 

Valori ammessi: *, 0, 1, 2, 9 

articleStatus 

Filtro per risposta editore 

enum 

Valori ammessi: *, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 

pod 

Filtro di ricerca sul fatto che un titolo sia "print on demand" o meno. 

string 

 

promotionCampaign

Filtro per codice campagna promozionale

string

 

sector

Filtro per codice settore

string

 

facet

Filtro che indica se includere o meno il raggruppamento dei risultati in "facet"

boolean

 

orderBy 

Campo su cui effettuare l’ordinamento 

string 

Se non specificato, viene applicato l'ordinamento per Stato Vendita (1, 2, 9, 0)

orderDirection 

Direzione dell'ordinamento (crescente o decrescente) 

enum 

Valori ammessi: asc, desc 

pageSize 

Numero di risultati per pagina 

string 

Se non specificato, saranno restituiti al massimo 50 risultati. 

pageIndex 

Numero pagina 

string 

Se non specificato, è restituita la prima pagina. 

forEdit

Flag che indica se la ricerca avviene da parte della pagina di modifica anagrafica

boolean

 

canBeOrdered

Flag che indica se restituire solo i titoli che possono essere ordinati

boolean

 

hiddenExcluded

Flag che indica se escludere i titoli nascosti e i materiali pubblicitari

boolean

 

 

L'operazione restituisce un oggetto JSON con la seguente struttura: 

  • facets: raggruppamento dei risultati in facet. Visibili se in querystring viene passato "facet" (vedi: Elenco dei facet).
  • totalCount: numero totale di titoli trovati dalla ricerca 
  • totalPages: numero totale di pagine che compongono i risultati di ricerca 
  • page: informazioni sulla pagina corrente 
    • index: numero di pagina 
    • size: dimensione della pagina 
    • from: indice del primo titolo della pagina 
    • to: indice dell’ultimo titolo della pagina 
  • titles: lista dei titoli contenuti nella pagina corrente (vedi: Elenco dei titoli).

 

Elenco dei titoli

L’elenco di titoli è un array di oggetti JSON aventi la seguente struttura:

Nome Campo 

Descrizione Campo 

Tipo Dato 

coverUrl

Url immagine di copertina

string

title 

Titolo completo 

string 

bibliographicTitle

Titolo a catalogo

string

materialCode

Codice materiale

string

ean 

Codice EAN 

string 

shortTitle 

Titolo breve 

string 

author 

Autore 

string 

bibliographicAuthor

Autore a catalogo

string

designer 

Disegnatore 

string 

screenwriter 

Sceneggiatore 

string 

publisher 

Editore

string 

originalPublisher

Editore originale 

string

titleVendorCode 

Codice del titolo per l’editore 

string 

vat

IVA. Contiene:

  • code: codice IVA
  • description: Descrizione dell’aliquota IVA 

object

creationDate 

Data di creazione 

date 

publicationDate 

Data di pubblicazione 

date 

launchDate 

Data di lancio 

date 

launchYear

Anno di lancio

string

launchNumber

Numero di lancio

string

outOfCatalogueDate 

Data di uscita dal catalogo 

date 

language 

Codice lingua 

string 

price 

Prezzo 

string 

reprintDate

Data di ristampa

date

pageCount 

Numero pagine 

integer 

volumeNumber 

Numero volume 

string 

availability

Disponibilità. I valori possibili che può assumere sono: 

  • available: disponibile
  • printOnDemand: stampa a richiesta
  • ordering: in ordine
  • reprinting: in ristampa
  • cannotBeOrdered: non ordinabile
  • other: altro

string

selloutPosition

Posizione del titolo in classifica

integer

vendor 

Editore. Contiene:

  • code: codice editore
  • description: descrizione editore

object

campaign

Campagna. Contiene:

  • code: codice campagna
  • description: descrizione campagna

object

package

Confezione. Contiene:

  • code: codice confezione
  • description: descrizione confezione

object

editorialSeries

Collana. Contiene:

  • code: codice collana
  • description: descrizione collana

object

genre

Codice genere

string

articleSaleStatus

Stato vendita. Contiene:

  • code: codice stato vendita
  • description: descrizione dello stato vendita 

object

articleStatus

Risposta editore. Contiene:

  • code: codice risposta editore
  • description: descrizione della risposta editore

object

workingState

Stato di lavorazione anagrafica. I valori possibili che può assumere sono: 

  • toBeValidated: da validare
  • validated: validato

string

registrationLimit

Data limite per l'iscrizione al lancio

date

dimensions

Dimensioni del titolo. Contiene:

  • netWeight: peso
  • height: altezza
  • width: larghezza
  • length: profondità

object

commodityType

Tipo di merce. Contiene:

  • code: codice del tipo
  • description: descrizione del tipo

object

sector

Settore. Contiene:

  • code: codice del settore
  • description: descrizione del settore

object

shelf

Descrizione dello scaffale

string

containedInPackage

Flag che indica se è contenuto in confezione

boolean

 

Elenco dei facet

Nome Campo 

Descrizione Campo 

Tipo Dato 

vendor

Raggruppamento degli editori, è una lista di oggetti contenenti i seguenti campi:

  • value: editore. Contiene:
    • code: codice editore
    • name: nome editore
  • count: numero di elementi corrispondenti
array

series

Raggruppamento delle collane, è una lista di oggetti contenenti i seguenti campi:

  • value: collana. Contiene: 
    • code: codice collana
    • description: nome collana
    • vendor: editore. Contiene:
      • code: codice editore
      • name: nome editore
  • count: numero di elementi corrispondenti

array

author

Raggruppamento degli autori, è una lista di oggetti contenenti i seguenti campi:

  • value: nome dell'autore
  • count: numero di elementi corrispondenti

array

bibliographicAuthor

Raggruppamento degli autori a catalogo, è una lista di oggetti contenenti i seguenti campi:

  • value: nome dell'autore a catalogo
  • count: numero di elementi corrispondenti

array

language

Raggruppamento delle lingue, è una lista di oggetti contenenti i seguenti campi:

  • value: codice della lingua
  • count: numero di elementi corrispondenti

array

price

Raggruppamento delle fasce di prezzo, è una lista di oggetti contenenti i seguenti campi:

  • value: fascia di prezzo. Contiene:
    • from: valore iniziale della fascia di prezzo
    • to: valore finale della fascia di prezzo
  • count: numero di elementi corrispondenti

array

printOnDemand

Raggruppamento dello stato di print on demand, è una lista di oggetti contenenti i seguenti campi:

  • value: valore di print on demand
  • count: numero di elementi corrispondenti

array

hasBeenPublished

Raggruppamento dello stato di pubblicazione, è una lista di oggetti contenenti i seguenti campi:

  • value: valore di pubblicazione
  • count: numero di elementi corrispondenti

array

articleSaleStatus

Raggruppamento degli stati di vendita, è una lista di oggetti contenenti i seguenti campi:

  • value: codice dello stato di vendita
  • count: numero di elementi corrispondenti

array

articleStatus

Raggruppamento delle risposte editore, è una lista di oggetti contenenti i seguenti campi:

  • value: codice della risposta editor
  • count: numero di elementi corrispondenti

array

sector

Raggruppamento dei settori, è una lista di oggetti contenenti i seguenti campi:

  • value: settore. Contiene:
    • code: codice settore
    • description: descrizione settore
  • count: numero di elementi corrispondenti

array

 

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/titoli/title?ean=9788807492433&pageIndex=1
Authorization: Bearer[TOKEN JWT]

 

Esempio risposta: 

{
	"totalCount": 1,
	"totalPages": 1,
	"page": {
		"index": 1,
		"size": 50,
		"from": 1,
		"to": 1
	},
	"titles": [
		{
			"coverUrl": "https://img.messaggerielibri.it/images/9788807492433_0_500_0_0.jpg",
			"title": "CINQUE VITE DI GIORGIO SCERBANENCO",
			"bibliographicTitle": "CINQUE VITE DI GIORGIO SCERBANENCO",
			"materialCode": "000000008807492433",
			"ean": "9788807492433",
			"shortTitle": "CINQUE VITE DI GIORGIO SCERB",
			"author": "SCERBANENKO ALBERTO",
			"bibliographicAuthor": "CINQUE VITE DI GIORGIO SCERBANENCO",
			"publisher": "FELTRINELLI EDITORE",
			"vat": {
				"code": "L",
				"description": "ART. 74 IVA LIBRO ASSOLTA"
			},
			"creationDate": "2018-05-18T12:00:00+02:00",
			"lastChangeDate": "2018-11-05",
			"publicationDate": "2018-10-01",
			"launchYear": 2023,
			"launchNumber": "60.0",
			"language": "IT",
			"price": 0.00,
			"availability": "other",
			"vendor": {
				"code": "0000000243",
				"description": "FELTRINELLI EDITORE"
			},
			"articleSaleStatus": {
				"code": "0",
				"description": "DI PROSSIMA PUBBLICAZIONE"
			},
			"articleStatus": {
				"code": "0",
				"description": "DI PROSSIMA PUBBLICAZIONE"
			},
			"editorialSeries": {
				"code": "VARIA",
				"description": "VARIA"
			},
			"genre": "01",
			"printOnDemand": false,
			"publishOnFol": false,
			"returnRecirculation": false,
			"workingState": "validated",
			"dimensions": {
				"netWeight": 650.000,
				"height": 10.000,
				"width": 120.000,
				"length": 240.000
			},
			"registrationLimit": "2023-08-29T00:00:00+02:00",
			"commodityType": {
				"code": "99",
				"description": "non classificati"
			}
		}
	]
}

Features

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

  • title_search

altrimenti viene restituito 403 (Forbidden)