Guía de la API de SULI

Primeros pasos

curl https://url.51x.mx/api/links -H "Authorization: Bearer TU_API_KEY"

Si todo está bien, verás una respuesta JSON con tus enlaces (o una lista vacía si aún no tienes ninguno).

Autenticación

Cada llamada a la API debe incluir un header Authorization con el formato:

Authorization: Bearer suli_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

No hay usuario/contraseña ni cookies de sesión — la clave por sí sola identifica tanto tu organización como el rol con el que operas.

Revocar una clave: desde /api-keys.php, botón "Revocar". Efecto inmediato — cualquier integración que la use empezará a recibir 401 invalid_api_key.

Permisos según el rol

Cuando generas una clave, esta hereda el rol del usuario que la creó. Si ese usuario cambia de rol o se desactiva su organización, la clave se ajusta automáticamente (no hace falta regenerarla).

Si tu clave no tiene el permiso necesario, la API responde 403 forbidden — en ese caso, pide a un administrador que te genere una clave desde un usuario con el rol adecuado (normalmente supervisor o administrador cubre la mayoría de los casos de uso).

Base URL

https://url.51x.mx/api/

Todas las rutas de esta guía son relativas a esa base.

Endpoints

Crear un enlace

POST /api/links

curl -X POST https://url.51x.mx/api/links \
  -H "Authorization: Bearer suli_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://ejemplo.com/pagina-larga",
    "title": "Campaña de agosto",
    "vigencia": "1m"
  }'

<?php
$ch = curl_init('https://url.51x.mx/api/links');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer suli_xxxxxxxx',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'url' => 'https://ejemplo.com/pagina-larga',
        'title' => 'Campaña de agosto',
        'vigencia' => '1m',
    ]),
]);
$response = json_decode(curl_exec($ch), true);
echo $response['data']['short_url'];

const res = await fetch('https://url.51x.mx/api/links', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer suli_xxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://ejemplo.com/pagina-larga',
    title: 'Campaña de agosto',
    vigencia: '1m',
  }),
});
const { data } = await res.json();
console.log(data.short_url);

{
  "data": {
    "id": 42,
    "code": "aB3k9",
    "short_url": "https://url.51x.mx/aB3k9",
    "original_url": "https://ejemplo.com/pagina-larga",
    "title": "Campaña de agosto",
    "expires_at": "2026-09-10 00:00:00",
    "clicks": 0
  }
}

expires_at viene en null si el enlace no tiene vigencia (es indefinido).

Listar enlaces

GET /api/links

Devuelve los enlaces de tu organización, del más reciente al más antiguo.

curl "https://url.51x.mx/api/links?page=1&per_page=50" \
  -H "Authorization: Bearer suli_xxxxxxxx"

{
  "data": [
    {
      "id": 42,
      "code": "aB3k9",
      "short_url": "https://url.51x.mx/aB3k9",
      "original_url": "https://ejemplo.com/pagina-larga",
      "title": "Campaña de agosto",
      "expires_at": "2026-09-10 00:00:00",
      "clicks": 7
    }
  ],
  "pagination": { "page": 1, "per_page": 50, "total": 1 }
}

pagination.total es el número total de enlaces que tiene tu organización (no solo los de esta página) — úsalo para saber cuántas páginas más pedir.

Consultar un enlace específico

GET /api/links/{code}

Donde {code} es el código corto (lo que va después del dominio, ej. aB3k9).

curl https://url.51x.mx/api/links/aB3k9 \
  -H "Authorization: Bearer suli_xxxxxxxx"

La respuesta usa el mismo formato que un elemento de la lista anterior. Útil para revisar cuántos clics lleva un enlace específico sin tener que listarlos todos.

Manejo de errores

Cuando algo falla, la API siempre responde con este formato:

{ "error": { "code": "invalid_url", "message": "El campo \"url\" es obligatorio y debe ser una URL válida." } }

code es estable y pensado para que tu programa lo compare directamente (ej. if (error.code === 'code_taken')); message es para mostrar a un humano o depurar.

Preguntas frecuentes