Acortador de URLs

Objetivo

Al terminar esta guía sabrás crear un enlace corto (por ejemplo https://h0b.co/promo-octubre) que lleva a la dirección larga que elijas, saber cuántas personas lo abren, cambiarlo o apagarlo cuando quieras y recuperarlo si lo eliminas por error.

Es útil cuando envías enlaces dentro de mensajes (donde cada carácter cuenta), cuando quieres medir una campaña o cuando necesitas poder cambiar el destino de un enlace ya repartido.

Requisitos

• Una organización activa de Hablame, con una clave de API vigente. Cómo obtenerla.
• El servicio urlshortener en la clave. Da todo el acortador: listar y ver enlaces, estadísticas, resumen, dominios y tarifa, y también crear (cada alta se cobra), editar, eliminar y restaurar. Solo el propietario de tu organización crea las claves.
• Saldo disponible o un plan del acortador vigente para crear enlaces. Además, tu organización necesita tener su moneda definida y una tarifa del acortador en esa moneda.
• Si quieres usar un dominio propio, tiene que estar registrado y verificado en tu organización. No hay un endpoint para registrarlo o verificarlo.

Credenciales

Toda petición lleva tu clave de API en la cabecera Authorization: Bearer hk_TU_API_KEY. El servicio urlshortener se da completo: no hay claves del acortador de solo lectura.

Pasos

1. 01
   Comprueba tu clave

   Llama a GET /utilities/ping. Un 200 confirma que la clave y la red funcionan.

2. 02
   Mira tus dominios

   GET /urlshortener/domains lista donde puedes publicar, con el predeterminado primero. Si no envías domain al crear, se usa ese.

3. 03
   Consulta la tarifa

   GET /urlshortener/pricing dice cuánto cuesta crear un enlace y cada visita a tu organización, y si tu plan lo incluye. Esta documentación no publica cifras.

4. 04
   Crea un enlace

   POST /urlshortener/links con la dirección de destino. Manda siempre una Idempotency-Key: si la petición se corta y la repites, no se crea ni se cobra otro enlace.

5. 05
   Compruébalo

   Abre la URL corta en un navegador y consulta el enlace con GET /urlshortener/links/{domain}/{code}.

6. 06
   Mide

   GET /urlshortener/links/{domain}/{code}/stats trae las visitas de un enlace por día o por hora y su desglose por país, dispositivo, sistema, navegador y origen. GET /urlshortener/overview resume toda tu organización.

7. 07
   Mantén

   Cambia el destino, apaga o vuelve a encender un enlace con PATCH; elimínalo con DELETE y recupéralo durante 90 días con restore.

Ejemplos

Crear un enlace

Solo se aceptan cuatro campos: longUrl (obligatorio), domain, code (tu alias) y expiresAt. Uno que no existe se rechaza con 400 nombrando el campo.

curl -X POST https://developers.hablame.co/api/v6/urlshortener/links \
  -H 'Authorization: Bearer hk_TU_API_KEY' \
  -H 'Idempotency-Key: 5f3b2c10-9a7e-4b2d-8c1f-0a1b2c3d4e5f' \
  -H 'Content-Type: application/json' \
  -d '{
    "longUrl": "https://example.com/landing?utm_source=sms",
    "code": "promo-octubre",
    "expiresAt": "2026-12-31T23:59:59-05:00"
  }'

import { randomUUID } from 'node:crypto'

const idempotencyKey = randomUUID()

const res = await fetch('https://developers.hablame.co/api/v6/urlshortener/links', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.HABLAME_API_KEY}`,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    longUrl: 'https://example.com/landing?utm_source=sms',
    code: 'promo-octubre',
  }),
})
const body = await res.json()
if (body.success) console.log(body.data.shortUrl)
else console.error(body.error.code, body.meta.requestId)

import os
import uuid
import requests

r = requests.post(
    "https://developers.hablame.co/api/v6/urlshortener/links",
    headers={
        "Authorization": f"Bearer {os.environ['HABLAME_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"longUrl": "https://example.com/landing?utm_source=sms", "code": "promo-octubre"},
    timeout=30,
)
body = r.json()
print(body["data"]["shortUrl"] if body["success"] else body["error"]["code"])

<?php
$ch = curl_init('https://developers.hablame.co/api/v6/urlshortener/links');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('HABLAME_API_KEY'),
        'Idempotency-Key: ' . bin2hex(random_bytes(16)),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        'longUrl' => 'https://example.com/landing?utm_source=sms',
        'code'    => 'promo-octubre',
    ]),
]);
$body = json_decode(curl_exec($ch), true);
echo $body['success'] ? $body['data']['shortUrl'] : $body['error']['code'];

Crear muchos a la vez

Para una campaña usa el alta en lote: hasta 1.000 enlaces por petición. Un enlace inválido no tumba el lote; la respuesta trae un resultado por enlace.

LOTE=campana-octubre-lote-01
curl -X POST https://developers.hablame.co/api/v6/urlshortener/links/batch \
  -H 'Authorization: Bearer hk_TU_API_KEY' \
  -H "Idempotency-Key: $LOTE" \
  -H 'Content-Type: application/json' \
  -d '{
    "links": [
      { "longUrl": "https://example.com/landing?c=1" },
      { "longUrl": "https://example.com/landing?c=2", "code": "oferta-2" }
    ]
  }'

Listar y medir

curl 'https://developers.hablame.co/api/v6/urlshortener/links?perPage=20&search=promo' \
  -H 'Authorization: Bearer hk_TU_API_KEY'

curl 'https://developers.hablame.co/api/v6/urlshortener/links/h0b.co/promo-octubre/stats?from=2026-10-01&to=2026-10-24' \
  -H 'Authorization: Bearer hk_TU_API_KEY'

Apagar y restaurar

curl -X PATCH https://developers.hablame.co/api/v6/urlshortener/links/h0b.co/promo-octubre \
  -H 'Authorization: Bearer hk_TU_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "status": "disabled" }'

curl -X POST https://developers.hablame.co/api/v6/urlshortener/links/h0b.co/promo-octubre/restore \
  -H 'Authorization: Bearer hk_TU_API_KEY'

Respuestas esperadas

Crear un enlace responde 201 con el enlace dentro de data. Los valores son de ejemplo:

{
  "success": true,
  "data": {
    "domain": "h0b.co",
    "code": "promo-octubre",
    "shortUrl": "https://h0b.co/promo-octubre",
    "longUrl": "https://example.com/landing?utm_source=sms",
    "isAlias": true,
    "status": "active",
    "domainStatus": "active",
    "expiresAt": "2027-01-01T04:59:59Z",
    "createdAt": "2026-10-24T15:04:05Z",
    "clicks": 0,
    "uniqueClicks": 0,
    "firstClickAt": null,
    "lastClickAt": null
  },
  "meta": {
    "requestId": "5d0f3a9c7b2e41a8",
    "clientIp": "203.0.113.45",
    "timestamp": "2026-10-24T15:04:05+00:00",
    "responseTimeMs": 31.2
  }
}

shortUrl

La URL corta completa, siempre https://{domain}/{code}. Es la que repartes.

status

active, disabled o blocked. Vencido no es un estado: un enlace active cuyo expiresAt ya pasó deja de redirigir, pero sigue en active. blocked lo pone Hablame por seguridad: no redirige y no se puede editar, eliminar ni reactivar.

domainStatus

Si el dominio deja abrir el enlace. Con suspended, released o pending el enlace no redirige aunque su status sea active.

clicks / uniqueClicks

Visitas de toda la vida del enlace y suma de las visitas únicas de cada día. Pueden tardar de segundos a pocos minutos en reflejarse. No cuentan robots ni vistas previas.

Con una Idempotency-Key repetida y el mismo cuerpo, recibes el mismo enlace con la cabecera Idempotency-Status: replayed, sin crear ni cobrar otro. Eliminar responde 204 sin cuerpo. Las listas traen items, total, hasMore y nextCursor: para recorrer muchos enlaces pasa el nextCursor como cursor en la siguiente petición.

Errores habituales

Todos los códigos están en el catálogo de errores y los síntomas más comunes, en resolución de problemas.

Seguridad

• Separa las claves por servicio. El acortador se da completo: una clave con él también crea, redirige y elimina tus enlaces si se filtra. Dale el servicio urlshortener solo al sistema que de verdad los administra; solo el propietario de tu organización crea las claves.
• Cuida el destino. Quien controla longUrl controla a dónde llevan tus enlaces ya repartidos. Valida de dónde viene cada destino antes de enviarlo.
• Hablame filtra los destinos peligrosos. Se rechazan localhost, nombres internos, direcciones IP privadas o reservadas, otros enlaces cortos, destinos con usuario antes del dominio y dominios con caracteres invisibles o de otros alfabetos. En los dominios compartidos tampoco se admiten alias que imiten una marca, un banco, un medio de pago o una entidad pública.
• Un enlace eliminado no libera su código. Nadie puede reutilizarlo para apuntar a otro lado. Tú puedes restaurarlo durante 90 días.
• Cada cambio queda registrado: el valor anterior, el nuevo y quién lo hizo (la clave de API o el usuario de Cloud).

Endpoints relacionados

Todos piden solo el servicio urlshortener: con él, la clave también crea, edita, elimina y restaura.

Próximos pasos

Para dudas técnicas escribe a developers@hablame.co. Si tienes una incidencia en producción, escribe por WhatsApp al +57 319 660 0002, las 24 horas.