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
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:
|
|
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:
altrimenti viene restituito 403 (Forbidden)
|