Nombre
Resumen de la organización
Inventario, actividad del rango frente al periodo anterior, evolución, más visitados y desgloses de toda tu organización.
Método HTTP y ruta
/ api/ v6/ urlshortener/ overviewhttps:
Qué pasa al ejecutarlo
- Solo consulta: no cambia datos de tu organización.
- La llamada no se cobra.
Qué hace
Todo el acortador de tu organización en una sola llamada, sin recorrer los enlaces uno por uno. Los días y las horas son de Colombia (America/).
inventoryes una foto del momento y no depende del rango: los enlaces vivos por estado (expiredson los activos con el vencimiento ya pasado), los alias, los que nunca han recibido una visita y las visitas de toda la vida.totalses lo que pasó en el rango, ytoday, lo mismo para hoy. El periodo anterior se pide concompare=: entonces lleganprevious previous,previousTotalsy, conseries,previousSeries, para el periodo anterior de igual longitud (30 días hasta hoy se comparan con los 30 anteriores, no con el mes calendario). Sin pedirlo llegan ennull.- Los bloques opcionales se piden en
include. Los que no pides llegan ennull; los que pides sin datos, vacíos.
Bloque de include | Qué agrega |
|---|---|
series | series (y previousSeries si comparas): enlaces creados, visitas y únicas por día o por hora, con los puntos sin actividad en cero. |
top | topLinks: los enlaces con más visitas dentro del rango, sin los eliminados. |
recent | recent: los 5 últimos enlaces creados y los 5 últimos visitados. |
dimensions | dimensions: los desgloses de dimensions sumando todos tus enlaces, con las mismas reglas que las estadísticas de un enlace. |
heatmap | heatmap: las visitas por día de la semana y hora (168 celdas). Con un rango de más de 31 días, se calcula sobre sus últimos 31, y la respuesta dice cuáles. |
El resumen recorre todos los enlaces de tu organización, así que su cupo va según lo que cuesta: cada resumen gasta unidades de un cupo de 150 por minuto de tu organización. Gasta 2 por la consulta; 1 por cada bloque que no depende del largo del rango (inventory, today, recent, heatmap), y, por cada 31 días del rango, 1 por cada bloque que lo recorre (totals, series, top, dimensions, y los del periodo anterior si comparas). Un resumen de 30 días con series, gasta 8; comparando, 10; uno de un año con todo, 78. Sin unidades, 429 con Retry-After. Y como mucho dos resúmenes de tu organización se calculan a la vez: el que llega con dos en curso espera unos segundos y, si no le toca turno, recibe 429.
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.
Autenticación y permisos
- Envía tu API key en la cabecera
Authorizationcon el esquema Bearer.
Quién puede llamarlo: Una API key con el servicio urlshortener habilitado.
Límites y consideraciones operativas
Límite de uso: 120 solicitudes por minuto.
- Ventanas de hasta 366 días por día, y de hasta 31 días por hora.
- Hasta 100 valores por dimensión y por ranking.
- Cupo por costo: 150 unidades por minuto por organización (ver arriba). Dos resúmenes a la vez por organización.
Parámetros de ruta
Este endpoint no tiene parámetros de ruta.
Parámetros de consulta
| Nombre | Tipo | Descripción y reglas |
|---|---|---|
fromOpcional | string | Primer día de la ventana, Formato: |
toOpcional | string | Último día de la ventana, Formato: |
granularityOpcional | string | Tamaño de cada punto de la serie. Valores permitidos: |
compareOpcional | string |
Valores permitidos: |
includeOpcional | string | Bloques opcionales, separados por coma: Ejemplo: |
dimensionsOpcional | string | Dimensiones de desglose, separadas por coma: Ejemplo: |
topOpcional | integer | Cuántos valores trae cada dimensión (y cada ranking). Máximo 100. Valor por omisión: |
Encabezados HTTP
| Nombre | Tipo | Descripción y reglas |
|---|---|---|
AuthorizationObligatorio | string | Tu API key con el esquema Bearer. Ejemplo: |
Cuerpo de la petición
Este endpoint no recibe cuerpo en la petición.
Respuestas satisfactorias
200
Resumen de la organización. El ejemplo es con compare=.
{
"success": true,
"data": {
"range": { "from": "2026-08-25", "to": "2026-09-23", "granularity": "day", "timezone": "America/Bogota" },
"previous": { "from": "2026-07-26", "to": "2026-08-24" },
"inventory": {
"total": 1250, "active": 1190, "expired": 40, "disabled": 20, "blocked": 0,
"aliases": 35, "neverClicked": 610, "clicks": 48210, "uniqueClicks": 30115
},
"today": { "linksCreated": 42, "clicks": 1310, "uniqueClicks": 902, "linksWithClicks": 118 },
"totals": { "linksCreated": 820, "clicks": 21400, "uniqueClicks": 14020, "linksWithClicks": 540 },
"previousTotals": { "linksCreated": 610, "clicks": 17950, "uniqueClicks": 11800, "linksWithClicks": 455 },
"series": [
{ "at": "2026-08-25", "linksCreated": 25, "clicks": 690, "uniqueClicks": 455 }
],
"previousSeries": [
{ "at": "2026-07-26", "linksCreated": 18, "clicks": 540, "uniqueClicks": 360 }
],
"topLinks": [
{
"domain": "h0b.co", "code": "promo-septiembre", "shortUrl": "https://h0b.co/promo-septiembre",
"longUrl": "https://example.com/promo", "status": "active", "expiresAt": null,
"clicks": 3120, "uniqueClicks": 2210, "lastClickAt": "2026-09-23T18:22:10Z"
}
],
"dimensions": null,
"recent": { "created": [], "clicked": [] },
"heatmap": 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 |
|---|---|---|
successSiempre presente | boolean | |
dataSiempre presente | object | |
data.Siempre presente | object | |
data.Siempre presente | string | Formato: |
data.Siempre presente | string | Formato: |
data.Siempre presente | string | Valores permitidos: |
data.Siempre presente | string | Ejemplo: |
data.Siempre presente | object | El periodo anterior, o Puede llegar en |
data.Siempre presente | string | Formato: |
data.Siempre presente | string | Formato: |
data.Siempre presente | object | Foto del momento de los enlaces vivos. |
data.Siempre presente | integer | |
data.Siempre presente | integer | Activos y sin vencer. |
data.Siempre presente | integer | Activos con el vencimiento ya pasado. |
data.Siempre presente | integer | |
data.Siempre presente | integer | Bloqueados por Hablame. |
data.Siempre presente | integer | |
data.Siempre presente | integer | Nunca han recibido una visita. |
data.Siempre presente | integer | Visitas de toda la vida. |
data.Siempre presente | integer | |
data.Siempre presente | object | Lo que pasó en una ventana de días. |
data.Siempre presente | integer | Enlaces creados en la ventana, incluidos los que después se eliminaron. |
data.Siempre presente | integer | Visitas en la ventana. |
data.Siempre presente | integer | Suma de las visitas únicas de cada día de la ventana. |
data.Siempre presente | integer | Enlaces que recibieron al menos una visita en la ventana. |
data.Siempre presente | object | Lo que pasó en una ventana de días. |
data.Siempre presente | integer | Enlaces creados en la ventana, incluidos los que después se eliminaron. |
data.Siempre presente | integer | Visitas en la ventana. |
data.Siempre presente | integer | Suma de las visitas únicas de cada día de la ventana. |
data.Siempre presente | integer | Enlaces que recibieron al menos una visita en la ventana. |
data.Siempre presente | object | Lo que pasó en una ventana de días. Puede llegar en |
data.Siempre presente | integer | Enlaces creados en la ventana, incluidos los que después se eliminaron. |
data.Siempre presente | integer | Visitas en la ventana. |
data.Siempre presente | integer | Suma de las visitas únicas de cada día de la ventana. |
data.Siempre presente | integer | Enlaces que recibieron al menos una visita en la ventana. |
data.Siempre presente | array<object> | Puede llegar en |
data.Siempre presente | string | El día ( Ejemplo: |
data.Siempre presente | integer | |
data.Siempre presente | integer | |
data.Siempre presente | integer | |
data.Siempre presente | array<object> | Puede llegar en |
data.Siempre presente | string | El día ( Ejemplo: |
data.Siempre presente | integer | |
data.Siempre presente | integer | |
data.Siempre presente | integer | |
data.Siempre presente | array<object> | Puede llegar en |
data.Siempre presente | string | |
data.Siempre presente | string | |
data.Siempre presente | string | Formato: |
data.Siempre presente | string | Formato: |
data.Siempre presente | string | Valores permitidos: |
data.Siempre presente | string | Puede llegar en Formato: |
data.Siempre presente | integer | |
data.Siempre presente | integer | |
data.Siempre presente | string | Puede llegar en Formato: |
data.Siempre presente | object | Puede llegar en |
data. | array<object> | |
data.Siempre presente | string | El valor tal como se registró ( |
data.Siempre presente | integer | |
data.Siempre presente | object | Puede llegar en |
data.Siempre presente | array<object> | |
data.Siempre presente | string | Dominio del enlace, en minúsculas. Si el dominio ya no es de tu organización ( |
data.Siempre presente | string | Código del enlace, en minúsculas: 7 caracteres |
data.Siempre presente | string | La URL corta completa: siempre Formato: |
data.Siempre presente | string | URL de destino. Formato: |
data.Siempre presente | boolean |
|
data.Siempre presente | string |
Valores permitidos: |
data. | string | Si el dominio deja abrir el enlace, aparte de su propio Valores permitidos: |
data.Siempre presente | string | Vencimiento en UTC, o Puede llegar en Formato: |
data.Siempre presente | string | Fecha de creación, en UTC. Formato: |
data.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.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.Siempre presente | string | Primera visita, en UTC. Puede llegar en Formato: |
data.Siempre presente | string | Última visita, en UTC. Puede llegar en Formato: |
data.Siempre presente | array<object> | |
data.Siempre presente | string | Dominio del enlace, en minúsculas. Si el dominio ya no es de tu organización ( |
data.Siempre presente | string | Código del enlace, en minúsculas: 7 caracteres |
data.Siempre presente | string | La URL corta completa: siempre Formato: |
data.Siempre presente | string | URL de destino. Formato: |
data.Siempre presente | boolean |
|
data.Siempre presente | string |
Valores permitidos: |
data. | string | Si el dominio deja abrir el enlace, aparte de su propio Valores permitidos: |
data.Siempre presente | string | Vencimiento en UTC, o Puede llegar en Formato: |
data.Siempre presente | string | Fecha de creación, en UTC. Formato: |
data.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.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.Siempre presente | string | Primera visita, en UTC. Puede llegar en Formato: |
data.Siempre presente | string | Última visita, en UTC. Puede llegar en Formato: |
data.Siempre presente | object | Puede llegar en |
data.Siempre presente | string | Formato: |
data.Siempre presente | string | Formato: |
data.Siempre presente | array<object> | |
data.Siempre presente | integer | Día de la semana: |
data.Siempre presente | integer | Hora de 0 a 23, en hora de Colombia. |
data.Siempre presente | integer | |
metaSiempre presente | object | Metadatos de la respuesta. |
meta.Siempre presente | string | Identificador único de la solicitud (16 caracteres hexadecimales). Es el mismo de la cabecera Ejemplo: |
meta.Siempre presente | string | IP con la que la API vio tu solicitud. Útil si tu API key solo admite ciertas redes. Ejemplo: |
meta.Siempre presente | string | Fecha y hora en que se construyó la respuesta (ISO 8601 con offset). Formato: |
meta.Siempre presente | number | Tiempo (ms) que tomó procesar la solicitud en el servidor. Ejemplo: |
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 |
|---|---|---|
successSiempre presente | boolean | Valor fijo: |
metaSiempre presente | object | Metadatos de la respuesta. |
meta.Siempre presente | string | Identificador único de la solicitud (16 caracteres hexadecimales). Es el mismo de la cabecera Ejemplo: |
meta.Siempre presente | string | IP con la que la API vio tu solicitud. Útil si tu API key solo admite ciertas redes. Ejemplo: |
meta.Siempre presente | string | Fecha y hora en que se construyó la respuesta (ISO 8601 con offset). Formato: |
meta.Siempre presente | number | Tiempo (ms) que tomó procesar la solicitud en el servidor. Ejemplo: |
errorSiempre presente | object | |
error.Siempre presente | string | Identificador estable en UPPER_SNAKE_CASE. Los clientes ramifican sobre este valor. Ejemplo: |
error. | integer | Código numérico legacy v5, solo cuando hay puente. Se omite en los códigos nacidos en v6. Ejemplo: |
error.Siempre presente | string | URL a la documentación del error. Formato: |
error.Siempre presente | string | Texto legible en inglés. Es para el log del desarrollador, no para el usuario final: no lo parsees. |
error.Siempre presente | array<object> | Contexto estructurado (validaciones, recurso afectado). Arreglo vacío cuando no hay contexto extra. |
Validación
- 400Una fecha inválida o una ventana mayor a la permitida, o un valor de
compareoincludeque no existe.
El rango o la granularidad de estadísticas son inválidos.
Mensaje que devuelve la API: The requested statistics range or granularity is invalid.
400VALIDATION_INVALID_PARAMETER
Un parámetro o un campo del cuerpo no es válido.
Autenticación
- 401Credenciales inválidas o faltantes.
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>`.
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.
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.
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.
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.
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.
Una consulta interna tardó demasiado y se cortó.
Otras respuestas
Este endpoint no declara respuestas de este tipo.
Consideraciones especiales
Las visitas únicas son la suma de las de cada día, no personas distintas. Las respuestas pueden tener hasta un minuto de antigüedad (cabecera X-Cache).
Cambio del 2026-09-30: antes el periodo anterior llegaba siempre; ahora solo con compare=. Si lo usas, agrega el parámetro.