API pública

• URL base: https://app.broslunas.link/api/v1
• Formato: JSON en peticiones y respuestas (UTF-8). Envía Content-Type: application/json.
• Alcance: cada token da acceso a una sola página y solo a sus enlaces. No hay endpoints de perfil, tema, estadísticas ni dominio.
• Sin CORS: está pensada para servidores. No uses un token en código que corra en un navegador.

1. Entra en el panel → API y crea un token. 2. Pruébalo:

curl https://app.broslunas.link/api/v1/links \
  -H "Authorization: Bearer $TOKEN"

Crea tokens en el panel (Dashboard → API). Elige un nombre y un permiso:

Envía el token en cada petición:

Authorization: Bearer bl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• El token (bl_ + 43 caracteres) se muestra una sola vez. Solo guardamos su hash SHA-256; si lo pierdes, revócalo y crea otro.
• Máximo 5 tokens por página. Se eliminan al borrar o transferir la página, y dejan de valer si la página se suspende.
• Guárdalo en variables de entorno, usa un token por integración y con el permiso mínimo. Si se filtra, revócalo: el efecto es inmediato.
• Sin cabecera, mal formada, token desconocido o revocado → 401 con WWW-Authenticate: Bearer.

Todos los errores tienen la misma forma:

{ "error": { "code": "invalid_link", "message": "URL no válida" } }

message está en español y se puede mostrar al usuario. Para la lógica usa code y el estado HTTP.

{
  "id": "6720f1c2a9b3c4d5e6f70812",
  "kind": "link",
  "label": "Mi portfolio",
  "url": "https://ejemplo.com",
  "icon": "web",
  "description": "Trabajos recientes",
  "imageUrl": null,
  "badge": "Nuevo",
  "featured": false,
  "social": false,
  "sensitive": false,
  "enabled": true,
  "startAt": null,
  "endAt": null,
  "position": 0
}

Qué admite url según kind

Los campos que no aplican a un tipo (por ejemplo featured en un embed) se descartan sin error.

Iconos e imágenes

• Catálogo: web, whatsapp, instagram, tiktok, youtube, x, facebook, linkedin, github, email, phone, telegram, signal, discord, threads, bluesky, mastodon, twitch, pinterest, snapchat.
• Lucide: lucide: + nombre en kebab-case, p. ej. lucide:map-pin.
• Propio: img:https://…, solo si es un icono que ya subiste a esta página desde el panel.
• imageUrl solo acepta imágenes alojadas en el almacenamiento de tu página (las que genera el panel al subirlas). Una URL externa o de otra página da 422 «Imagen no válida». La API no sube archivos.

GET/links· token de lectura o escritura

Devuelve todos los enlaces, también los desactivados y los programados, ordenados por position.

curl https://app.broslunas.link/api/v1/links -H "Authorization: Bearer $TOKEN"

{ "links": [ { "id": "…", "label": "…", "position": 0 } ] }

POST/links· requiere escritura

Lo añade al final. Solo label es obligatorio (y url salvo en header). No acepta enabled ni position: se crea activo; ocúltalo después con PATCH.

curl -X POST https://app.broslunas.link/api/v1/links \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Reserva tu cita",
    "url": "https://ejemplo.com/reservas",
    "icon": "lucide:calendar",
    "badge": "Nuevo",
    "featured": true,
    "startAt": "2026-12-01T00:00:00Z",
    "endAt": "2026-12-31T23:59:59Z"
  }'

Respuesta 201 con { "link": { … } }. Errores: 400, 403, 422.

{ "kind": "header", "label": "Redes" }
{ "kind": "embed", "label": "Mi último vídeo", "url": "https://youtu.be/dQw4w9WgXcQ" }
{ "label": "Escríbeme", "url": "mailto:hola@ejemplo.com", "icon": "email" }
{ "label": "Llámame", "url": "tel:+34600123456", "icon": "phone" }

GET/links/:id· token de lectura o escritura

200 con { "link": { … } }. 404 si no existe o es de otra página.

PATCH/links/:id· requiere escritura

Edición parcial: solo cambian los campos que envíes. Acepta label, url, enabled, icon, description, imageUrl, badge, featured, social, sensitive, startAt y endAt. Envía null para vaciar un campo opcional. kind no se puede cambiar.

# Ocultar un enlace
curl -X PATCH https://app.broslunas.link/api/v1/links/6720f1c2a9b3c4d5e6f70812 \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "enabled": false }'

# Quitar la programación
-d '{ "startAt": null, "endAt": null }'

200 con el enlace ya actualizado. Si cambias icon o imageUrl, el archivo propio anterior se elimina. Errores: 400, 403, 404, 422.

DELETE/links/:id· requiere escritura

Borra el enlace y sus imágenes e iconos propios. Las estadísticas históricas de clics se conservan.

200 con { "ok": true }. Repetir un DELETE ya hecho devuelve 404.

PUT/links/order· requiere escritura

ids debe contener todos los enlaces de la página, una vez cada uno, en el orden deseado (el primero queda arriba). Si falta, sobra o se repite alguno no se cambia nada y se devuelve 422 invalid_order; así dos clientes a la vez no pueden dejar posiciones duplicadas.

curl -X PUT https://app.broslunas.link/api/v1/links/order \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "ids": ["6720…0813", "6720…0812", "6720…0814"] }'

200 con { "links": [ … ] } ya ordenados. Para mover uno: GET, reordena el array de ids y envíalo.

• Visibilidad pública: la página solo muestra enlaces con enabled: true y dentro de su ventana startAt/endAt. La API siempre devuelve todos.
• Caché: cada escritura invalida la caché de tu página; el cambio se ve de inmediato.
• Concurrencia: no hay control de versiones; gana la última escritura.
• Reintentos: GET, PUT /links/order y PATCH con los mismos valores se pueden repetir. POST no: reintentar tras un timeout puede duplicar el enlace; comprueba con GET antes.
• Aislamiento: cada consulta lleva la página del token; nunca verá ni modificará datos de otra.