SEO Pages API

API REST per la gestione dei metadati SEO delle pagine CMS. Questi endpoint permettono di leggere e modificare programmaticamente i dati SEO delle pagine, utili per integrazioni con strumenti SEO esterni o automazioni.

---

Autenticazione

Tutte le richieste alle API SEO richiedono autenticazione tramite Bearer Token.

Header Richiesto

Authorization: Bearer {your-api-token}

Codici di Errore Autenticazione

Codice	Descrizione
401 Unauthorized	Token mancante o non valido
403 Forbidden	Token valido ma permessi insufficienti

---

Permessi Richiesti

Le API utilizzano gli stessi permessi del backend CMS:

Endpoint	Permesso Richiesto
GET Elenco pagine	Cms.pages.show
GET Singola pagina	Cms.pages.show
PATCH Aggiorna pagina	Cms.pages.update

---

Endpoint

Elenco Pagine Indicizzabili

Restituisce l'elenco paginato delle pagine CMS indicizzabili con i relativi dati SEO.

Vengono restituite solo le pagine che soddisfano tutti questi criteri:

• Attive (is_active = true)

• Pubblicate (data pubblicazione valida)

• Indicizzabili (meta_noindex = false)

Request

GET /api/v1/seo/pages
Content-Type: application/json
Authorization: Bearer {token}

Body Parameters

Parametro	Tipo	Obbligatorio	Default	Descrizione
locale	string	No	Locale progetto	Codice lingua (es: it, en, de)
offset	integer	No	0	Offset per paginazione
limit	integer	No	50	Numero massimo di risultati (max: 100)
parent_id	integer	No	—	ID del nodo padre per filtrare le sotto-pagine

Esempio Request

{
    "locale": "it",
    "offset": 0,
    "limit": 20,
    "parent_id": 44
}

Il parametro parent_id è opzionale. Se specificato, restituisce solo le sotto-pagine dirette del nodo padre indicato.

Response 200

{
    "data": [
        {
            "id": 123,
            "node_id": 45,
            "parent_id": 44,
            "name": "Chi Siamo",
            "locale_code": "it",
            "canonical": "https://example.com/it/chi-siamo",
            "is_canonical": true,
            "seo_title": "Chi Siamo | Example Company",
            "seo_h1": "La Nostra Storia",
            "meta_description": "Scopri la storia della nostra azienda...",
            "meta_keywords": "azienda, storia, team",
            "meta_noindex": false,
            "meta_nofollow": false,
            "sitemap_priority": "auto",
            "sitemap_frequency": "weekly",
            "alternative_langs": {
                "en": "https://example.com/en/about-us",
                "de": "https://example.com/de/uber-uns"
            },
            "updated_at": "2025-01-15T10:30:00+01:00",
            "published_from": "2024-06-01T00:00:00+02:00",
            "published_to": null
        }
    ],
    "meta": {
        "totalCount": 150,
        "totalPages": 8
    },
    "links": {
        "self": "/api/v1/seo/pages?limit=20&offset=0",
        "next": "/api/v1/seo/pages?limit=20&offset=20",
        "last": "/api/v1/seo/pages?limit=20&offset=140"
    }
}

---

Dettaglio Singola Pagina

Restituisce i dati SEO completi di una singola pagina identificata dal suo node_id.

Importante: L'endpoint accetta il node_id (ID della pagina/nodo), non l'ID della traduzione.

Request

GET /api/v1/seo/pages/{nodeId}
Content-Type: application/json
Authorization: Bearer {token}

Path Parameters

Parametro	Tipo	Descrizione
nodeId	integer	ID della pagina (PageModel.id)

Body Parameters

Parametro	Tipo	Obbligatorio	Default	Descrizione
locale	string	No	Locale progetto	Codice lingua della traduzione

Esempio Request

{
    "locale": "it"
}

Response 200

{
    "data": {
        "id": 123,
        "node_id": 45,
        "parent_id": 44,
        "name": "Chi Siamo",
        "locale_code": "it",
        "canonical": "https://example.com/it/chi-siamo",
        "is_canonical": true,
        "seo_title": "Chi Siamo | Example Company",
        "seo_h1": "La Nostra Storia",
        "meta_description": "Scopri la storia della nostra azienda...",
        "meta_keywords": "azienda, storia, team",
        "meta_noindex": false,
        "meta_nofollow": false,
        "sitemap_priority": "auto",
        "sitemap_frequency": "weekly",
        "alternative_langs": {
            "en": "https://example.com/en/about-us",
            "de": "https://example.com/de/uber-uns"
        },
        "updated_at": "2025-01-15T10:30:00+01:00",
        "published_from": "2024-06-01T00:00:00+02:00",
        "published_to": null
    }
}

Response 404

{
    "message": "Pagina non trovata"
}

---

Aggiorna Dati SEO

Aggiorna i campi SEO di una pagina specifica.

Comportamento dei campi:

• Campi non inviati → rimangono invariati

• Campi inviati con valore vuoto ("") → vengono svuotati (impostati a null)

• Campi inviati con nuovo valore → vengono aggiornati

Request

PATCH /api/v1/seo/pages/{nodeId}
Content-Type: application/json
Authorization: Bearer {token}

Path Parameters

Parametro	Tipo	Descrizione
nodeId	integer	ID della pagina (PageModel.id)

Body Parameters

Parametro	Tipo	Obbligatorio	Validazione	Descrizione
locale	string	Sì	max: 5 caratteri	Codice lingua della traduzione
seo_title	string	No	max: 255 caratteri	Titolo SEO personalizzato
seo_h1	string	No	max: 255 caratteri	Tag H1 personalizzato
meta_description	string	No	max: 500 caratteri	Meta description
meta_keywords	string	No	max: 255 caratteri	Meta keywords
meta_noindex	boolean	No	true / false	Flag noindex per i motori di ricerca
meta_nofollow	boolean	No	true / false	Flag nofollow per i link
sitemap_priority	string	No	auto, high, medium, low	Priorità nella sitemap
sitemap_frequency	string	No	never, yearly, monthly, weekly, daily, hourly, always	Frequenza di aggiornamento nella sitemap

Esempio Request - Aggiornamento Completo

{
    "locale": "it",
    "seo_title": "Nuovo Titolo SEO | Example",
    "seo_h1": "Nuovo Titolo H1",
    "meta_description": "Nuova meta description ottimizzata per i motori di ricerca",
    "meta_keywords": "keyword1, keyword2, keyword3",
    "meta_noindex": false,
    "meta_nofollow": false,
    "sitemap_priority": "high",
    "sitemap_frequency": "daily"
}

Esempio Request - Aggiornamento Parziale

{
    "locale": "it",
    "seo_title": "Solo il titolo cambia",
    "meta_description": "E la descrizione"
}

Esempio Request - Svuotamento Campo

{
    "locale": "it",
    "meta_keywords": ""
}

Response 200

{
    "data": {
        "id": 123,
        "node_id": 45,
        "parent_id": 44,
        "name": "Chi Siamo",
        "locale_code": "it",
        "canonical": "https://example.com/it/chi-siamo",
        "is_canonical": true,
        "seo_title": "Nuovo Titolo SEO | Example",
        "seo_h1": "Nuovo Titolo H1",
        "meta_description": "Nuova meta description ottimizzata...",
        "meta_keywords": "keyword1, keyword2, keyword3",
        "meta_noindex": false,
        "meta_nofollow": false,
        "sitemap_priority": "high",
        "sitemap_frequency": "daily",
        "alternative_langs": {
            "en": "https://example.com/en/about-us"
        },
        "updated_at": "2025-12-10T15:45:00+01:00",
        "published_from": "2024-06-01T00:00:00+02:00",
        "published_to": null
    },
    "message": "Dati SEO aggiornati con successo"
}

Response 404

{
    "message": "Pagina non trovata"
}

Response 422 - Errore di Validazione

{
    "message": "I dati forniti non sono validi.",
    "errors": {
        "sitemap_priority": [
            "La priorità sitemap deve essere: auto, high, medium o low"
        ],
        "seo_title": [
            "Il titolo SEO non può superare i 255 caratteri"
        ]
    }
}

---

Struttura Dati Response

Oggetto Pagina SEO

Campo	Tipo	Descrizione
id	integer	ID della traduzione (PageTransModel.id)
node_id	integer	ID della pagina/nodo (PageModel.id)
parent_id	integer | null	ID della pagina genitore, null se pagina root
name	string	Nome della pagina tradotto
locale_code	string	Codice lingua della traduzione
canonical	string	URL canonico completo della pagina
is_canonical	boolean	Indica se questa è la versione canonica
seo_title	string | null	Titolo SEO personalizzato
seo_h1	string | null	Tag H1 personalizzato
meta_description	string | null	Meta description
meta_keywords	string | null	Meta keywords
meta_noindex	boolean	Se true, la pagina non viene indicizzata
meta_nofollow	boolean	Se true, i link non vengono seguiti
sitemap_priority	string	Priorità sitemap: auto, high, medium, low
sitemap_frequency	string	Frequenza sitemap: never, yearly, monthly, weekly, daily, hourly, always
alternative_langs	object	Mappa delle versioni in altre lingue {locale: url}
updated_at	string	Data ultimo aggiornamento (ISO 8601)
published_from	string | null	Data inizio pubblicazione (ISO 8601)
published_to	string | null	Data fine pubblicazione (ISO 8601), null se illimitata

Oggetto Meta (Paginazione)

Campo	Tipo	Descrizione
totalCount	integer	Numero totale di pagine disponibili
totalPages	integer	Numero totale di pagine di risultati

Oggetto Links (Navigazione)

Campo	Tipo	Descrizione
self	string	URL della pagina corrente
first	string	URL della prima pagina (se applicabile)
prev	string	URL della pagina precedente (se applicabile)
next	string	URL della pagina successiva (se applicabile)
last	string	URL dell'ultima pagina (se applicabile)

---

Esempi di Utilizzo

cURL - Elenco Pagine

curl -X GET "https://api.example.com/api/v1/seo/pages" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"locale": "it", "limit": 10}'

cURL - Dettaglio Pagina

curl -X GET "https://api.example.com/api/v1/seo/pages/45" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"locale": "it"}'

cURL - Aggiornamento SEO

curl -X PATCH "https://api.example.com/api/v1/seo/pages/45" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "locale": "it",
    "seo_title": "Nuovo Titolo SEO",
    "meta_description": "Nuova descrizione ottimizzata"
  }'

JavaScript (Fetch API)

// Elenco pagine
const response = await fetch('/api/v1/seo/pages', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        locale: 'it',
        offset: 0,
        limit: 50
    })
});

const data = await response.json();
console.log(data.data); // Array di pagine
console.log(data.meta.totalCount); // Totale pagine

PHP (Guzzle)

use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => 'https://api.example.com',
    'headers' => [
        'Authorization' => 'Bearer YOUR_TOKEN',
        'Content-Type' => 'application/json'
    ]
]);

// Aggiornamento SEO
$response = $client->patch('/api/v1/seo/pages/45', [
    'json' => [
        'locale' => 'it',
        'seo_title' => 'Nuovo Titolo SEO',
        'sitemap_priority' => 'high'
    ]
]);

$result = json_decode($response->getBody(), true);

---

Codici di Stato HTTP

Codice	Descrizione
200 OK	Richiesta completata con successo
401 Unauthorized	Autenticazione richiesta o token non valido
403 Forbidden	Permessi insufficienti per l'operazione
404 Not Found	Pagina non trovata o non appartenente al progetto
422 Unprocessable Entity	Errore di validazione dei dati
500 Internal Server Error	Errore interno del server

---

Note Tecniche

Scope Progetto

Tutte le operazioni sono limitate al progetto corrente dell'utente autenticato. Non è possibile accedere o modificare pagine di altri progetti.

Lingue Alternative

Il campo alternative_langs contiene solo le lingue per cui esiste una traduzione pubblicata della pagina. Se una pagina non ha traduzioni in altre lingue, l'oggetto sarà vuoto {}.

Valori di Priorità Sitemap

Valore	Descrizione
auto	Priorità calcolata automaticamente in base alla profondità
high	Priorità alta (1.0)
medium	Priorità media (0.5)
low	Priorità bassa (0.3)

Valori di Frequenza Sitemap

Valore	Descrizione
always	Contenuto che cambia ad ogni accesso
hourly	Aggiornamento orario
daily	Aggiornamento giornaliero
weekly	Aggiornamento settimanale (default)
monthly	Aggiornamento mensile
yearly	Aggiornamento annuale
never	Contenuto archiviato, mai modificato

---

Limiti e Rate Limiting

Parametro	Limite
Risultati per pagina (max)	100
Risultati per pagina (default)	50

Se viene richiesto un limit superiore a 100, il sistema lo ridurrà automaticamente a 100.