Passo per passo: aggiornare una pagina via API

In questo esempio aggiorni una pagina esistente interamente tramite l’API: aggiungi un link, lo sposti in cima, cambi lo stile dei pulsanti, validi la bozza e la pubblichi. I comandi funzionano in qualsiasi shell con curl e jq.

#1. Creare una chiave API

1. Apri «Callback e API» nella dashboard
2. Clicca su «+ Crea nuova chiave»
3. Scegli «Scrittura» sia per «Pagine» sia per «Link» (include l’accesso in lettura)
4. Clicca su «Crea chiave» e copia il secret della chiave
5. Copia l’ID della chiave dall’elenco

Salva entrambi i valori come variabili d’ambiente, non nello script:

export LH_KEY_ID="6F668EA6598B0692"
export LH_KEY_SECRET="lt_…"
export API="https://dock.at-harbor.com"

#2. Ottenere un token di accesso

LH_TOKEN=$(curl -sS -X POST "$API/v1/token" \
  -H "Content-Type: application/json" \
  -d "{\"key_id\":\"$LH_KEY_ID\",\"key_secret\":\"$LH_KEY_SECRET\"}" \
  | jq -r .token)

Il token è valido per 15 minuti. Se il tuo script dura di più, richiedine uno nuovo nel frattempo.

#3. Trovare la pagina

curl -sS "$API/v1/pages" -H "Authorization: Bearer $LH_TOKEN" \
  | jq '.items[] | {id, handle, title, status, current_version}'

Annota l’id della pagina. In questo esempio è 42:

PAGE_ID=42

#4. Aggiungere un link

LINK_ID=$(curl -sS -X POST "$API/v1/pages/$PAGE_ID/links" \
  -H "Authorization: Bearer $LH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Autumn sale","target_url_template":"https://shop.example.com/autumn","enabled":true}' \
  | jq -r .id)
echo "New link: $LINK_ID"

L’API risponde con HTTP 201 e il nuovo ID. I nuovi link finiscono in fondo all’elenco. Se è raggiunto il limite di link del tuo piano, ricevi 409 link_limit_reached.

#5. Spostare il link in cima

curl -sS -X POST "$API/v1/pages/$PAGE_ID/links/reorder" \
  -H "Authorization: Bearer $LH_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"order\":[$LINK_ID]}"

Basta inviare gli ID che devono passare in testa. Tutti gli altri link mantengono il loro ordine dopo di essi.

#6. Cambiare il design nella bozza

Con PATCH, theme_config viene sostituito completamente. Quindi leggi prima la bozza, cambi solo il valore che ti interessa e rimandi l’intero oggetto:

THEME=$(curl -sS "$API/v1/pages/$PAGE_ID/draft" -H "Authorization: Bearer $LH_TOKEN" \
  | jq -c '(.theme_config // {}) | .button_style = "pill"')

curl -sS -X PATCH "$API/v1/pages/$PAGE_ID/draft" \
  -H "Authorization: Bearer $LH_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"theme_config\":$THEME}"

button_style accetta rounded, pill e square. Altri campi di theme_config sono, per esempio, bg_color, text_color, button_color, button_text_color e background.

#7. Validare la bozza

curl -sS "$API/v1/pages/$PAGE_ID/draft/validate" -H "Authorization: Bearer $LH_TOKEN"
# → {"ok":true,"valid":true,"issues":[]}

Se valid è false, issues elenca i problemi. Risolvili prima di pubblicare. Se la bozza differisce davvero dalla versione live lo indica GET /v1/pages/$PAGE_ID nel campo has_unpublished_changes – se è false, puoi saltare la pubblicazione.

#8. Pubblicare

curl -sS -X POST "$API/v1/pages/$PAGE_ID/publish" -H "Authorization: Bearer $LH_TOKEN"
# → {"ok":true,"version":8,"checksum":"…"}

Ora i visitatori vedono la nuova versione – compresi il nuovo link, l’ordine e il design. Se hai un webhook per page.published, riceve ora una consegna. Se la bozza non può essere pubblicata, l’API risponde con 409 draft_not_publishable e l’elenco in details.issues.

#9. Annullare

Se il risultato non ti piace, riporta la versione precedente nella bozza e pubblica di nuovo:

curl -sS -X POST "$API/v1/pages/$PAGE_ID/versions/7/restore" -H "Authorization: Bearer $LH_TOKEN"
curl -sS -X POST "$API/v1/pages/$PAGE_ID/publish" -H "Authorization: Bearer $LH_TOKEN"

Invece di un numero di versione puoi passare current: così scarti tutte le modifiche della bozza dall’ultima pubblicazione. Il ripristino riporta design, modello, CSS personalizzato, SEO, blocchi e link; titolo, handle e visibilità non sono soggetti a versioni.

#Errori frequenti

400 bad_request

Manca l’header Content-Type: application/json. Senza di esso, curl -d invia un tipo diverso.

401 invalid_token

Il token è scaduto dopo 15 minuti. Richiedine uno nuovo.

403 insufficient_scope

Alla chiave manca uno scope, per esempio «Scrittura» per i link.

Design improvvisamente reimpostato

theme_config è stato inviato con un solo campo e ha sostituito l’intero tema. Invia di nuovo il tema completo, oppure usa restore current per scartare tutte le modifiche della bozza dall’ultima pubblicazione.

Tutti i codici sono spiegati in Formato degli errori e codici di errore API, e tutti gli endpoint sono elencati in Endpoint dell’API per area.