Referencia API REST

Autenticación

La API ClicAven usa claves API para la autenticación. Cada solicitud debe incluir su clave en el encabezado Authorization.

Cómo obtener una clave API

1. Inicie sesión en su cuenta ClicAven y acceda a la página Claves API
2. Asigne un nombre a su clave y haga clic en Crear
3. Copie la clave mostrada — no volverá a ser visible

Headers requeridos

Authorization: Bearer ca_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

POST/api/links

Crea un nuevo enlace corto. Requiere una clave API válida.

Headers requeridos

Authorization: Bearer ca_votre_cle_api
Content-Type: application/json

Body de la solicitud

{
  "url": "https://example.com/une-url-tres-longue",
  "title": "Promo Noël LinkedIn",
  "customSlug": "promo-noel",
  "domainHostname": "go.mon-domaine.com",
  "permanent": true
}

El campo title es opcional (120 caracteres como máximo). Sirve para encontrar el enlace en el panel y en la exportación CSV; nunca se muestra públicamente.

Campos del enlace

El esquema completo y actualizado se publica en formato OpenAPI 3.1: /api/openapi.json y /api/openapi.yaml. Se genera a partir del código, por lo que es la referencia autorizada.

Respuesta (201 Created)

{
  "@context": "/api/contexts/Link",
  "@id": "/api/links/01a08b81-78ad-7720-a4c8-3133c7752bb9",
  "@type": "Link",
  "id": "01a08b81-78ad-7720-a4c8-3133c7752bb9",
  "url": "https://example.com/une-url-tres-longue",
  "short": "aB3xYz",
  "shortUrl": "https://clicaven.com/aB3xYz",
  "title": "Promo Noël LinkedIn",
  "clickCount": 0,
  "createdAt": "2026-04-18T12:00:00+00:00",
  "permanent": true,
  "domainHostname": null
}

Ejemplo curl

curl -s -X POST https://clicaven.com/api/links \
  -H "Authorization: Bearer ca_votre_cle_api" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/page-longue?utm_source=api","title":"Campagne API"}'

GET/api/links

Lista todos sus enlaces cortos. Requiere una clave API válida.

Ejemplo curl

curl -s https://clicaven.com/api/links \
  -H "Authorization: Bearer ca_votre_cle_api" | jq .

Respuesta (200 OK)

{
  "@context": "/api/contexts/Link",
  "@id": "/api/links",
  "@type": "Collection",
  "totalItems": 1,
  "member": [
    {
      "@id": "/api/links/01a08b81-78ad-7720-a4c8-3133c7752bb9",
      "@type": "Link",
      "id": "01a08b81-78ad-7720-a4c8-3133c7752bb9",
      "url": "https://example.com/page-longue",
      "short": "aB3xYz",
      "shortUrl": "https://clicaven.com/aB3xYz",
      "title": "Promo Noël LinkedIn",
      "clickCount": 14,
      "createdAt": "2026-04-18T12:00:00+00:00",
      "permanent": true,
      "domainHostname": null
    }
  ]
}

GET/api/links/{id}

Obtiene los detalles de un enlace específico, incluido el contador de clics.

Ejemplo curl

curl -s https://clicaven.com/api/links/01a08b81-78ad-7720-a4c8-3133c7752bb9 \
  -H "Authorization: Bearer ca_votre_cle_api" | jq .

Respuesta (200 OK)

{
  "@context": "/api/contexts/Link",
  "@id": "/api/links/01a08b81-78ad-7720-a4c8-3133c7752bb9",
  "@type": "Link",
  "id": "01a08b81-78ad-7720-a4c8-3133c7752bb9",
  "url": "https://example.com/page-longue",
  "short": "aB3xYz",
  "shortUrl": "https://clicaven.com/aB3xYz",
  "title": "Promo Noël LinkedIn",
  "clickCount": 14,
  "createdAt": "2026-04-18T12:00:00+00:00",
  "permanent": true,
  "domainHostname": null
}

DELETE/api/links/{id}

Elimina definitivamente un enlace. La redirección quedará inmediatamente inactiva. Esta acción es irreversible.

Ejemplo curl

curl -s -X DELETE https://clicaven.com/api/links/01a08b81-78ad-7720-a4c8-3133c7752bb9 \
  -H "Authorization: Bearer ca_votre_cle_api"
# → 204 No Content (éxito, sin cuerpo)

6. Códigos de error

Formato de error

{
  "error": "authentication_failed",
  "message": "Invalid or expired API key."
}

Ejemplos PHP y JavaScript

No necesita ningún SDK: la API es una simple API REST JSON. Aquí encontrará ejemplos listos para copiar en los lenguajes más habituales.

PHP

<?php
// ClicAven API — PHP example (no SDK needed)
$apiKey = 'ca_votre_cle_api';
$url    = 'https://example.com/une-url-tres-longue';

$ch = curl_init('https://clicaven.com/api/links');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['url' => $url]),
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

echo $response['shortUrl'];
// => https://clicaven.com/aB3xYz

JavaScript (Node.js / fetch)

const API_KEY = 'ca_votre_cle_api';

const res = await fetch('https://clicaven.com/api/links', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ url: 'https://example.com/une-url-tres-longue' }),
});

const link = await res.json();
console.log(link.shortUrl);
// => https://clicaven.com/aB3xYz

Enlace con slug personalizado (Pro+)

curl -s -X POST https://clicaven.com/api/links \
  -H "Authorization: Bearer ca_votre_cle_api" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/promo","customSlug":"ma-promo"}'

{
  "id": 43,
  "short": "rT9kWm",
  "customSlug": "ma-promo",
  "shortUrl": "https://clicaven.com/ma-promo",
  "url": "https://example.com/promo",
  "clickCount": 0,
  "createdAt": "2026-04-25T14:00:00+00:00"
}

Los slugs personalizados requieren un plan Pro o superior. De 3 a 60 caracteres, letras, números y guiones.