Hablame
POST/api/v6/urlshortener/links

Crear un enlace corto

Publica un enlace corto en uno de tus dominios, con código generado o alias propio.

Alcance y límites

Alcance

API key con el servicio urlshortener habilitado

Límite de uso

35 solicitudes por segundo

Idempotencia

Admite Idempotency-Key

  • La URL de destino admite hasta 2048 caracteres.
  • Se rechazan destinos que apunten a hosts privados o reservados.

Crea un enlace corto en uno de tus dominios. El código se genera automáticamente (base36, 7 caracteres) salvo que envíes un alias propio. Los códigos son únicos por dominio: el mismo alias puede existir en dos dominios distintos.

Cabeceras

Idempotency-Key
stringopcional
Llave de idempotencia opcional (1 a 255 caracteres de A-Za-z0-9_-). Repetir la misma operación con la misma llave devuelve la respuesta original sin volver a ejecutarla. Ver la guía de idempotencia.

Cuerpo de la petición

application/json
url
stringobligatorio
URL de destino. Absoluta http o https, máximo 2048 caracteres. Se rechazan hosts privados o reservados.
domain
stringopcional
Dominio donde publicar. Debe estar disponible para tu cuenta (ver GET /api/v6/urlshortener/domains). Por defecto, tu dominio predeterminado.
alias
stringopcional
Código personalizado opcional (3 a 32 caracteres: minúsculas, dígitos, - y _). Debe estar libre en el dominio y no ser una palabra reservada.
expiresAt
stringopcional
Expiración opcional en ISO-8601, siempre futura. Después de esa fecha el enlace responde 410.
{
  "url": "https://example.com/landing?utm_source=sms",
  "domain": "go.acme.co",
  "alias": "spring-sale"
}

Respuestas

201

Enlace creado. En el caso extremo de que la relectura inmediata falle, data trae solo code y domain.

{
  "success": true,
  "data": {
    "id": 1024,
    "code": "a1b2c3d",
    "domain": "go.acme.co",
    "shortUrl": "https://go.acme.co/a1b2c3d",
    "longUrl": "https://example.com/landing?utm_source=sms",
    "alias": false,
    "active": true,
    "expiresAt": null,
    "createdAt": "2026-06-01T15:04:05Z",
    "clicks": 0,
    "uniqueClicks": 0,
    "lastClickAt": null
  },
  "meta": {
    "requestId": "8f0c0e2a4b1d4c8fae2b7a91e0c5d3f6",
    "timestamp": "2026-06-01T15:04:05+00:00",
    "responseTimeMs": 7.2
  }
}
400

Entrada inválida (URL de destino, alias, expiración o dominio), o llave de idempotencia con formato incorrecto.

401

Credenciales inválidas o faltantes.

403

La organización está en modo solo lectura, o no puede crear el enlace.

409

El alias ya está en uso en este dominio, o una petición con la misma llave de idempotencia sigue en proceso.

422

La llave de idempotencia se reusó con un cuerpo distinto.

429

Se excedió el límite de solicitudes.

Errores posibles

Códigos que este endpoint puede devolver en error.code. El detalle completo está en el catálogo.

401AUTH_REQUIREDNo se envió un token Bearer y cada llamada lo requiere.401AUTH_INVALID_KEYLa API key no se reconoce: formato equivocado, revocada o vencida.401AUTH_SERVICE_NOT_ALLOWEDLa key no tiene permitido el servicio detrás de este endpoint.403ACCOUNT_READ_ONLYModo solo lectura: solo pasan GET, HEAD y OPTIONS.400URL_INVALIDLa URL de destino está mal formada.400URL_SCHEME_NOT_ALLOWEDSolo se admiten destinos http y https.400URL_TOO_LONGLa URL de destino supera el largo máximo.400URL_BLOCKED_HOSTEl host de destino es privado o reservado.400ALIAS_INVALIDEl alias no cumple el formato permitido.409ALIAS_TAKENEl alias ya está en uso en este dominio.409ALIAS_RESERVEDEl alias es una palabra reservada.400EXPIRES_AT_INVALID`expiresAt` debe ser una fecha ISO futura.400DOMAIN_NOT_ALLOWEDEl dominio elegido no está disponible para tu cuenta.500CODE_GENERATION_FAILEDNo se pudo asignar un código único.400IDEMPOTENCY_KEY_INVALIDLa llave de idempotencia no cumple el formato.409IDEMPOTENCY_IN_PROGRESSLa primera petición con esa llave sigue en proceso.422IDEMPOTENCY_KEY_REUSEDLa llave ya existe, pero con un cuerpo distinto.429RATE_TPS_EXCEEDEDExcediste el cupo de tu organización para este endpoint.
Ver el catálogo completo
POST /api/v6/urlshortener/links
curl -X POST 'https://developers.hablame.co/api/v6/urlshortener/links' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer hk_TU_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{"url":"https://example.com/landing?utm_source=sms","domain":"go.acme.co","alias":"spring-sale"}'

Try-It

Ejecuta la petición contra la API real con tu propia API key.

La key se usa solo en tu navegador para esta petición. No se guarda ni se envía a ningún otro lado.

Parámetros

Llave de idempotencia opcional (1 a 255 caracteres de A-Za-z0-9_-). Repetir la misma operación con la misma llave devuelve la respuesta original sin volver a ejecutarla. Ver la guía de idempotencia.

Cuerpo de la petición

URL de destino. Absoluta http o https, máximo 2048 caracteres. Se rechazan hosts privados o reservados.

Dominio donde publicar. Debe estar disponible para tu cuenta (ver GET /api/v6/urlshortener/domains). Por defecto, tu dominio predeterminado.

Código personalizado opcional (3 a 32 caracteres: minúsculas, dígitos, - y _). Debe estar libre en el dominio y no ser una palabra reservada.

Expiración opcional en ISO-8601, siempre futura. Después de esa fecha el enlace responde 410.

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

Respuesta

Todavía no has enviado ninguna petición.