API

Configuration de l'API

Avant toute chose, l'API doit être activée et configurée dans le back-office.

Accéder à la configuration :
Modules > PrestaBlog > Configuration > Outils > API

Paramètres disponibles :

• Activer l'API : interrupteur principal. L'API ne répond à aucune requête tant qu'il est désactivé.
• Clé API : cliquez sur « Générer une nouvelle clé ». La clé s'affiche une seule fois - copiez-la immédiatement, elle ne sera plus accessible ensuite. Seule son empreinte cryptographique (SHA-256) est stockée. Si vous perdez la clé, générez-en une nouvelle.
• Activer automatiquement les nouveaux articles : détermine si les articles créés via l'API sont publiés immédiatement ou enregistrés comme brouillons, lorsque la requête ne précise pas explicitement ce paramètre.
• Limite de requêtes : nombre maximal de requêtes par minute par adresse IP (défaut : 60).
• Sécurité image : bloque le téléchargement d'images depuis des adresses IP privées ou internes. Recommandé pour les installations exposées sur Internet.
• Derrière un proxy : à activer si votre boutique est derrière Cloudflare, un reverse proxy ou un CDN, pour une gestion correcte de l'IP cliente.
• Niveau de log : Aucun désactive les logs. Sécurité enregistre les tentatives d'authentification échouées et les blocages. Debug enregistre toutes les requêtes (à utiliser temporairement pour le diagnostic).
• Origines CORS autorisées : uniquement si une application web hébergée sur un autre domaine doit appeler l'API depuis un navigateur. Laissez vide dans la grande majorité des cas.

Permissions API

La section Permissions API vous permet de restreindre précisément ce que la clé API est autorisée à faire. Chaque opération peut être activée ou désactivée indépendamment, aussi bien pour les articles que pour les catégories.

• Autoriser la création d'articles / de catégories : autorise les requêtes POST pour créer de nouveaux contenus.
• Autoriser la modification d'articles / de catégories : autorise les requêtes PUT pour mettre à jour des contenus existants.
• Autoriser la suppression d'articles / de catégories : autorise les requêtes DELETE. À désactiver si vous souhaitez empêcher toute suppression accidentelle depuis un agent IA ou un script tiers.

Utilisation via un agent IA (recommandé)

Vous n'êtes pas développeur, ou vous ne souhaitez pas écrire de code ? La méthode la plus simple est d'utiliser un agent IA comme Claude via le protocole MCP (Model Context Protocol). L'agent sait exactement quels appels effectuer, gère l'authentification et comprend vos instructions en langage naturel.

1. Activer l'API et générer votre clé

Dans le back-office PrestaBlog : Outils > API. Activez l'API, cliquez sur « Générer une nouvelle clé », et copiez la clé affichée - elle ne sera plus accessible ensuite.

2. Construire votre URL de connexion MCP

L'URL de connexion suit ce format :

https://prestablog-mcp.prestablog.workers.dev/mcp?key=VOTRE_CLE&shop=https://votre-boutique.com

Remplacez VOTRE_CLE par la clé que vous avez générée et https://votre-boutique.com par l'URL de votre boutique.

A ne pas confondre avec "URL de l'API" qui est une autre URL utilisé pour les appels directes.

3. Configurer avec Claude

Dans Claude, cliquez en haut à gauche sur Customize, puis Connecteurs,
en haut de la colonne qui vient d'apparaitre cliquez sur le bouton +, puis Ajouter un connecteur personnalisé.

Renseignez :

• Nom : ce que vous souhaitez (ex: PrestaBlog API)
• URL : votre URL de connexion construite à l'étape 2

Validez. Claude a maintenant accès à votre blog et peut créer, modifier, supprimer vos articles et catégories directement.

Exemples de ce que vous pouvez demander à Claude :

• « Crée un article sur les chaussures d'été dans la catégorie Mode »
• « Liste les 10 derniers articles publiés »
• « Modifie le titre de l'article 42 »
• « Crée une nouvelle catégorie Actualités avec cette description »
• « Supprime la catégorie 5 »

4. Configurer avec Windsurf

Dans Windsurf, ouvrez le panneau Cascade, cliquez sur ... en haut à droite du panneau, puis sur l'icône MCPs (dernière icône en bas à droite du menu qui apparaît). Une fenêtre d'édition s'ouvre. Ajoutez la configuration suivante après avoir généré l'URL correctement (voir l'étape 2) :

{
  "mcpServers": {
    "prestablog": {
      "serverUrl": "https://prestablog-mcp.prestablog.workers.dev/mcp?key=VOTRE_CLE&shop=https://votre-boutique.com"
    }
  }
}

Sauvegardez. Cascade affiche 1 MCP en bas du panneau, confirmant que la connexion est active.

Exemples de ce que vous pouvez demander à Cascade :

• « Crée un article sur les chaussures d'été dans la catégorie Mode »
• « Liste les 10 derniers articles publiés »
• « Modifie le titre de l'article 42 »
• « Crée une nouvelle catégorie Actualités avec cette description »
• « Supprime la catégorie 5 »

Authentification (REST)

Chaque requête doit inclure la clé API dans un header HTTP. Deux formats sont acceptés :

Authorization: Bearer VOTRE_CLE_API

ou

X-Api-Key: VOTRE_CLE_API

Blocage automatique : après 5 tentatives d'authentification échouées depuis la même IP, celle-ci est bloquée pendant 1 heure. Ce délai est configurable dans les paramètres de l'API.

Articles

Lister les articles

GET /prestablog-api/articles

Retourne la liste paginée des articles. Paramètres disponibles : lang (ID de langue), page, per_page (max 100), active (1 = publiés uniquement), category (ID de catégorie), search (recherche dans le titre), sort (date, title, id), order (asc, desc).

curl -X GET "https://votre-boutique.com/prestablog-api/articles?lang=1&page=1&per_page=10" \
  -H "Authorization: Bearer VOTRE_CLE"

Détail d'un article

GET /prestablog-api/articles/{id}

Retourne toutes les données d'un article : champs multilingues, catégories, produits associés, articles liés, table des matières.

curl -X GET "https://votre-boutique.com/prestablog-api/articles/18" \
  -H "Authorization: Bearer VOTRE_CLE"

Créer un article

POST /prestablog-api/articles

Exemple minimal :

curl -X POST "https://votre-boutique.com/prestablog-api/articles" \
  -H "Authorization: Bearer VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{
    "languages": {
      "1": {
        "title": "Mon article",
        "content": "<h2>Introduction</h2><p>Contenu de l article.</p>"
      }
    },
    "categories": [1],
    "active": true
  }'

Exemple complet avec image, multilingue et métadonnées :

{
  "languages": {
    "1": {
      "title": "Mon article",
      "introduction": "Texte court affiché dans les listes",
      "content": "<h2>Section</h2><p>Contenu HTML complet.</p>",
      "meta_title": "Mon article - Titre SEO",
      "meta_description": "Description pour les moteurs de recherche",
      "meta_keywords": "mot1, mot2",
      "link_rewrite": "mon-article"
    },
    "2": {
      "title": "My article",
      "introduction": "Short text displayed in listings",
      "content": "<h2>Section</h2><p>Full HTML content.</p>"
    }
  },
  "categories": [2, 5],
  "active": true,
  "date": "2026-06-15 09:00:00",
  "enable_toc": true,
  "author_id": 1,
  "image": {
    "url": "https://example.com/image.jpg"
  }
}

Champs disponibles :

Modifier un article

PUT /prestablog-api/articles/{id}

Mise à jour partielle : seuls les champs présents dans la requête sont modifiés. Les champs non transmis conservent leur valeur actuelle. Pour les langues, seules celles incluses dans le payload sont mises à jour.

curl -X PUT "https://votre-boutique.com/prestablog-api/articles/18" \
  -H "Authorization: Bearer VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{
    "active": false,
    "languages": {
      "1": {
        "title": "Nouveau titre"
      }
    }
  }'

Supprimer un article

DELETE /prestablog-api/articles/{id}

Supprime l'article et toutes ses données associées : images (toutes les variantes), catégories, produits liés, articles liés.

curl -X DELETE "https://votre-boutique.com/prestablog-api/articles/18" \
  -H "Authorization: Bearer VOTRE_CLE"

Image d'un article

POST /prestablog-api/articles/{id}/image

Trois méthodes disponibles selon votre contexte :

Via URL distante (l'image est hébergée en ligne) :

curl -X POST "https://votre-boutique.com/prestablog-api/articles/18/image" \
  -H "Authorization: Bearer VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/image.jpg"}'

Via fichier local (upload multipart) :

curl -X POST "https://votre-boutique.com/prestablog-api/articles/18/image" \
  -H "Authorization: Bearer VOTRE_CLE" \
  -F "file=@/chemin/vers/image.jpg"

Via base64 (fallback) :

Note : le base64 est très volumineux et peut devenir difficile à manipuler pour des images complexes. Quand c'est possible, privilégiez l'upload via URL distante.

curl -X POST "https://votre-boutique.com/prestablog-api/articles/18/image" \
  -H "Authorization: Bearer VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{"base64": "/9j/4AAQSkZJRg...", "filename": "photo.jpg"}'

Catégories

L'API permet de créer, consulter, modifier et supprimer des catégories, exactement comme pour les articles.

Lister les catégories

GET /prestablog-api/categories

Retourne les catégories sous forme d'arbre par défaut. Paramètre flat=1 pour une liste plate, active=1 pour les actives uniquement, lang pour la langue.

curl -X GET "https://votre-boutique.com/prestablog-api/categories?lang=1" \
  -H "Authorization: Bearer VOTRE_CLE"

Détail d'une catégorie

GET /prestablog-api/categories/{id}

Retourne toutes les données d'une catégorie : champs multilingues, nombre d'articles, groupes de clients associés.

Créer une catégorie

POST /prestablog-api/categories

Exemple minimal :

curl -X POST "https://votre-boutique.com/prestablog-api/categories" \
  -H "Authorization: Bearer VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{
    "languages": {
      "1": {
        "title": "Actualités"
      }
    },
    "active": true
  }'

Exemple complet :

{
  "languages": {
    "1": {
      "title": "Actualités",
      "description": "<p>Toutes les actualités de notre boutique.</p>",
      "meta_title": "Actualités - Titre SEO",
      "meta_description": "Description SEO de la catégorie",
      "meta_keywords": "actualités, news",
      "link_rewrite": "actualites"
    },
    "2": {
      "title": "News",
      "description": "<p>All the latest news from our shop.</p>",
      "link_rewrite": "news"
    }
  },
  "parent": 0,
  "position": 1,
  "active": true,
  "image": {
    "url": "https://example.com/categorie.jpg"
  }
}

Champs disponibles :

Modifier une catégorie

PUT /prestablog-api/categories/{id}

Mise à jour partielle : seuls les champs présents dans la requête sont modifiés.

curl -X PUT "https://votre-boutique.com/prestablog-api/categories/1" \
  -H "Authorization: Bearer VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{
    "languages": {
      "1": {
        "title": "Nouveau nom de catégorie",
        "description": "<p>Nouvelle description.</p>"
      }
    }
  }'

Supprimer une catégorie

DELETE /prestablog-api/categories/{id}

Supprime la catégorie et toutes ses données associées : image, liens avec les articles, groupes de clients.

curl -X DELETE "https://votre-boutique.com/prestablog-api/categories/1" \
  -H "Authorization: Bearer VOTRE_CLE"

Image d'une catégorie

POST /prestablog-api/categories/{id}/image

Mêmes trois méthodes que pour les articles : URL distante, fichier local (multipart), ou base64.

Note : le base64 est très volumineux et peut devenir difficile à manipuler pour des images complexes. Quand c'est possible, privilégiez l'upload via URL distante.

curl -X POST "https://votre-boutique.com/prestablog-api/categories/1/image" \
  -H "Authorization: Bearer VOTRE_CLE" \
  -F "file=@/chemin/vers/categorie.jpg"

Auteurs

Les auteurs sont en lecture seule via l'API. Ils doivent être créés dans le back-office PrestaBlog.

• GET /prestablog-api/authors - liste de tous les auteurs
• GET /prestablog-api/authors/{id} - détail d'un auteur avec biographies multilingues

curl -X GET "https://votre-boutique.com/prestablog-api/authors?lang=1" \
  -H "Authorization: Bearer VOTRE_CLE"

Codes d'erreur

Toutes les réponses d'erreur suivent ce format :

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "Description lisible de l'erreur",
    "details": { "field": "languages.1.title" }
  }
}

Limite de débit : en cas de dépassement, la réponse 429 inclut un header Retry-After indiquant le nombre de secondes à attendre avant de réessayer. Chaque réponse inclut également les headers X-RateLimit-Limit et X-RateLimit-Remaining.

Intégration Python

Pour les développeurs Python, la bibliothèque requests permet d'interagir avec l'API en quelques lignes.

pip install requests

import requests

BASE = "https://votre-boutique.com/prestablog-api"
KEY = "VOTRE_CLE"
headers = {"Authorization": f"Bearer {KEY}"}

# Lister les articles
r = requests.get(f"{BASE}/articles", headers=headers, params={"lang": 1, "per_page": 10})
print(r.json())

# Créer un article
r = requests.post(f"{BASE}/articles", headers=headers, json={
    "languages": {"1": {"title": "Mon article", "content": "<p>Contenu</p>"}},
    "categories": [1],
    "active": True
})
print(r.json())

# Upload d'image depuis un fichier local
with open("image.jpg", "rb") as f:
    r = requests.post(f"{BASE}/articles/18/image", headers=headers, files={"file": f})
print(r.json())