La API de LinkHarbor de un vistazo

La API REST te permite controlar LinkHarbor desde tus propios programas: crear páginas y enlaces, editar y publicar borradores, generar enlaces cortos o llevar las estadísticas a tus propios informes. Este artículo es para desarrolladores y explica las reglas básicas que se aplican a todos los endpoints.

#¿Qué vía te conviene?

#URL base y versiones

URL base

https://dock.at-harbor.com: todos los endpoints del producto están bajo /v1, por ejemplo https://dock.at-harbor.com/v1/pages.

Versión

Por ahora solo existe la versión v1. El número de versión forma parte de la ruta.

Protocolo

Solo HTTPS.

OpenAPI

La descripción legible por máquinas (OpenAPI 3.1) está en https://dock.at-harbor.com/openapi.yaml. Puedes cargarla en Postman, Insomnia o un generador de código.

#Pruebas en el sandbox

Para desarrollo y pruebas hay un sandbox aparte. Se comporta como la API real, pero está completamente separado de ella: cuentas propias, datos propios, y nada de ello llega a tu espacio de trabajo real.

API

https://drydock.at-harbor.com, con las mismas rutas que arriba, por ejemplo https://drydock.at-harbor.com/v1/pages.

Panel

https://sandbox-deck.linkharbor.com, por ejemplo para crear claves de API.

Páginas

Las páginas publicadas aparecen en https://<handle>.sandbox.linkharbor.com.

Cuenta

Tu cuenta real de LinkHarbor no funciona allí. Crea una cuenta de sandbox aparte.

El sandbox no envía correos. Si te registras mediante la API (POST /v1/auth/register), el código de verificación vuelve directamente en la respuesta, en el campo _dev_verification. Lo mismo ocurre al restablecer la contraseña y al cambiar el correo. Este campo solo existe en el sandbox, así que no dependas de él en tu código.

• Las notificaciones push están desactivadas
• Los pagos pasan por el modo de prueba de Stripe; no se mueve dinero real
• Los límites de peticiones son aproximadamente un tercio de los reales, y las cuentas nuevas están limitadas a 5 por hora y dirección IP
• El día 1 de cada mes a las 3:00 UTC el sandbox se vacía por completo; después, todas las cuentas y los datos han desaparecido
• Cada respuesta lleva el encabezado X-Environment: sandbox

#La autenticación en resumen

1. Como propietario o admin, crea en el panel, en «Callback y API», una clave de API con los scopes que necesites (desde Creator Pro)
2. Cambia el ID y el secreto de la clave por un token de acceso mediante POST /v1/token
3. Envía el token en cada petición en el encabezado Authorization: Bearer …
4. Pide un token nuevo pasados 15 minutos

Todos los detalles están en Claves de API y tokens, y los permisos en Scopes.

#Peticiones y respuestas

Formato

Las peticiones y las respuestas son JSON en UTF-8. Las subidas de archivos usan además multipart/form-data.

Content-Type

Envía el encabezado Content-Type: application/json en cada petición que tenga cuerpo. Cualquier otro tipo se rechaza con 400 bad_request, incluido el que curl pone automáticamente con -d cuando falta este encabezado.

Campos desconocidos

Los campos que un endpoint no conoce provocan 422 validation_failed. La respuesta indica cuáles son los campos desconocidos.

JSON roto

Provoca 400 invalid_json.

Tamaño

Según el endpoint, un cuerpo puede tener como máximo 64 KB, 1 MB o 2 MB, y una subida de archivo 10 MB. Si es mayor, la API responde con 413 request_too_large. Todos los límites están en Límites de peticiones.

Listas

Llegan como un objeto con el campo items, por ejemplo {"items":[…]}.

Crear

Responde con HTTP 201 y el nuevo ID, por ejemplo {"id":123}.

Acciones sin valor de retorno

Responden con {"ok":true}.

Errores

Siempre tienen un formato fijo con un código legible por máquinas. Consulta Formato y códigos de error.

#Paginación

No hay un esquema de paginación único. La mayoría de las listas son pequeñas y llegan completas; solo algunos endpoints tienen parámetros:

Para sort en los enlaces cortos existen created_desc, created_asc, redirects_desc y redirects_asc; q busca en el slug, el título y la URL de destino (hasta 100 caracteres, sin distinguir mayúsculas de minúsculas). En las estadísticas, period acepta 24h, 7d, 30d, 90d, this_month, last_month, last_30d y custom; como alternativa, pasas from y to. granularity es hour o day.

#ID de petición e idioma

• Cada respuesta lleva el encabezado X-Request-Id; inclúyelo cuando contactes con soporte
• Si envías tú mismo un encabezado X-Request-Id, la API usa ese
• El texto de error en message está en el idioma de la cuenta del propietario del espacio de trabajo y, si no, sigue a Accept-Language; el código en error nunca cambia

#¿Llamarla desde el navegador?

Técnicamente, la API permite llamadas desde el navegador (CORS). Pero un secreto de clave nunca debe estar en código que se ejecuta en el lado del visitante, ni en una web ni en una app. Llama siempre a la API desde tu propio servidor.

#Planes

No hay una cuota de llamadas a la API por plan. Solo se aplican los límites de peticiones por minuto. Los límites de contenido de tu plan, como páginas, enlaces o bloques por página, se aplican en la API igual que en el panel. Consulta Comparativa de planes.

#Tu primera llamada

# Cambiar la clave por un 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 las páginas (scope read:pages)
curl https://dock.at-harbor.com/v1/pages \
  -H "Authorization: Bearer $LH_TOKEN"

Un ejemplo completo que añade un enlace, cambia el diseño y publica está en Actualizar una página mediante la API.