Pas à pas : mettre à jour une page via l’API

Dans cet exemple, vous mettez à jour une page existante entièrement via l’API : vous ajoutez un lien, le placez en tête, changez le style des boutons, validez le brouillon et le publiez. Les commandes fonctionnent dans n’importe quel shell avec curl et jq.

#1. Créer une clé API

1. Ouvrez « Callback et API » dans le tableau de bord
2. Cliquez sur « + Créer une nouvelle clé »
3. Choisissez « Écriture » pour « Pages » et pour « Liens » (cela inclut l’accès en lecture)
4. Cliquez sur « Créer la clé » et copiez le secret de la clé
5. Copiez l’ID de la clé depuis la liste

Enregistrez les deux valeurs comme variables d’environnement, pas dans le script :

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

#2. Obtenir un jeton d’accès

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)

Le jeton est valable 15 minutes. Si votre script dure plus longtemps, récupérez-en un nouveau entre-temps.

#3. Trouver la page

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

Notez l’id de la page. Dans cet exemple, c’est 42 :

PAGE_ID=42

#4. Ajouter un lien

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

L’API répond avec HTTP 201 et le nouvel ID. Les nouveaux liens arrivent à la fin de la liste. Si la limite de liens de votre offre est atteinte, vous recevez 409 link_limit_reached.

#5. Placer le lien en tête

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]}"

Il suffit d’envoyer les ID qui doivent passer en tête. Tous les autres liens gardent leur ordre derrière eux.

#6. Modifier le design dans le brouillon

theme_config est entièrement remplacé lors d’un PATCH. Lisez donc d’abord le brouillon, modifiez uniquement la valeur voulue et renvoyez l’objet complet :

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 accepte rounded, pill et square. D’autres champs de theme_config sont notamment bg_color, text_color, button_color, button_text_color et background.

#7. Valider le brouillon

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

Si valid vaut false, issues liste les problèmes. Corrigez-les avant de publier. Pour savoir si le brouillon diffère de la version en ligne, regardez le champ has_unpublished_changes de GET /v1/pages/$PAGE_ID – s’il vaut false, vous pouvez vous passer de la publication.

#8. Publier

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

Les visiteurs voient maintenant la nouvelle version – avec le nouveau lien, l’ordre et le design. Si vous avez un webhook pour page.published, il reçoit maintenant une livraison. Si le brouillon ne peut pas être publié, l’API répond 409 draft_not_publishable avec la liste dans details.issues.

#9. Annuler

Si le résultat ne vous plaît pas, ramenez la version précédente dans le brouillon et publiez à nouveau :

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"

Au lieu d’un numéro de version, vous pouvez passer current : cela abandonne toutes les modifications du brouillon depuis la dernière publication. La restauration ramène le design, le modèle, le CSS personnalisé, le SEO, les blocs et les liens ; le titre, le handle et la visibilité ne sont pas versionnés.

#Erreurs fréquentes

400 bad_request

L’en-tête Content-Type: application/json manque. Sans lui, curl -d envoie un autre type.

401 invalid_token

Le jeton a expiré au bout de 15 minutes. Récupérez-en un nouveau.

403 insufficient_scope

Il manque une portée à la clé, par exemple « Écriture » pour les liens.

Design soudain réinitialisé

theme_config a été envoyé avec un seul champ et a remplacé tout le thème. Renvoyez le thème complet, ou utilisez restore current pour abandonner toutes les modifications du brouillon depuis la dernière publication.

Tous les codes sont expliqués dans Format et codes d’erreur, et tous les endpoints sont listés dans Endpoints par domaine.