Paso a paso: actualizar una página mediante la API

En este ejemplo actualizas una página existente solo con la API: añades un enlace, lo subes arriba del todo, cambias el estilo de los botones, validas el borrador y lo publicas. Los comandos funcionan en cualquier shell con curl y jq.

#1. Crear una clave de API

1. Abre «Callback y API» en el panel
2. Haz clic en «+ Crear nueva clave»
3. Elige «Escritura» tanto para «Páginas» como para «Enlaces» (incluye el acceso de lectura)
4. Haz clic en «Crear clave» y copia el secreto de la clave
5. Copia el ID de la clave de la lista

Guarda ambos valores como variables de entorno, no en el script:

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

#2. Obtener un token de acceso

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)

El token es válido durante 15 minutos. Si tu script tarda más, pide uno nuevo entre medias.

#3. Encontrar la página

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

Apunta el id de la página. En este ejemplo es 42:

PAGE_ID=42

#4. Añadir un enlace

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

La API responde con HTTP 201 y el nuevo ID. Los enlaces nuevos van al final de la lista. Si se alcanza el límite de enlaces de tu plan, recibes 409 link_limit_reached.

#5. Subir el enlace arriba del todo

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 con enviar los ID que deben pasar al principio. Todos los demás enlaces mantienen su orden detrás.

#6. Cambiar el diseño en el borrador

theme_config se sustituye por completo con un PATCH. Por eso lees primero el borrador, cambias solo el valor que quieres y devuelves el objeto entero:

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 acepta rounded, pill y square. Otros campos de theme_config son, por ejemplo, bg_color, text_color, button_color, button_text_color y background.

#7. Validar el borrador

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

Si valid es false, issues enumera los problemas. Corrígelos antes de publicar. Si el borrador difiere o no de la versión publicada lo indica GET /v1/pages/$PAGE_ID en el campo has_unpublished_changes; si es false, puedes saltarte la publicación.

#8. Publicar

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

Ahora los visitantes ven la nueva versión, con el nuevo enlace, el orden y el diseño. Si tienes un webhook para page.published, ahora recibe una entrega. Si el borrador no se puede publicar, la API responde con 409 draft_not_publishable y la lista en details.issues.

#9. Deshacer

Si no te gusta el resultado, vuelve a llevar la versión anterior al borrador y publica de nuevo:

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"

En lugar de un número de versión puedes pasar current: así descartas todos los cambios del borrador desde la última publicación. La restauración recupera el diseño, la plantilla, el CSS personalizado, el SEO, los bloques y los enlaces; el título, el handle y la visibilidad no tienen versiones.

#Errores frecuentes

400 bad_request

Falta el encabezado Content-Type: application/json. Sin él, curl -d envía otro tipo.

401 invalid_token

El token caducó a los 15 minutos. Pide uno nuevo.

403 insufficient_scope

A la clave le falta un scope, por ejemplo «Escritura» para los enlaces.

El diseño se ha restablecido de repente

Se envió theme_config con un solo campo y sustituyó todo el tema. Vuelve a enviar el tema completo, o usa restore current para descartar todos los cambios del borrador desde la última publicación.

Todos los códigos se explican en Formato y códigos de error, y todos los endpoints están en Endpoints por área.