API

Configurazione dell'API

Per prima cosa, l'API deve essere attivata e configurata nel back-office.

Accedere alla configurazione:
Moduli > PrestaBlog > Configurazione > Strumenti > API

Impostazioni disponibili:

• Attivare l'API: interruttore principale. L'API non risponde ad alcuna richiesta finché è disattivata.
• Chiave API: fai clic su “Genera una nuova chiave”. La chiave viene mostrata una sola volta: copiala subito, poi non sarà più accessibile. Viene salvata solo la sua impronta crittografica (SHA-256). Se perdi la chiave, generane una nuova.
• Attivare automaticamente i nuovi articoli: determina se gli articoli creati tramite API vengono pubblicati immediatamente o salvati come bozze, quando la richiesta non specifica esplicitamente questo parametro.
• Limite di richieste: numero massimo di richieste al minuto per indirizzo IP (predefinito: 60).
• Sicurezza immagini: blocca il download di immagini da IP privati o interni. Consigliato per installazioni esposte su Internet.
• Dietro un proxy: da attivare se il tuo negozio è dietro Cloudflare, un reverse proxy o un CDN, per gestire correttamente l'IP del cliente.
• Livello di log: Nessuno disattiva i log. Sicurezza registra i tentativi di autenticazione falliti e i blocchi. Debug registra tutte le richieste (da usare temporaneamente per la diagnosi).
• Origini CORS consentite: solo se un'app web ospitata su un altro dominio deve chiamare l'API dal browser. Lascia vuoto nella maggior parte dei casi.

Permessi API

La sezione Permessi API ti consente di limitare in modo preciso ciò che la chiave API è autorizzata a fare. Ogni operazione può essere attivata o disattivata separatamente, sia per gli articoli che per le categorie.

• Consentire la creazione di articoli / categorie: consente le richieste POST per creare nuovi contenuti.
• Consentire la modifica di articoli / categorie: consente le richieste PUT per aggiornare contenuti esistenti.
• Consentire l'eliminazione di articoli / categorie: consente le richieste DELETE. Disattivalo se vuoi evitare eliminazioni accidentali da un agente IA o da uno script di terze parti.

Utilizzo tramite un agente IA (consigliato)

Non sei uno sviluppatore, o non vuoi scrivere codice? Il metodo più semplice è usare un agente IA come Claude tramite il protocollo MCP (Model Context Protocol). L'agente sa esattamente quali chiamate effettuare, gestisce l'autenticazione e comprende le tue istruzioni in linguaggio naturale.

1. Attivare l'API e generare la chiave

Nel back-office di PrestaBlog: Strumenti > API. Attiva l'API, fai clic su “Genera una nuova chiave” e copia la chiave mostrata: non sarà più accessibile in seguito.

2. Costruire l'URL di connessione MCP

L'URL di connessione segue questo formato:

https://prestablog-mcp.prestablog.workers.dev/mcp?key=YOUR_KEY&shop=https://your-shop.com

Sostituisci YOUR_KEY con la chiave generata e https://your-shop.com con l'URL del tuo negozio.

Da non confondere con l'“URL dell'API”, che è un URL diverso usato per le chiamate dirette.

3. Configurare con Claude

In Claude, fai clic su Customize in alto a sinistra, poi su Connectors,
in alto nella colonna che appare fai clic sul pulsante +, quindi su Add a custom connector.

Inserisci:

• Name: quello che vuoi (es: PrestaBlog API)
• URL: l'URL di connessione MCP costruito al punto 2

Conferma. Claude ora ha accesso al tuo blog e può creare, modificare ed eliminare articoli e categorie direttamente.

Esempi di ciò che puoi chiedere a Claude:

• “Crea un articolo sulle scarpe estive nella categoria Moda”
• “Elenca gli ultimi 10 articoli pubblicati”
• “Modifica il titolo dell'articolo 42”
• “Crea una nuova categoria Notizie con questa descrizione”
• “Elimina la categoria 5”

4. Configurare con Windsurf

In Windsurf, apri il pannello Cascade, fai clic su ... nell'angolo in alto a destra del pannello, quindi sull'icona MCPs (l'ultima icona in basso a destra del menu). Si apre una finestra di modifica. Aggiungi la configurazione seguente dopo aver generato correttamente l'URL (vedi il punto 2):

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

Salva. Cascade mostra 1 MCP in basso nel pannello, confermando che la connessione è attiva.

Esempi di ciò che puoi chiedere a Cascade:

• “Crea un articolo sulle scarpe estive nella categoria Moda”
• “Elenca gli ultimi 10 articoli pubblicati”
• “Modifica il titolo dell'articolo 42”
• “Crea una nuova categoria Notizie con questa descrizione”
• “Elimina la categoria 5”

Autenticazione (REST)

Ogni richiesta deve includere la chiave API in un header HTTP. Sono accettati due formati:

Authorization: Bearer YOUR_API_KEY

o

X-Api-Key: YOUR_API_KEY

Blocco automatico: dopo 5 tentativi di autenticazione falliti dallo stesso IP, l'IP viene bloccato per 1 ora. Questo intervallo è configurabile nelle impostazioni dell'API.

Articoli

Elencare gli articoli

GET /prestablog-api/articles

Restituisce l'elenco paginato degli articoli. Parametri disponibili: lang (ID lingua), page, per_page (max 100), active (1 = solo pubblicati), category (ID categoria), search (ricerca nel titolo), sort (date, title, id), order (asc, desc).

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

Dettaglio di un articolo

GET /prestablog-api/articles/{id}

Restituisce tutti i dati di un articolo: campi multilingua, categorie, prodotti associati, articoli correlati, indice.

curl -X GET "https://your-shop.com/prestablog-api/articles/18" \
  -H "Authorization: Bearer YOUR_KEY"

Creare un articolo

POST /prestablog-api/articles

Esempio minimo:

curl -X POST "https://your-shop.com/prestablog-api/articles" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "languages": {
      "1": {
        "title": "My article",
        "content": "<h2>Introduction</h2><p>Article content.</p>"
      }
    },
    "categories": [1],
    "active": true
  }'

Esempio completo con immagine, contenuto multilingua e metadati:

{
  "languages": {
    "1": {
      "title": "My article",
      "introduction": "Short text displayed in listings",
      "content": "<h2>Section</h2><p>Full HTML content.</p>",
      "meta_title": "My article - SEO Title",
      "meta_description": "Search engine description",
      "meta_keywords": "word1, word2",
      "link_rewrite": "my-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"
  }
}

Campi disponibili:

Modificare un articolo

PUT /prestablog-api/articles/{id}

Aggiornamento parziale: vengono modificati solo i campi presenti nella richiesta. I campi non inviati mantengono il valore attuale. Per le lingue, vengono aggiornate solo quelle incluse nel payload.

curl -X PUT "https://your-shop.com/prestablog-api/articles/18" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "active": false,
    "languages": {
      "1": {
        "title": "New title"
      }
    }
  }'

Eliminare un articolo

DELETE /prestablog-api/articles/{id}

Elimina l'articolo e tutti i dati associati: immagini (tutte le varianti), categorie, prodotti collegati, articoli correlati.

curl -X DELETE "https://your-shop.com/prestablog-api/articles/18" \
  -H "Authorization: Bearer YOUR_KEY"

Immagine di un articolo

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

Sono disponibili tre metodi in base al tuo contesto:

URL remoto (immagine ospitata online):

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

File locale (upload multipart):

curl -X POST "https://your-shop.com/prestablog-api/articles/18/image" \
  -H "Authorization: Bearer YOUR_KEY" \
  -F "file=@/path/to/image.jpg"

Base64 (fallback):

Nota: il base64 è molto voluminoso e può diventare difficile da gestire per immagini complesse. Quando possibile, preferisci l'upload tramite URL remoto.

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

Categorie

L'API consente di creare, consultare, modificare ed eliminare categorie, esattamente come per gli articoli.

Elencare le categorie

GET /prestablog-api/categories

Restituisce le categorie in forma di albero per impostazione predefinita. Usa flat=1 per una lista piatta, active=1 per ottenere solo le attive, lang per la lingua.

curl -X GET "https://your-shop.com/prestablog-api/categories?lang=1" \
  -H "Authorization: Bearer YOUR_KEY"

Dettaglio di una categoria

GET /prestablog-api/categories/{id}

Restituisce tutti i dati di una categoria: campi multilingua, numero di articoli, gruppi cliente associati.

Creare una categoria

POST /prestablog-api/categories

Esempio minimo:

curl -X POST "https://your-shop.com/prestablog-api/categories" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "languages": {
      "1": {
        "title": "News"
      }
    },
    "active": true
  }'

Esempio completo:

{
  "languages": {
    "1": {
      "title": "News",
      "description": "<p>All news from our shop.</p>",
      "meta_title": "News - SEO Title",
      "meta_description": "SEO description of the category",
      "meta_keywords": "news",
      "link_rewrite": "news"
    },
    "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/category.jpg"
  }
}

Campi disponibili:

Modificare una categoria

PUT /prestablog-api/categories/{id}

Aggiornamento parziale: vengono modificati solo i campi presenti nella richiesta.

curl -X PUT "https://your-shop.com/prestablog-api/categories/1" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "languages": {
      "1": {
        "title": "New category name",
        "description": "<p>New description.</p>"
      }
    }
  }'

Eliminare una categoria

DELETE /prestablog-api/categories/{id}

Elimina la categoria e tutti i dati associati: immagine, collegamenti con articoli, gruppi cliente.

curl -X DELETE "https://your-shop.com/prestablog-api/categories/1" \
  -H "Authorization: Bearer YOUR_KEY"

Immagine di una categoria

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

Stessi tre metodi degli articoli: URL remoto, file locale (multipart) o base64.

Nota: il base64 è molto voluminoso e può diventare difficile da gestire per immagini complesse. Quando possibile, preferisci l'upload tramite URL remoto.

curl -X POST "https://your-shop.com/prestablog-api/categories/1/image" \
  -H "Authorization: Bearer YOUR_KEY" \
  -F "file=@/path/to/category.jpg"

Autori

Gli autori sono in sola lettura tramite l'API. Devono essere creati nel back-office di PrestaBlog.

• GET /prestablog-api/authors - elencare tutti gli autori
• GET /prestablog-api/authors/{id} - dettaglio autore con biografie multilingua

curl -X GET "https://your-shop.com/prestablog-api/authors?lang=1" \
  -H "Authorization: Bearer YOUR_KEY"

Codici di errore

Tutte le risposte di errore seguono questo formato:

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "Messaggio di errore leggibile",
    "details": { "field": "languages.1.title" }
  }
}

Limite di richieste: quando viene superato, la risposta 429 include l'header Retry-After che indica quanti secondi attendere prima di riprovare. Ogni risposta include anche gli header X-RateLimit-Limit e X-RateLimit-Remaining.

Integrazione Python

Per gli sviluppatori Python, la libreria requests rende semplice interagire con l'API in poche righe.

pip install requests

import requests

BASE = "https://your-shop.com/prestablog-api"
KEY = "YOUR_KEY"
headers = {"Authorization": f"Bearer {KEY}"}

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

# Creare un articolo
r = requests.post(f"{BASE}/articles", headers=headers, json={
    "languages": {"1": {"title": "My article", "content": "<p>Content</p>"}},
    "categories": [1],
    "active": True
})
print(r.json())

# Caricare un'immagine da un file locale
with open("image.jpg", "rb") as f:
    r = requests.post(f"{BASE}/articles/18/image", headers=headers, files={"file": f})
print(r.json())