MetasBooks

Documentation de l'API de Collecte de Métadonnées du Livre

Aperçu

L'API de collecte de métadonnées du livre permet aux développeurs d'obtenir des informations détaillées sur un livre en utilisant son numéro ISBN (International Standard Book Number) au format EAN-13. Pour accéder à l'API, vous aurez besoin d'une clé d'API valide, qui doit être incluse dans chaque requête pour autoriser l'accès.

URL de l'API

L'URL de base pour accéder à l'API est :

https://metasbooks.fr/api/lookup_metas.php

Authentification

L'authentification à l'API est réalisée en utilisant une clé d'API qui doit être incluse dans l'url chaque requête. Voici comment ajouter la clé d'API dans l'url :

apikey=VotreCléAPI

Remplacez "VotreCléAPI" par la clé d'API fournie par MetasBooks lors de l'inscription à l'API.

Paramètres de la requête

L'API de collecte de métadonnées de livre prend en charge les paramètres suivants :

• ISBN (obligatoire): Le numéro ISBN au format EAN-13 du livre pour lequel vous souhaitez récupérer les métadonnées. L'ISBN est une chaîne alphanumérique unique qui identifie de manière unique un livre dans son format EAN-13 elle commence généralement par 978 ou 979 suivi de 9 digits d'identification de l'ouvrage et d'un digit qui correspond a une clé de contrôle. Ex: 978-123456789-0


• Le format de réponse souhaité (obligatoire):
  L'API propose quatre formats de réponse:
  
  Le format JSON (JavaScript Object Notation): vous devrez pour ce format indiquer dans l'url de votre requête:

  format=json

  
  Le format XML (Extensible Markup Language): vous devrez pour ce format indiquer dans l'url de votre requête:

  format=xml

  
  Le format ONIX (Online Information Exchange): conçu pour les métadonnées commerciales de livres. Vous devrez pour ce format indiquer dans l'url de votre requête:

  format=onix

  
  Le format MARC (Machine-Readable Cataloging): utilisé principalement par les bibliothèques pour le catalogage des ouvrages. Vous devrez pour ce format indiquer dans l'url de votre requête:

  format=marc

Exemple d'utilisation

Voici un exemple complet de requête pour récupérer les métadonnées d'un livre en utilisant l'ISBN :

GET https://metasbooks.fr/api/lookup_metas.php?ean=9782253934103&apikey=VotreCléAPI&format=json

Remplacez "9782253934103" par le numéro ISBN du livre que vous souhaitez interroger, et assurez-vous d'inclure votre clé d'API dans l'url de la requête.

Réponse de l'API

Si votre format de réponse souhaité est le JSON, l'API répondra avec un objet JSON contenant les métadonnées du livre correspondant à l'ISBN fourni. Voici un exemple de réponse JSON:

                {
                ean: "9782253934103",
                titre: "Tout le bleu du ciel",
                auteur: "Mélissa Da Costa",
                editeur: "LGF/Livre de Poche",
                collection: "Le Livre de Poche",
                format: "Poche",
                presentation: "Broché",
                date: "12 Février 2020",
                nbpages: "840",
                poids: "0",
                largeur: "11,0",
                hauteur: "17,8",
                epaisseur: "3,3",
                image_url: "https://metasbooks.fr/api/images/8b79924ea0336b012eb5b0d3b2522747-9782253934103.jpg",
                resume_final: "Petitesannonces.fr : Jeune homme de 26 ans,
                    condamné à une espérance de vie de deux ans par un Alzheimer précoce, souhaite prendre le large pour un ultime
                    voyage. Recherche compagnon(ne) pour partager avec moi ce dernier périple.\r\nÉmile a décidé de fuir l’hôpital, la
                    compassion de sa famille et de ses amis. À son propre étonnement, il reçoit une réponse à cette annonce. Trois jours
                    plus tard, devant le camping-car acheté secrètement, il retrouve Joanne, une jeune femme coiffée d’un grand chapeau
                    noir qui a pour seul bagage un sac à dos, et qui ne donne aucune explication sur sa présence.\r\nAinsi commence un
                    voyage stupéfiant de beauté. À chaque détour de ce périple naissent, à travers la rencontre avec les autres et la
                    découverte de soi, la joie, la peur, l’amitié, l’amour qui peu à peu percent la carapace de douleurs
                    d’Émile.\r\n\r\n<em>Un livre aux dialogues impeccables et aux personnages touchants
                    d’humanité. </em>\r\nPsychologies magazine.\r\n\r\n<em>Bouleversant.
                    </em>\r\nVersion femina.",
                note: null,
                num_serie: null,
                serie: null,
                classification: "Littérature générale > Romans > Romans
                    francophones",
                code_classification: "3435 > 3442 > 3443",
                prix: "10,90",
                reponse: "Trouvé",
                code_reponse: 1
                }
            

Si votre format de réponse souhaité est le XML, l'API renverra une réponse formatée en XML contenant les métadonnées du livre correspondant à l'ISBN fourni. Voici un exemple de réponse XML:

                    <nodes>
<ean>
9782253934103
</ean>
<titre>
Tout le bleu du ciel
</titre>
<auteur>
Mélissa Da
                        Costa
</auteur>
<editeur>
LGF/Livre de Poche
</editeur>
<collection>
Le Livre de Poche
</collection>
<format>
Poche
</format>
<presentation>
Broché
</presentation>
<date>
12 Février
                        2020
</date>
<nbpages>
840
</nbpages>
<poids>
0
</poids>
<largeur>
11,0
</largeur>
<hauteur>
17,8
</hauteur>
<epaisseur>
3,3
</epaisseur>
<image_url>
https://metasbooks.fr/api/images/8b79924ea0336b012eb5b0d3b2522747-9782253934103.jpg
</image_url>
<resume_final>
Petitesannonces.fr : Jeune homme de 26 ans, condamné à une espérance de vie de deux ans par un
                        Alzheimer précoce, souhaite prendre le large pour un ultime voyage. Recherche compagnon(ne) pour partager avec moi
                        ce dernier périple.
                        Émile a décidé de fuir l’hôpital, la compassion de sa famille et de ses amis. À son propre étonnement, il reçoit une
                        réponse à cette annonce. Trois jours plus tard, devant le camping-car acheté secrètement, il retrouve Joanne, une
                        jeune femme coiffée d’un grand chapeau noir qui a pour seul bagage un sac à dos, et qui ne donne aucune explication
                        sur sa présence.
                        Ainsi commence un voyage stupéfiant de beauté. À chaque détour de ce périple naissent, à travers la rencontre avec
                        les autres et la découverte de soi, la joie, la peur, l’amitié, l’amour qui peu à peu percent la carapace de
                        douleurs d’Émile.
                    
                        &lt;em&gt;Un livre aux dialogues impeccables et aux personnages touchants d’humanité. &lt;/em&gt;
                        Psychologies magazine.
                    
                        &lt;em&gt;Bouleversant. &lt;/em&gt;
                        Version femina.
</resume_final>
<note>
</note>
<num_serie>
</num_serie>
<serie>
</serie>
<classification>
Littérature générale > Romans > Romans
                        francophones
</classification>
<code_classification>
3435 > 3442 > 3443
</code_classification>
<prix>
10,90
</prix>
<reponse>
Trouvé
</reponse>
<code_reponse>
1
</code_reponse>
</nodes>
            

Codes d'erreur

L'API peut renvoyer les codes d'erreur HTTP standard en cas de problème, tels que 400 Bad Request, 401 Unauthorized, 404 Not Found, etc. Assurez-vous de traiter ces codes d'erreur correctement dans votre application.

Codes réponse

Outre ces différents code d'erreur, l'API émet un code réponse pour vous permettre d'identifier simplement les requêtes qui n'ont pas abouties.

En cas de succès:

                
JSON:
                reponse: "Trouvé",
                code_reponse: 1
                

                

                
XML:
                <reponse>
Trouvé
</reponse>
<code_reponse>
1
</code_reponse>
                

En cas d'echec:

                
JSON:
                reponse: "Non trouvé",
                code_reponse: 0
                

                

                
XML:
                <reponse>
Non trouvé
</reponse>
<code_reponse>
0
</code_reponse>
                

Un code d'erreur peut également s'afficher si le compte associé a la clé d'API fournie n'a pas suffisement de crédits:

            
JSON:
            reponse: "Crédits insufisants",
            code_reponse: 2
            

            

            
XML:
            <reponse>
Crédits insufisants
</reponse>
<code_reponse>
2
</code_reponse>
            

Verrification de l'état du compte

L'API propose également un end-point permettant de vérifier l'état de votre compte:

GET https://metasbooks.fr/api/check_account.php?apikey=VotreCléAPI

Ce endpoint renvoie un résultat JSON avec le status de votre compte et le nombre de crédits disponibles

            
JSON:
            crédits: 250,
            is_active: 1
            

Le compte est actif si is_active vaut 1 et inactif s'il vaut 0

Endpoint : Ajouter un Livre (v.Beta)

Cet endpoint permet d'ajouter une fiche produit dans la base de données. Il accepte une requête POST contenant les métadonnées du livre à ajouter.

URL

https://metasbooks.fr/api/add_book.php

Paramètres requis

Les paramètres doivent être envoyés sous forme de JSON dans le corps de la requête. Les champs obligatoires sont marqués par *.

• apikey (*) : Clé API valide de l'utilisateur.
• ean (*) : Code EAN unique du produit.
• titre (*) : Titre du livre.
• auteur (*) : Auteur du livre.
• editeur (*) : Nom de l'éditeur.
• format (*) : Format du livre (ex. "Broché").
• date_parrution (*) : Date de parution (YYYY-MM-DD).
• nbpages (*) : Nombre de pages.
• poids (*) : Poids en grammes.
• largeur (*) : Largeur en centimètres.
• hauteur (*) : Hauteur en centimètres.
• epaisseur (*) : Épaisseur en centimètres.
• url_image (*) : URL de l'image du produit.
• description (*) : Description du livre.
• code_classification (*) : Code de la classification.
• prix (*) : Prix en euros.

Réponse de l'API

Si la requête est réussie, l'API retourne un objet JSON avec un message de succès. En cas d'échec, un message d'erreur est retourné avec un code spécifique.

Réponse JSON

            {
                "status": "success",
                "message": "Fiche produit ajoutée avec succès."
            }
            

Codes d'erreur possibles

• 0 - Erreur de connexion à la base de données : Le serveur n'a pas pu se connecter à la base de données.
• 1 - Clé API non valide : La clé API fournie est introuvable.
• 2 - Champs obligatoires non renseignés : Un ou plusieurs champs requis sont manquants. La réponse inclura une liste des champs manquants.

  
                      {
                          "status": "echec",
                          "code_echec": 2,
                          "message": "Champs obligatoires non renseignés.",
                          "missing_fields": ["titre", "prix"]
                      }
                      

• 3 - Méthode HTTP non autorisée : Seules les requêtes POST sont autorisées.
• 4 - Erreur lors de l'insertion des données : Une erreur inattendue s'est produite.
• 5 - EAN déjà présent : L'EAN fourni existe déjà dans la base de données.
• 6 - Erreur lors de la conversion de l'image : L'image n'a pas pu être convertie ou stockée.
• 7 - Image vide ou introuvable : L'image fournie est invalide ou vide.
• 8 - Taille de l'image trop grande : L'image dépasse la limite de 2 Mo.
• 10 - Code classification invalide : Le code classification fourni n'existe pas.

Exemples d'appel

            curl -X POST https://metasbooks.fr/api/add_book.php \
            -H "Content-Type: application/json" \
            -d '{
                "apikey": "votre_cle_api",
                "ean": "9781234567890",
                "titre": "Exemple de Livre",
                "auteur": "Nom Auteur",
                "editeur": "Nom Editeur",
                "format": "Broché",
                "date_parrution": "2025-01-01",
                "nbpages": 200,
                "poids": 300,
                "largeur": 15.2,
                "hauteur": 22.5,
                "epaisseur": 2.1,
                "url_image": "https://example.com/image.jpg",
                "description": "Description du livre.",
                "code_classification": "1234",
                "prix": 19.99
            }'
            

Endpoint : Télécharger la Table des Catégories (v.Beta)

Cet endpoint permet de récupérer les données de la table Categories. Les résultats peuvent être retournés au format JSON ou XML, selon les besoins.

URL

https://metasbooks.fr/api/get_categories.php

Paramètres requis

• apikey (*) : Clé API valide de l'utilisateur pour authentifier la requête.
• format : Format de la réponse. Les valeurs possibles sont :
  • json (par défaut)
  • xml

Réponse de l'API

La réponse dépend du format spécifié. Voici des exemples pour chaque format :

Réponse JSON (par défaut)

        {
            "status": "success",
            "categories": [
                {
                    "id": "1",
                    "code": "1234",
                    "name": "Littérature",
                    "parent_id": null,
                    "level": "1"
                },
                {
                    "id": "2",
                    "code": "1235",
                    "name": "Romans",
                    "parent_id": "1",
                    "level": "2"
                }
            ]
        }
        

Réponse XML

        <categories>
            <category>
                <id>1</id>
                <code>1234</code>
                <name>Littérature</name>
                <parent_id/>
                <level>1</level>
            </category>
            <category>
                <id>2</id>
                <code>1235</code>
                <name>Romans</name>
                <parent_id>1</parent_id>
                <level>2</level>
            </category>
        </categories>
        

Codes d'erreur possibles

• 400 - Clé API manquante : La clé API n'a pas été fournie dans la requête.
• 401 - Clé API invalide : La clé API fournie est incorrecte ou n'existe pas.
• 405 - Méthode non autorisée : Une méthode HTTP autre que GET a été utilisée.
• 500 - Erreur interne : Une erreur inattendue s'est produite (par exemple, échec de la connexion à la base de données).

Notes importantes

• Le paramètre format est facultatif. Si aucun format n'est spécifié, la réponse sera en JSON.
• Les catégories sont triées par leur niveau (level) pour refléter la hiérarchie.

Exemples d'appel

Voici des exemples d'appels pour chaque format :

Requête JSON

        curl "https://metasbooks.fr/api/get_categories.php?apikey=votre_cle_api&format=json"
        

Requête XML

        curl "https://metasbooks.fr/api/get_categories.php?apikey=votre_cle_api&format=xml"