Nombre
Actualizar un enlace corto
Cambia el destino, el estado o el vencimiento. El dominio y el código no cambian.
Método HTTP y ruta
/https:
Qué pasa al ejecutarlo
- Cambia datos de tu organización.
- La llamada no se cobra.
- Si con este cambio el enlace vuelve a redirigir (lo reactivas, o le amplías o quitas el vencimiento), cada visita de una persona se vuelve a cobrar (las de robots y las vistas previas no).
Qué hace
Cambia la URL de destino (longUrl, que se revalida como al crear), el estado (status) o el vencimiento (expiresAt). Envía solo lo que quieras cambiar; hace falta al menos un campo. El dominio y el código no se pueden cambiar: romperían todas las URL cortas ya repartidas. Editar no tiene costo.
Cada cambio queda registrado con el valor anterior, el nuevo y quién lo hizo (la API key o el usuario del portal). Un enlace bloqueado por Hablame (status:) no se puede editar: responde 409 LINK_BLOCKED.
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: 35 solicitudes por segundo.
Parámetros de ruta
| Nombre | Tipo | Descripción y reglas |
|---|---|---|
domainObligatorio | string | Dominio del enlace, tal como lo devuelve la API en Ejemplo: |
codeObligatorio | string | Código o alias del enlace. Se compara en minúsculas. Ejemplo: |
Parámetros de consulta
| Nombre | Tipo | Descripción y reglas |
|---|---|---|
domainStatusOpcional | string | Con Valores permitidos: |
Encabezados HTTP
| Nombre | Tipo | Descripción y reglas |
|---|---|---|
AuthorizationObligatorio | string | Tu API key con el esquema Bearer. Ejemplo: |
Content-TypeObligatorio | string | Tipo del cuerpo que envías. Valor fijo: |
Cuerpo de la petición
Tipo de contenido:application/jsonObligatorio
| Nombre | Tipo | Descripción y reglas |
|---|---|---|
longUrlOpcional | string | Nueva URL de destino. Mismas reglas que al crear. Formato: |
statusOpcional | string |
Valores permitidos: |
expiresAtOpcional | string | Nuevo vencimiento, siempre futuro. Sin zona horaria se lee en hora de Colombia ( Formato: |
{
"status": "disabled"
}Respuestas satisfactorias
200
Enlace actualizado, tal como quedó.
{
"success": true,
"data": {
"domain": "h0b.co",
"code": "a1b2c3d",
"shortUrl": "https://h0b.co/a1b2c3d",
"longUrl": "https://example.com/landing?utm_source=sms",
"isAlias": false,
"status": "active",
"domainStatus": "active",
"expiresAt": null,
"createdAt": "2026-09-23T15:04:05Z",
"clicks": 0,
"uniqueClicks": 0,
"firstClickAt": null,
"lastClickAt": 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 | 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: |
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
- 400No se envió nada que cambiar, un campo no tiene el tipo correcto, o un valor es inválido.
No se envió ningún campo actualizable.
Mensaje que devuelve la API: No updatable fields were provided.
400VALIDATION_INVALID_PARAMETER
Un parámetro o un campo del cuerpo no es válido.
400URL_INVALID
La URL de destino está mal formada.
Mensaje que devuelve la API: The destination URL is not valid. Provide an absolute `http`/`https` URL with a host.
Solo se admiten destinos http y https.
Mensaje que devuelve la API: Only `http` and `https` destination URLs are allowed.
400URL_TOO_LONG
La URL de destino supera el largo máximo.
Mensaje que devuelve la API: The destination URL exceeds the maximum allowed length.
El host de destino es privado o reservado.
Mensaje que devuelve la API: The destination host is not allowed (private, reserved, or loopback addresses are blocked).
expiresAtdebe ser una fecha ISO futura.Mensaje que devuelve la API: `expiresAt` must be a future ISO-8601 date-time.
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
- 404No existe un enlace de tu organización con ese dominio y código (o fue eliminado). Un enlace de otra organización también responde
404: no se revela que exista.
No hay un enlace con ese dominio y código.
Mensaje que devuelve la API: No short link was found for that domain and code.
Errores internos y disponibilidad
Este endpoint no declara respuestas de este tipo.
Otras respuestas
- 409El enlace está bloqueado por Hablame y no se puede cambiar.
409LINK_BLOCKED
El enlace está bloqueado por seguridad.
Consideraciones especiales
Las claves que no reconoce se ignoran: un cuerpo como {"active": (del contrato anterior) no cambia nada y responde 400 NOTHING_TO_UPDATE. Para desactivar, envía {"status":.
Una key con el acortador también crea y borra
El servicio urlshortener da todo el acortador: con él, la API key lista y consulta enlaces, y también los crea (cada alta se cobra), los edita, los borra y los restaura. No hay keys de solo lectura. Solo el propietario de tu organización crea las keys: si una no debe crear enlaces, no le des este servicio. Sin él, la key recibe 403 AUTH_SERVICE_NOT_ALLOWED.