A API do LinkHarbor num relance

A API REST permite controlar o LinkHarbor a partir dos seus próprios programas: criar páginas e links, editar e publicar rascunhos, gerar links curtos ou levar as estatísticas para os seus próprios relatórios. Este artigo destina-se a programadores e explica as regras básicas que se aplicam a todos os endpoints.

#Que caminho escolher?

#URL base e versões

URL base

https://dock.at-harbor.com – todos os endpoints do produto estão em /v1, por exemplo https://dock.at-harbor.com/v1/pages.

Versão

De momento existe apenas a versão v1. O número da versão faz parte do caminho.

Protocolo

Apenas HTTPS.

OpenAPI

A descrição legível por máquina (OpenAPI 3.1) está em https://dock.at-harbor.com/openapi.yaml. Pode carregá-la no Postman, no Insomnia ou num gerador de código.

#Testar na sandbox

Para desenvolvimento e testes existe uma sandbox à parte. Comporta-se como a API real, mas está totalmente separada dela: contas próprias, dados próprios, e nada disso chega ao seu espaço de trabalho real.

API

https://drydock.at-harbor.com, com os mesmos caminhos indicados acima, por exemplo https://drydock.at-harbor.com/v1/pages.

Painel

https://sandbox-deck.linkharbor.com, por exemplo para criar chaves de API.

Páginas

As páginas publicadas aparecem em https://<handle>.sandbox.linkharbor.com.

Conta

A sua conta LinkHarbor real não funciona aí. Crie uma conta de sandbox separada.

A sandbox não envia e-mails. Se se registar através da API (POST /v1/auth/register), o código de verificação vem diretamente na resposta, no campo _dev_verification. O mesmo se aplica à reposição da palavra-passe e à alteração do e-mail. Este campo só existe na sandbox, por isso não dependa dele no seu código.

• As notificações push estão desligadas
• Os pagamentos passam pelo modo de teste do Stripe, sem movimento de dinheiro real
• Os rate limits são cerca de um terço dos valores reais, e as contas novas estão limitadas a 5 por hora e endereço IP
• No dia 1 de cada mês, às 3:00 UTC, a sandbox é apagada por completo, e a seguir todas as contas e dados desaparecem
• Todas as respostas trazem o cabeçalho X-Environment: sandbox

#Autenticação em resumo

1. Como proprietário ou admin, crie no painel, em «Callback e API», uma chave de API com os scopes de que precisa (a partir do Creator Pro)
2. Troque o ID e o segredo da chave por um token de acesso através de POST /v1/token
3. Envie o token em cada pedido no cabeçalho Authorization: Bearer …
4. Obtenha um novo token ao fim de 15 minutos

Todos os pormenores estão em Chaves de API e tokens de acesso, as permissões em Scopes.

#Pedidos e respostas

Formato

Pedidos e respostas são JSON em UTF-8. Os carregamentos de ficheiros usam também multipart/form-data.

Content-Type

Envie o cabeçalho Content-Type: application/json em todos os pedidos com corpo. Qualquer outro tipo é recusado com 400 bad_request – incluindo o que o curl define automaticamente para -d quando este cabeçalho falta.

Campos desconhecidos

Os campos que um endpoint não conhece levam a 422 validation_failed. A resposta indica os campos desconhecidos.

JSON inválido

Leva a 400 invalid_json.

Tamanho

Consoante o endpoint, um corpo pode ter no máximo 64 KB, 1 MB ou 2 MB, e um carregamento de ficheiro 10 MB. Se for maior, a API responde com 413 request_too_large. Todos os limites estão em Rate limits.

Listas

Vêm como objeto com o campo items, por exemplo {"items":[…]}.

Criar

Responde com HTTP 201 e o novo ID, por exemplo {"id":123}.

Ações sem valor de retorno

Respondem com {"ok":true}.

Erros

Têm sempre um formato fixo com um código legível por máquina. Veja Formato de erro e códigos de erro.

#Paginação

Não existe um esquema único de paginação. A maioria das listas é pequena e vem completa; só alguns endpoints têm parâmetros:

Para sort nos links curtos existem created_desc, created_asc, redirects_desc e redirects_asc; q pesquisa no slug, no título e no URL de destino (até 100 caracteres, sem distinguir maiúsculas de minúsculas). Nas estatísticas, period aceita 24h, 7d, 30d, 90d, this_month, last_month, last_30d e custom; em alternativa, indica from e to. granularity é hour ou day.

#ID do pedido e idioma

• Todas as respostas trazem o cabeçalho X-Request-Id – indique-o quando contactar o suporte
• Se enviar o seu próprio cabeçalho X-Request-Id, a API usa-o
• O texto de erro em message está no idioma da conta do proprietário do espaço de trabalho, senão segue Accept-Language; o código em error fica sempre igual

#Chamar a partir do browser?

Tecnicamente, a API permite chamadas a partir do browser (CORS). Mas um segredo de chave nunca deve estar em código que corre do lado do visitante – nem num site, nem numa app. Chame a API sempre a partir do seu próprio servidor.

#Planos

Não existe uma quota de chamadas à API por plano. Aplicam-se apenas os rate limits por minuto. Os limites de conteúdo do seu plano – como páginas, links ou blocos por página – aplicam-se através da API tal como no painel. Veja Comparação de planos.

#A sua primeira chamada

# Trocar a chave por um token
curl -X POST https://dock.at-harbor.com/v1/token \
  -H "Content-Type: application/json" \
  -d '{"key_id":"6F668EA6598B0692","key_secret":"lt_…"}'
# → {"token":"eyJ…","expires_in":900}

export LH_TOKEN="eyJ…"

# Listar páginas (scope read:pages)
curl https://dock.at-harbor.com/v1/pages \
  -H "Authorization: Bearer $LH_TOKEN"

Um exemplo completo que adiciona um link, altera o design e publica está em Atualizar uma página via API.