Passo a passo: atualizar uma página via API

Neste exemplo, atualiza uma página existente inteiramente através da API: adiciona um link, passa-o para o topo, altera o estilo dos botões, valida o rascunho e publica-o. Os comandos funcionam em qualquer shell com curl e jq.

#1. Criar uma chave de API

1. Abra «Callback e API» no painel
2. Clique em «+ Criar nova chave»
3. Escolha «Escrita» tanto em «Páginas» como em «Links» (inclui o acesso de leitura)
4. Clique em «Criar chave» e copie o segredo da chave
5. Copie o ID da chave a partir da lista

Guarde ambos os valores como variáveis de ambiente, não no script:

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

#2. Obter um token de acesso

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)

O token é válido durante 15 minutos. Se o seu script demorar mais, obtenha um novo pelo meio.

#3. Encontrar a página

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

Anote o id da página. Neste exemplo é 42:

PAGE_ID=42

#4. Adicionar um 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":"Promoção de outono","target_url_template":"https://shop.example.com/autumn","enabled":true}' \
  | jq -r .id)
echo "Novo link: $LINK_ID"

A API responde com HTTP 201 e o novo ID. Os links novos vão para o fim da lista. Se o limite de links do seu plano for atingido, recebe 409 link_limit_reached.

#5. Passar o link para o topo

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 enviar os IDs que devem passar para a frente. Todos os outros links mantêm a ordem atrás deles.

#6. Alterar o design no rascunho

theme_config é substituído por completo num PATCH. Por isso, leia primeiro o rascunho, altere só o valor pretendido e envie o objeto inteiro de volta:

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 aceita rounded, pill e square. Outros campos de theme_config incluem bg_color, text_color, button_color, button_text_color e background.

#7. Validar o rascunho

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

Se valid for false, issues lista os problemas. Corrija-os antes de publicar. Se o rascunho difere de todo da versão online, é indicado por GET /v1/pages/$PAGE_ID no campo has_unpublished_changes – se for false, pode saltar a publicação.

#8. Publicar

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

Os visitantes veem agora a nova versão – incluindo o novo link, a ordem e o design. Se tiver um webhook para page.published, este recebe agora uma entrega. Se o rascunho não puder ser publicado, a API responde com 409 draft_not_publishable e a lista em details.issues.

#9. Anular

Se não gostar do resultado, traga a versão anterior de volta para o rascunho e publique novamente:

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"

Em vez de um número de versão, pode indicar current: isto descarta todas as alterações do rascunho desde a última publicação. O restauro recupera o design, o modelo, o CSS personalizado, o SEO, os blocos e os links; o título, o handle e a visibilidade não têm versões.

#Erros frequentes

400 bad_request

Falta o cabeçalho Content-Type: application/json. Sem ele, curl -d envia outro tipo.

401 invalid_token

O token expirou ao fim de 15 minutos. Obtenha um novo.

403 insufficient_scope

Falta um scope à chave, por exemplo «Escrita» para links.

Design reposto de repente

theme_config foi enviado com apenas um campo e substituiu o tema inteiro. Envie novamente o tema completo ou use restore current para descartar todas as alterações do rascunho desde a última publicação.

Todos os códigos estão explicados em Formato de erro e códigos de erro, e todos os endpoints estão listados em Endpoints por área.