Nombre

Listar enlaces cortos

Tus enlaces paginados, con búsqueda, filtros, orden y sus contadores de visitas.

Método HTTP y ruta

GET/api/v6/urlshortener/links

https://developers.hablame.co/api/v6/urlshortener/links

Qué pasa al ejecutarlo

Solo consulta: no cambia datos de tu organización.
La llamada no se cobra.

Qué hace

Lista los enlaces de tu organización (nunca los eliminados) con sus contadores ya consolidados. Por defecto, del más nuevo al más viejo. Todos los filtros son opcionales y se combinan entre sí.

Para recorrer muchos enlaces, pagina con cursor. Cada respuesta trae nextCursor mientras haya más: pásalo en la siguiente petición, con los mismos filtros, sort y order, y la página empieza justo después del último enlace de la anterior. page sigue funcionando como siempre, pero solo hasta el enlace 10.000 (con perPage=100, hasta la página 100); más allá responde 400 y hay que seguir con cursor, que no tiene tope.

total es exacto hasta 10.000. Si los enlaces que cumplen los filtros son más, total llega en 10000 y totalIsExact en false: «más de 10.000». hasMore dice siempre, sin error, si hay otra página.

Disponibilidad y requisitos previos

Publicado y disponible en la API v6 de producción.
Todas las rutas parten de https://developers.hablame.co.
Necesitas una API key de Hablame para llamarlo.

Crea tu clave de API

Autenticación y permisos

Envía tu API key en la cabecera Authorization con el esquema Bearer.

Quién puede llamarlo: Una API key con el servicio urlshortener habilitado.

Límites y consideraciones operativas

Límite de uso: 30 solicitudes por minuto.

Hasta 100 ítems por página; un valor mayor se recorta a 100.
total es exacto hasta 10.000; por encima, totalIsExact es false.
Con page se llega hasta el enlace 10.000; para seguir, cursor.
Una búsqueda o un orden demasiado costosos para una organización muy grande se detienen a los pocos segundos con 504.

Parámetros de ruta

Este endpoint no tiene parámetros de ruta.

Parámetros de consulta

Nombre	Tipo	Descripción y reglas
`page`Opcional	`integer`	Número de página (empieza en 1). Llega hasta el enlace 10.000: la página tiene que empezar, como mucho, en el enlace 10.000. Con `cursor` se ignora. Valor por omisión:`1`Mínimo:`1`
`perPage`Opcional	`integer`	Ítems por página (máximo 100). Valor por omisión:`20`Mínimo:`1`Máximo:`100`
`cursor`Opcional	`string`	El `nextCursor` de la respuesta anterior, tal cual. La página empieza justo después del último enlace de esa respuesta. Tiene que ir con el mismo `sort` y `order`; un cursor que no es de esta organización o de este orden responde `400`.
`search`Opcional	`string`	Busca en el código y en la URL de destino, por fragmento y sin distinguir mayúsculas ni tildes (mínimo 2 caracteres; con menos se ignora). Si pegas una URL corta completa (`h0b.co/a1b2c3d` o `https://h0b.co/a1b2c3d`), trae exactamente ese enlace, también si su dominio ya no es de tu organización (`domainStatus: released`). Largo mínimo:`2`
`domain`Opcional	`string`	Solo los enlaces de este dominio. Los de un dominio que ya no es de tu organización (`domainStatus: released`) no entran aunque se llamen igual: para encontrar uno, pega su URL corta en `search`.
`state`Opcional	`string`	Estado tal como lo vive quien visita: `active` (activo y sin vencer), `expired` (activo con el vencimiento ya pasado: ya no redirige), `disabled` o `blocked` (bloqueado por Hablame). Valores permitidos:`active` `expired` `disabled` `blocked`
`status`Opcional	`string`	Estado guardado. `active` incluye los vencidos. Se conserva por compatibilidad; prefiere `state`. Valores permitidos:`active` `disabled` `blocked`
`kind`Opcional	`string`	Enlaces con alias elegido, o con código generado. Valores permitidos:`alias` `generated`
`traffic`Opcional	`string`	`none`: los que nunca han recibido una visita. `some`: los que han recibido al menos una. Valores permitidos:`none` `some`
`createdFrom`Opcional	`string`	Creados desde este día (`AAAA-MM-DD`, hora de Colombia), incluido. Formato:`date`Ejemplo:`2026-09-01`
`createdTo`Opcional	`string`	Creados hasta este día (`AAAA-MM-DD`, hora de Colombia), incluido. Formato:`date`Ejemplo:`2026-09-23`
`sort`Opcional	`string`	Orden: por fecha de creación, por visitas de toda la vida, por última visita o por vencimiento. Con `lastClick` y `expires`, los enlaces sin ese dato van al final en los dos sentidos. Valores permitidos:`created` `clicks` `lastClick` `expires`Valor por omisión:`created`
`order`Opcional	`string`	Sentido del orden. Valores permitidos:`desc` `asc`Valor por omisión:`desc`

Encabezados HTTP

Nombre Tipo Descripción y reglas

Nombre	Tipo	Descripción y reglas
`Authorization`Obligatorio	`string`	Tu API key con el esquema Bearer. Ejemplo:`Bearer hk_TU_API_KEY`

AuthorizationObligatorio

string

Tu API key con el esquema Bearer.

Ejemplo:Bearer hk_TU_API_KEY

Cuerpo de la petición

Este endpoint no recibe cuerpo en la petición.

Respuestas satisfactorias

200

Página de enlaces.

Ejemplo de respuesta

{
  "success": true,
  "data": {
    "items": [
      {
        "domain": "h0b.co",
        "code": "a1b2c3d",
        "shortUrl": "https://h0b.co/a1b2c3d",
        "longUrl": "https://example.com/landing",
        "isAlias": false,
        "status": "active",
        "domainStatus": "active",
        "expiresAt": null,
        "createdAt": "2026-09-20T15:04:05Z",
        "clicks": 128,
        "uniqueClicks": 96,
        "firstClickAt": "2026-09-20T15:31:40Z",
        "lastClickAt": "2026-09-23T18:22:10Z"
      }
    ],
    "page": 1,
    "perPage": 20,
    "total": 1,
    "totalIsExact": true,
    "hasMore": false,
    "nextCursor": null
  },
  "meta": {
    "requestId": "8f0c0e2a4b1d4c8f",
    "clientIp": "203.0.113.45",
    "timestamp": "2026-09-23T18:30:00+00:00",
    "responseTimeMs": 7.2
  }
}

Los valores del ejemplo son ilustrativos.

Campos de la respuesta

Nombre	Tipo	Descripción y reglas
`success`Siempre presente	`boolean`
`data`Siempre presente	`object`
`data.items`Siempre presente	`array<object>`
`data.items[].domain`Siempre presente	`string`	Dominio del enlace, en minúsculas. Si el dominio ya no es de tu organización (`domainStatus: released`), es el nombre que tenía.
`data.items[].code`Siempre presente	`string`	Código del enlace, en minúsculas: 7 caracteres `0-9a-z` cuando lo genera el servicio, o el alias que se eligió al crearlo. Único por dominio.
`data.items[].shortUrl`Siempre presente	`string`	La URL corta completa: siempre `https://{domain}/{code}`. Formato:`uri`
`data.items[].longUrl`Siempre presente	`string`	URL de destino. Formato:`uri`
`data.items[].isAlias`Siempre presente	`boolean`	`true` cuando el código lo eligió quien creó el enlace (campo `code` al crearlo); `false` cuando lo generó el servicio.
`data.items[].status`Siempre presente	`string`	`active`, `disabled` o `blocked` (y `deleted`, solo en el caso de abajo). Vencido no es un estado: un enlace `active` con `expiresAt` en el pasado ya no redirige, pero conserva `active`. `blocked` es un enlace que Hablame bloqueó por seguridad: no redirige y no se puede editar, eliminar ni reactivar desde la API; si crees que es un error, escríbenos. Los enlaces eliminados no aparecen en las respuestas, salvo en la repetición de un alta con `Idempotency-Key` cuyo enlace se eliminó después: llega tal como está, con `deleted`. Valores permitidos:`active` `disabled` `blocked` `deleted`
`data.items[].domainStatus`	`string`	Si el dominio deja abrir el enlace, aparte de su propio `status`. `active`: lo deja. `suspended`: el dominio está suspendido; `released`: el dominio ya no es de tu organización; `pending`: es un dominio propio que todavía no está verificado. Con esos tres el enlace no redirige (el visitante recibe `404`) aunque su `status` sea `active`. Llega en la lista, en la consulta de un enlace y al crearlo, editarlo o restaurarlo; si no llega, trátalo como antes de que existiera. Pueden aparecer valores nuevos: uno que no conozcas no significa que el enlace no abra. Valores permitidos:`active` `pending` `suspended` `released`
`data.items[].expiresAt`Siempre presente	`string`	Vencimiento en UTC, o `null` si no vence. Puede llegar en `null`. Formato:`date-time`
`data.items[].createdAt`Siempre presente	`string`	Fecha de creación, en UTC. Formato:`date-time`
`data.items[].clicks`Siempre presente	`integer`	Visitas de toda la vida del enlace. Las consolida un proceso en segundo plano: una visita puede tardar de segundos a pocos minutos en reflejarse. No cuenta bots ni las vistas previas que generan las redes sociales y los chats.
`data.items[].uniqueClicks`Siempre presente	`integer`	Suma de las visitas únicas de cada día: la primera visita del día desde cada navegador. No son personas distintas en toda la vida del enlace.
`data.items[].firstClickAt`Siempre presente	`string`	Primera visita, en UTC. `null` si nunca ha recibido una. Puede llegar en `null`. Formato:`date-time`
`data.items[].lastClickAt`Siempre presente	`string`	Última visita, en UTC. `null` si nunca ha recibido una. Puede llegar en `null`. Formato:`date-time`
`data.page`Siempre presente	`integer`	La página pedida, o `0` si se pidió con `cursor`.
`data.perPage`Siempre presente	`integer`
`data.total`Siempre presente	`integer`	Enlaces que cumplen los filtros, exacto hasta 10.000. Si son más, llega en `10000` y `totalIsExact` es `false`.
`data.totalIsExact`Siempre presente	`boolean`	`false` cuando hay más de 10.000 y `total` es el tope.
`data.hasMore`Siempre presente	`boolean`	`true` si hay más páginas.
`data.nextCursor`Siempre presente	`string`	Para pedir la página siguiente con `cursor`, o `null` si no hay más. Puede llegar en `null`.
`meta`Siempre presente	`object`	Metadatos de la respuesta.
`meta.requestId`Siempre presente	`string`	Identificador único de la solicitud (16 caracteres hexadecimales). Es el mismo de la cabecera `X-Request-Id`. Cítalo al contactar soporte. Ejemplo:`b9b1704baffab211`
`meta.clientIp`Siempre presente	`string`	IP con la que la API vio tu solicitud. Útil si tu API key solo admite ciertas redes. Ejemplo:`203.0.113.45`
`meta.timestamp`Siempre presente	`string`	Fecha y hora en que se construyó la respuesta (ISO 8601 con offset). Formato:`date-time`Ejemplo:`2026-06-04T19:43:59+00:00`
`meta.responseTimeMs`Siempre presente	`number`	Tiempo (ms) que tomó procesar la solicitud en el servidor. Ejemplo:`4.24`

Códigos de error

Todas las respuestas de error tienen la misma forma: success en false y un objeto error cuyo code dice qué pasó. Aquí están agrupadas por tipo, con los códigos que este endpoint puede devolver.

Forma de una respuesta de error

Nombre	Tipo	Descripción y reglas
`success`Siempre presente	`boolean`	Valor fijo:`false`
`meta`Siempre presente	`object`	Metadatos de la respuesta.
`meta.requestId`Siempre presente	`string`	Identificador único de la solicitud (16 caracteres hexadecimales). Es el mismo de la cabecera `X-Request-Id`. Cítalo al contactar soporte. Ejemplo:`b9b1704baffab211`
`meta.clientIp`Siempre presente	`string`	IP con la que la API vio tu solicitud. Útil si tu API key solo admite ciertas redes. Ejemplo:`203.0.113.45`
`meta.timestamp`Siempre presente	`string`	Fecha y hora en que se construyó la respuesta (ISO 8601 con offset). Formato:`date-time`Ejemplo:`2026-06-04T19:43:59+00:00`
`meta.responseTimeMs`Siempre presente	`number`	Tiempo (ms) que tomó procesar la solicitud en el servidor. Ejemplo:`4.24`
`error`Siempre presente	`object`
`error.code`Siempre presente	`string`	Identificador estable en UPPER_SNAKE_CASE. Los clientes ramifican sobre este valor. Ejemplo:`AUTH_REQUIRED`
`error.legacyCode`	`integer`	Código numérico legacy v5, solo cuando hay puente. Se omite en los códigos nacidos en v6. Ejemplo:`40002`
`error.type`Siempre presente	`string`	URL a la documentación del error. Formato:`uri`Ejemplo:`https://developers.hablame.co/docs/v6/errors/auth-required`
`error.message`Siempre presente	`string`	Texto legible en inglés. Es para el log del desarrollador, no para el usuario final: no lo parsees.
`error.details`Siempre presente	`array<object>`	Contexto estructurado (validaciones, recurso afectado). Arreglo vacío cuando no hay contexto extra.

Validación

400Un filtro trae un valor que no existe (el mensaje dice cuál y qué valores acepta), una fecha que no es AAAA-MM-DD, una page más allá del enlace 10.000 o un cursor que no vale.

400VALIDATION_INVALID_PARAMETER
Un parámetro o un campo del cuerpo no es válido.

Autenticación

401Credenciales inválidas o faltantes.

401AUTH_REQUIRED
No se envió un token Bearer y cada llamada lo requiere.
Mensaje que devuelve la API: Authentication is required. Send your API key as `Authorization: Bearer <token>`.
401AUTH_INVALID_KEY
La clave de API no se reconoce: formato equivocado, revocada o vencida.
Mensaje que devuelve la API: The provided API key is invalid or has expired. Please verify the value sent in the `Authorization: Bearer` header.

Permisos

403La API key no tiene habilitado el acortador (o está apagado para tu organización), la key no se puede usar desde la red de la petición, o la organización no está activa.

403AUTH_SERVICE_NOT_ALLOWED
La clave no tiene permitido el servicio detrás de este endpoint.
Mensaje que devuelve la API: This API key is not authorized to use the requested service.
403AUTH_IP_NOT_ALLOWED
La clave solo funciona desde ciertas redes y tu IP no está entre ellas.
Mensaje que devuelve la API: This API key cannot be used from this IP address. The address we saw is in `meta.clientIp`: call from one of the networks allowed for the key, or use a key that allows this one.
403ACCOUNT_NOT_ACTIVE
Tu organización está suspendida o cerrada.
Mensaje que devuelve la API: The organization associated with this API key is not active. Please contact support.

Límites de uso

429Se excedió el límite de solicitudes.

429RATE_TPS_EXCEEDED
Excediste el cupo de tu organización para este endpoint.
Mensaje que devuelve la API: You have exceeded the allowed request rate for this endpoint. Please wait before retrying.

Recurso inexistente

Este endpoint no declara respuestas de este tipo.

Errores internos y disponibilidad

504La consulta tardó demasiado y la detuvimos. Pasa con consultas muy grandes para organizaciones con muchos enlaces: acótala (menos días, menos secciones, más filtros). Repetirla igual no ayuda.

504INFRA_DB_QUERY_TIMEOUT
Una consulta interna tardó demasiado y se cortó.

Otras respuestas