⚙️ API REST de Linkyaa

La API de Linkyaa permite crear y gestionar links cortos, consultar analytics y automatizar flujos desde tu aplicación, CRM o herramienta de marketing.

Base URL: https://linkyaa.com/api/linkyaa

Formato: JSON · Versión: v1

Autenticación

La API usa tokens en el header Authorization. Hay dos formas de autenticarte:

Authorization: Bearer {tu_token_jwt}

Opción 1 — Token de sesión (JWT): el que obtienes al iniciar sesión, expira a los 30 días.

Opción 2 — API key (plan Business): genera una desde el panel en Configuración → API & Webhooks. No expira hasta que la revoques y tiene el mismo formato en el header Authorization: Bearer lk_xxxxxxxx_.... Ideal para integraciones server-to-server, ya que no depende de que tu sesión siga activa.

Para obtener un token de sesión:

POST /api/linkyaa/login
{
  "email": "tu@empresa.co",
  "password": "tu_contraseña"
}

// Respuesta:
{
  "token": "eyJhbGci...",
  "user": { "id": 1, "plan": "pro" }
}

Manejo de errores

La API usa códigos HTTP estándar. Los errores incluyen un campo error con descripción.

Demo de link (público)

POST /api/linkyaa/demo
{
  "url": "https://mitienda.co/catalogo-julio"
}

// Respuesta:
{
  "slug": "ab3k9x",
  "short_url": "https://linkyaa.com/ab3k9x"
}

Listar links

GET /api/linkyaa/links
Authorization: Bearer {token}

// Respuesta:
[
  {
    "id": 42,
    "slug": "promo-julio",
    "destination_url": "https://tienda.co/ofertas",
    "short_url": "https://linkyaa.com/promo-julio",
    "clicks": 1247,
    "is_active": 1,
    "created_at": "2026-07-01T10:00:00Z"
  }
]

Crear link

POST /api/linkyaa/links
Authorization: Bearer {token}

{
  "destination_url": "https://tienda.co/oferta-especial",
  "title": "Promo Amor y Amistad",
  "custom_slug": "amor26"
}

// Respuesta:
{
  "id": 87,
  "slug": "amor26",
  "short_url": "https://linkyaa.com/amor26"
}

Editar link

PUT /api/linkyaa/links/87
Authorization: Bearer {token}

{
  "destination_url": "https://tienda.co/nueva-url",
  "is_active": true
}

Eliminar link

DELETE /api/linkyaa/links/87
Authorization: Bearer {token}

// Respuesta:
{ "success": true }

Analytics de un link

GET /api/linkyaa/links/87/analytics?days=30
Authorization: Bearer {token}

// Respuesta:
{
  "total_clicks": 1247,
  "clicks_by_country": [{ "country": "CO", "clicks": 1100 }],
  "clicks_by_device": [{ "device": "mobile", "clicks": 970 }],
  "clicks_by_day": [{ "date": "2026-07-01", "clicks": 87 }]
}

Perfil del usuario

GET /api/linkyaa/me
Authorization: Bearer {token}

// Respuesta:
{
  "id": 1,
  "name": "Mi Empresa",
  "email": "yo@empresa.co",
  "plan": "pro",
  "link_count": 42,
  "total_clicks": 18500
}

Rate limits

Para garantizar disponibilidad, aplicamos los siguientes límites:

Cuando se supera el límite, la API retorna 429 Too Many Requests con el header Retry-After.

Webhooks

Linkyaa puede notificar tu servidor en tiempo real cuando un link recibe clics. Disponible en el plan Business. Configúralos desde el panel en Configuración → API & Webhooks → Webhooks: solo necesitas la URL de tu endpoint, ahí mismo obtienes el signing secret y puedes enviar un evento de prueba.

// Payload de evento click:
{
  "event": "link.clicked",
  "link_id": 87,
  "slug": "amor26",
  "short_url": "https://linkyaa.com/amor26",
  "destination_url": "https://tienda.co/ofertas",
  "country": "CO",
  "device": "mobile",
  "browser": "Chrome",
  "os": "Android",
  "timestamp": "2026-07-18T20:30:00Z"
}

Cada entrega incluye el header X-Linkyaa-Signature: sha256={hmac}, un HMAC-SHA256 del cuerpo firmado con tu signing secret. Verifícalo antes de procesar el payload:

const crypto = require('crypto');
const expected = crypto.createHmac('sha256', secret)
  .update(rawBody).digest('hex');
const valid = expected === signatureHeader.replace('sha256=', '');

Tu endpoint debe responder 2xx en menos de 5 segundos. Si falla 20 veces seguidas, el webhook se pausa automáticamente y puedes reactivarlo desde el panel.

¿Necesitas ayuda con la API? Centro de ayuda · api@linkyaa.com