Saltar al contenido

Endpoints

Endpoints

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

GET/api/v6/urlshortener/overview

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

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/Bogota).

  • inventory es una foto del momento y no depende del rango: los enlaces vivos por estado (expired son los activos con el vencimiento ya pasado), los alias, los que nunca han recibido una visita y las visitas de toda la vida.
  • totals es lo que pasó en el rango, y today, lo mismo para hoy. El periodo anterior se pide con compare=previous: entonces llegan previous, previousTotals y, con series, 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 en null.
  • Los bloques opcionales se piden en include. Los que no pides llegan en null; los que pides sin datos, vacíos.

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,top,recent 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.

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: 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

NombreTipoDescripción y reglas
fromOpcionalstring

Primer día de la ventana, AAAA-MM-DD en hora de Colombia, incluido. Por defecto, 29 días antes de to (la ventana es de 30 días).

Formato:dateEjemplo:2026-09-01

toOpcionalstring

Último día de la ventana, AAAA-MM-DD en hora de Colombia, incluido. Por defecto, hoy.

Formato:dateEjemplo:2026-09-23

granularityOpcionalstring

Tamaño de cada punto de la serie. day admite ventanas de hasta 366 días; hour, de hasta 31.

Valores permitidos:day hourValor por omisión:day

compareOpcionalstring

previous agrega el periodo anterior de igual longitud (previous, previousTotals y, con series, previousSeries). none, o no enviarlo, lo omite. Hasta el 2026-09-30 el valor por defecto era previous.

Valores permitidos:previous noneValor por omisión:none

includeOpcionalstring

Bloques opcionales, separados por coma: series, top, recent, dimensions, heatmap. Por defecto series,top,recent. Un nombre que no existe responde 400.

Ejemplo:series,top,recent,dimensions,heatmap

dimensionsOpcionalstring

Dimensiones de desglose, separadas por coma: country, subdivision, city, device, os, browser, referrer. Por defecto country,device,os,browser,referrer. Los nombres que no existen se ignoran.

Ejemplo:country,device,referrer

topOpcionalinteger

Cuántos valores trae cada dimensión (y cada ranking). Máximo 100.

Valor por omisión:10Mínimo:1Máximo:100

Encabezados HTTP

NombreTipoDescripción y reglas
AuthorizationObligatoriostring

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

Resumen de la organización. El ejemplo es con compare=previous.

Ejemplo de respuesta
{
  "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

NombreTipoDescripción y reglas
successSiempre presenteboolean

dataSiempre presenteobject

data.rangeSiempre presenteobject

data.range.fromSiempre presentestring

Formato:date

data.range.toSiempre presentestring

Formato:date

data.range.granularitySiempre presentestring

Valores permitidos:day hour

data.range.timezoneSiempre presentestring

Ejemplo:America/Bogota

data.previousSiempre presenteobject

El periodo anterior, o null si no se pidió compare=previous.

Puede llegar en null.

data.previous.fromSiempre presentestring

Formato:date

data.previous.toSiempre presentestring

Formato:date

data.inventorySiempre presenteobject

Foto del momento de los enlaces vivos.

data.inventory.totalSiempre presenteinteger

data.inventory.activeSiempre presenteinteger

Activos y sin vencer.

data.inventory.expiredSiempre presenteinteger

Activos con el vencimiento ya pasado.

data.inventory.disabledSiempre presenteinteger

data.inventory.blockedSiempre presenteinteger

Bloqueados por Hablame. total los incluye.

data.inventory.aliasesSiempre presenteinteger

data.inventory.neverClickedSiempre presenteinteger

Nunca han recibido una visita.

data.inventory.clicksSiempre presenteinteger

Visitas de toda la vida.

data.inventory.uniqueClicksSiempre presenteinteger

data.todaySiempre presenteobject

Lo que pasó en una ventana de días.

data.today.linksCreatedSiempre presenteinteger

Enlaces creados en la ventana, incluidos los que después se eliminaron.

data.today.clicksSiempre presenteinteger

Visitas en la ventana.

data.today.uniqueClicksSiempre presenteinteger

Suma de las visitas únicas de cada día de la ventana.

data.today.linksWithClicksSiempre presenteinteger

Enlaces que recibieron al menos una visita en la ventana.

data.totalsSiempre presenteobject

Lo que pasó en una ventana de días.

data.totals.linksCreatedSiempre presenteinteger

Enlaces creados en la ventana, incluidos los que después se eliminaron.

data.totals.clicksSiempre presenteinteger

Visitas en la ventana.

data.totals.uniqueClicksSiempre presenteinteger

Suma de las visitas únicas de cada día de la ventana.

data.totals.linksWithClicksSiempre presenteinteger

Enlaces que recibieron al menos una visita en la ventana.

data.previousTotalsSiempre presenteobject

Lo que pasó en una ventana de días.

Puede llegar en null.

data.previousTotals.linksCreatedSiempre presenteinteger

Enlaces creados en la ventana, incluidos los que después se eliminaron.

data.previousTotals.clicksSiempre presenteinteger

Visitas en la ventana.

data.previousTotals.uniqueClicksSiempre presenteinteger

Suma de las visitas únicas de cada día de la ventana.

data.previousTotals.linksWithClicksSiempre presenteinteger

Enlaces que recibieron al menos una visita en la ventana.

data.seriesSiempre presentearray<object>

Puede llegar en null.

data.series[].atSiempre presentestring

El día (AAAA-MM-DD) o la hora (AAAA-MM-DDTHH:00:00), en hora de Colombia y sin zona.

Ejemplo:2026-09-23

data.series[].linksCreatedSiempre presenteinteger

data.series[].clicksSiempre presenteinteger

data.series[].uniqueClicksSiempre presenteinteger

data.previousSeriesSiempre presentearray<object>

Puede llegar en null.

data.previousSeries[].atSiempre presentestring

El día (AAAA-MM-DD) o la hora (AAAA-MM-DDTHH:00:00), en hora de Colombia y sin zona.

Ejemplo:2026-09-23

data.previousSeries[].linksCreatedSiempre presenteinteger

data.previousSeries[].clicksSiempre presenteinteger

data.previousSeries[].uniqueClicksSiempre presenteinteger

data.topLinksSiempre presentearray<object>

Puede llegar en null.

data.topLinks[].domainSiempre presentestring

data.topLinks[].codeSiempre presentestring

data.topLinks[].shortUrlSiempre presentestring

Formato:uri

data.topLinks[].longUrlSiempre presentestring

Formato:uri

data.topLinks[].statusSiempre presentestring

Valores permitidos:active disabled blocked

data.topLinks[].expiresAtSiempre presentestring

Puede llegar en null.

Formato:date-time

data.topLinks[].clicksSiempre presenteinteger

data.topLinks[].uniqueClicksSiempre presenteinteger

data.topLinks[].lastClickAtSiempre presentestring

Puede llegar en null.

Formato:date-time

data.dimensionsSiempre presenteobject

Puede llegar en null.

data.dimensions.{cualquier clave}array<object>

data.dimensions.{cualquier clave}[].valueSiempre presentestring

El valor tal como se registró (CO, mobile, Chrome, www.facebook.com…), o __other para la suma de lo que quedó fuera del top.

data.dimensions.{cualquier clave}[].clicksSiempre presenteinteger

data.recentSiempre presenteobject

Puede llegar en null.

data.recent.createdSiempre presentearray<object>

data.recent.created[].domainSiempre presentestring

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.recent.created[].codeSiempre presentestring

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.recent.created[].shortUrlSiempre presentestring

La URL corta completa: siempre https://{domain}/{code}.

Formato:uri

data.recent.created[].longUrlSiempre presentestring

URL de destino.

Formato:uri

data.recent.created[].isAliasSiempre presenteboolean

true cuando el código lo eligió quien creó el enlace (campo code al crearlo); false cuando lo generó el servicio.

data.recent.created[].statusSiempre presentestring

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.recent.created[].domainStatusstring

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.recent.created[].expiresAtSiempre presentestring

Vencimiento en UTC, o null si no vence.

Puede llegar en null.

Formato:date-time

data.recent.created[].createdAtSiempre presentestring

Fecha de creación, en UTC.

Formato:date-time

data.recent.created[].clicksSiempre presenteinteger

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.recent.created[].uniqueClicksSiempre presenteinteger

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.recent.created[].firstClickAtSiempre presentestring

Primera visita, en UTC. null si nunca ha recibido una.

Puede llegar en null.

Formato:date-time

data.recent.created[].lastClickAtSiempre presentestring

Última visita, en UTC. null si nunca ha recibido una.

Puede llegar en null.

Formato:date-time

data.recent.clickedSiempre presentearray<object>

data.recent.clicked[].domainSiempre presentestring

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.recent.clicked[].codeSiempre presentestring

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.recent.clicked[].shortUrlSiempre presentestring

La URL corta completa: siempre https://{domain}/{code}.

Formato:uri

data.recent.clicked[].longUrlSiempre presentestring

URL de destino.

Formato:uri

data.recent.clicked[].isAliasSiempre presenteboolean

true cuando el código lo eligió quien creó el enlace (campo code al crearlo); false cuando lo generó el servicio.

data.recent.clicked[].statusSiempre presentestring

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.recent.clicked[].domainStatusstring

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.recent.clicked[].expiresAtSiempre presentestring

Vencimiento en UTC, o null si no vence.

Puede llegar en null.

Formato:date-time

data.recent.clicked[].createdAtSiempre presentestring

Fecha de creación, en UTC.

Formato:date-time

data.recent.clicked[].clicksSiempre presenteinteger

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.recent.clicked[].uniqueClicksSiempre presenteinteger

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.recent.clicked[].firstClickAtSiempre presentestring

Primera visita, en UTC. null si nunca ha recibido una.

Puede llegar en null.

Formato:date-time

data.recent.clicked[].lastClickAtSiempre presentestring

Última visita, en UTC. null si nunca ha recibido una.

Puede llegar en null.

Formato:date-time

data.heatmapSiempre presenteobject

Puede llegar en null.

data.heatmap.fromSiempre presentestring

Formato:date

data.heatmap.toSiempre presentestring

Formato:date

data.heatmap.cellsSiempre presentearray<object>

data.heatmap.cells[].weekdaySiempre presenteinteger

Día de la semana: 1 lunes … 7 domingo.

data.heatmap.cells[].hourSiempre presenteinteger

Hora de 0 a 23, en hora de Colombia.

data.heatmap.cells[].clicksSiempre presenteinteger

metaSiempre presenteobject

Metadatos de la respuesta.

meta.requestIdSiempre presentestring

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.clientIpSiempre presentestring

IP con la que la API vio tu solicitud. Útil si tu API key solo admite ciertas redes.

Ejemplo:203.0.113.45

meta.timestampSiempre presentestring

Fecha y hora en que se construyó la respuesta (ISO 8601 con offset).

Formato:date-timeEjemplo:2026-06-04T19:43:59+00:00

meta.responseTimeMsSiempre presentenumber

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
NombreTipoDescripción y reglas
successSiempre presenteboolean

Valor fijo:false

metaSiempre presenteobject

Metadatos de la respuesta.

meta.requestIdSiempre presentestring

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.clientIpSiempre presentestring

IP con la que la API vio tu solicitud. Útil si tu API key solo admite ciertas redes.

Ejemplo:203.0.113.45

meta.timestampSiempre presentestring

Fecha y hora en que se construyó la respuesta (ISO 8601 con offset).

Formato:date-timeEjemplo:2026-06-04T19:43:59+00:00

meta.responseTimeMsSiempre presentenumber

Tiempo (ms) que tomó procesar la solicitud en el servidor.

Ejemplo:4.24

errorSiempre presenteobject

error.codeSiempre presentestring

Identificador estable en UPPER_SNAKE_CASE. Los clientes ramifican sobre este valor.

Ejemplo:AUTH_REQUIRED

error.legacyCodeinteger

Código numérico legacy v5, solo cuando hay puente. Se omite en los códigos nacidos en v6.

Ejemplo:40002

error.typeSiempre presentestring

URL a la documentación del error.

Formato:uriEjemplo:https://developers.hablame.co/docs/v6/errors/auth-required

error.messageSiempre presentestring

Texto legible en inglés. Es para el log del desarrollador, no para el usuario final: no lo parsees.

error.detailsSiempre presentearray<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 compare o include que no existe.
  • 400STATS_RANGE_INVALID

    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.
  • 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.

Otras respuestas

Este endpoint no declara respuestas de este tipo.

Ver en el catálogo de errores

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=previous. Si lo usas, agrega el parámetro.

Documentación relacionada

¿Necesitas ayuda?

¿Te sirvió esta página?

Ver todos los canales de soporte

Pide ayuda sobre esto: este endpoint

Armamos un mensaje con los datos que ayudan a revisar tu caso. Léelo, complétalo y envíalo tú: no se manda nada solo.

El mensaje nunca lleva tu clave de API ni contraseñas.