Documentación de API

Acortador de URL

SDK

Además de la API REST, el SDK oficial para TypeScript y JavaScript gestiona la autenticación, la paginación y el filtrado de campos de las URLs.

Instalación

Instala el SDK de acortador de URLs desde npm. Puedes usar @ircg/uss para este servicio o @ircg/sdk para todos los servicios de IRCG.

typescript

	# Solo este servicio
	npm install @ircg/uss
	# O el meta-paquete
	npm install @ircg/sdk

Uso básico

Inicializa USSClient con tu API key y crea una URL corta. Los métodos seguros devuelven error en vez de lanzar una excepción.

typescript

	import { USSClient } from '@ircg/uss'
	
	const uss = new USSClient({ apiKey: API_KEY, lang: 'es' })
	const result = await uss.create({
		url: 'https://example.com/a/very/long/path',
		fields: ['urlKey', 'originalUrl'],
	})
	if (result.error) throw new Error(result.error.message)
	console.log('https://ircg.dev/l/' + result.shortenedUrl.urlKey)

Dry run

Configura dryRun: true para simular todas las operaciones remotas sin realizar solicitudes HTTP ni consumir créditos. Las listas regresan vacías y el cliente no conserva URLs acortadas entre llamadas.

typescript

	const uss = new USSClient({ apiKey: 'unused', dryRun: true })
	const result = await uss.create({
		url: 'https://example.com/a/very/long/path',
		fields: ['urlKey', 'originalUrl'],
	})
	if (result.error) throw new Error(result.error.message)
	console.log(result.shortenedUrl.urlKey) // "DR"

API REST

Método	Ruta	Descripción
GET	/api/v1/urls	Listar URLs acortadas.
POST	/api/v1/urls	Acortar una URL.
GET	/api/v1/urls/:urlKey	Consultar una URL acortada.
PUT	/api/v1/urls/:urlKey	Actualizar una URL acortada.
DELETE	/api/v1/urls/:urlKey	Eliminar una URL acortada.

Listar URLs acortadas GET

typescript

	import { USSClient } from '@ircg/uss'
	
	const uss = new USSClient({ apiKey: API_KEY, lang: 'es' })
	const result = await uss.getAll({ page: 1, amount: 50, fields: ['urlKey', 'originalUrl', 'visits'] })
	if (result.error) throw new Error(result.error.message)
	console.log(result.shortenedUrls, result.totalAmount)
	
	const response = await fetch('https://ircg.dev/api/v1/urls?fields=%5B%22urlKey%22%2C%22originalUrl%22%2C%22visits%22%5D', {
		headers: { Authorization: `Bearer ${API_KEY}`,
			'Accept-Language': 'es' },
	})
	if (!response.ok) throw new Error(`List failed: ${response.status}`)
	const data = await response.json()
	console.log(data.shortenedUrls, data.totalAmount)

Parámetros opcionales

https://ircg.dev/api/v1/urls?fields=["urlKey","originalUrl","visits"]&amount=100&page=3&ascending=true

Parámetro	Tipo	Valores permitidos	Por defecto	Descripción
fields	string	Arreglo JSON de nombres de campos	Todos los campos	Especifica qué campos incluir en la respuesta. Campos disponibles: `id`, `serviceId`, `urlKey`, `originalUrl`, `createdAt`, `updatedAt`, `visits` y `active`. Ejemplo: `?fields=["urlKey","originalUrl","visits"]`
amount	number	1 - 100	50	Útil para la paginación.
page	number	1 - 99999	1	Útil para la paginación.
ascending	boolean	true false	false	Ordena la lista tomando en cuenta la fecha de creación (`createdAt`).

Respuestas

200

Respuesta satisfactoria

400

Error en body o parámetros de la petición

401

Error de autenticación

404

No se encontró algún recurso

429

Demasiadas solicitudes

500

Error inesperado

Acortar URL POST

typescript

	import { USSClient } from '@ircg/uss'
	
	const uss = new USSClient({ apiKey: API_KEY, lang: 'es' })
	const result = await uss.create({ url: 'https://example.com/docs', fields: ['urlKey', 'originalUrl'] })
	if (result.error) throw new Error(result.error.message)
	console.log(result.shortenedUrl.urlKey)
	
	const response = await fetch('https://ircg.dev/api/v1/urls?fields=%5B%22urlKey%22%2C%22originalUrl%22%5D', {
		method: 'POST',
		headers: { Authorization: `Bearer ${API_KEY}`,
			'Accept-Language': 'es', 'Content-Type': 'application/json' },
		body: JSON.stringify({ url: 'https://example.com/docs' }),
	})
	if (!response.ok) throw new Error(`Create failed: ${response.status}`)
	const data = await response.json()
	console.log(data.shortenedUrl.urlKey)

Parámetros opcionales

https://ircg.dev/api/v1/urls?fields=["urlKey","originalUrl"]

Parámetro	Tipo	Valores permitidos	Por defecto	Descripción
fields	string	Arreglo JSON de nombres de campos	Todos los campos	Especifica qué campos incluir en la respuesta. Campos disponibles: `id`, `serviceId`, `urlKey`, `originalUrl`, `createdAt`, `updatedAt`, `visits` y `active`. Ejemplo: `?fields=["urlKey","originalUrl","visits"]`

Cuerpo

Campo	Tipo	Requerido	Por defecto	Descripción
url	string	Sí	-	La URL que se requiere acortar. Debe empezar por "https".

Respuestas

200

Respuesta satisfactoria

204

Respuesta satisfactoria (No content)

400

Error en body o parámetros de la petición

401

Error de autenticación

404

No se encontró algún recurso

429

Demasiadas solicitudes

500

Error inesperado

Obtener URL acortada GET

typescript

	import { USSClient } from '@ircg/uss'
	
	const uss = new USSClient({ apiKey: API_KEY, lang: 'es' })
	const urlKey = '2F'
	const result = await uss.getByKey({ urlKey, fields: ['urlKey', 'originalUrl', 'visits'] })
	if (result.error) throw new Error(result.error.message)
	console.log(result.shortenedUrl)
	
	const response = await fetch(`https://ircg.dev/api/v1/urls/${urlKey}?fields=%5B%22urlKey%22%2C%22originalUrl%22%2C%22visits%22%5D`, {
		headers: { Authorization: `Bearer ${API_KEY}`,
			'Accept-Language': 'es' },
	})
	if (!response.ok) throw new Error(`Read failed: ${response.status}`)
	const data = await response.json()
	console.log(data.shortenedUrl)

Segmento de ruta

https://ircg.dev/api/v1/urls/${urlKey}

https://ircg.dev/api/v1/urls/1C

Segmento	Tipo	Descripción
urlKey	string	Funciona como identificador único de cada URL acortada.

Parámetros opcionales

https://ircg.dev/api/v1/urls/1C?fields=["urlKey","originalUrl","visits"]

Parámetro	Tipo	Valores permitidos	Por defecto	Descripción
fields	string	Arreglo JSON de nombres de campos	Todos los campos	Especifica qué campos incluir en la respuesta. Campos disponibles: `id`, `serviceId`, `urlKey`, `originalUrl`, `createdAt`, `updatedAt`, `visits` y `active`. Ejemplo: `?fields=["urlKey","originalUrl","visits"]`

Respuestas

200

Respuesta satisfactoria

400

Error en body o parámetros de la petición

401

Error de autenticación

404

No se encontró algún recurso

429

Demasiadas solicitudes

500

Error inesperado

Actualizar URL acortada PUT

Se puede actualizar el campo active, al tener el valor false ya no ocurren las redirecciones.

typescript

	import { USSClient } from '@ircg/uss'
	
	const uss = new USSClient({ apiKey: API_KEY, lang: 'es' })
	const urlKey = '2F'
	const result = await uss.update({ urlKey, active: false, fields: ['urlKey', 'active', 'updatedAt'] })
	if (result.error) throw new Error(result.error.message)
	if ('shortenedUrl' in result) console.log(result.shortenedUrl)
	
	const response = await fetch(`https://ircg.dev/api/v1/urls/${urlKey}?fields=%5B%22urlKey%22%2C%22active%22%2C%22updatedAt%22%5D`, {
		method: 'PUT',
		headers: { Authorization: `Bearer ${API_KEY}`,
			'Accept-Language': 'es', 'Content-Type': 'application/json' },
		body: JSON.stringify({ active: false }),
	})
	if (!response.ok) throw new Error(`Update failed: ${response.status}`)
	console.log((await response.json()).shortenedUrl)

Segmento de ruta

https://ircg.dev/api/v1/urls/${urlKey}

https://ircg.dev/api/v1/urls/2M

Segmento	Tipo	Descripción
urlKey	string	Funciona como identificador único de cada URL acortada.

Parámetros opcionales

https://ircg.dev/api/v1/urls/2M?fields=["urlKey","originalUrl"]

Parámetro	Tipo	Valores permitidos	Por defecto	Descripción
fields	string	Arreglo JSON de nombres de campos	Todos los campos	Especifica qué campos incluir en la respuesta. Campos disponibles: `id`, `serviceId`, `urlKey`, `originalUrl`, `createdAt`, `updatedAt`, `visits` y `active`. Ejemplo: `?fields=["urlKey","originalUrl","visits"]`

Cuerpo

Campo	Tipo	Requerido	Por defecto	Descripción
active	boolean	No	false	Indica si la redirección está activa o no.

Respuestas

200

Respuesta satisfactoria

204

Respuesta satisfactoria (No content)

400

Error en body o parámetros de la petición

401

Error de autenticación

404

No se encontró algún recurso

429

Demasiadas solicitudes

500

Error inesperado

Eliminar URL acortada DELETE

typescript

	import { USSClient } from '@ircg/uss'
	
	const uss = new USSClient({ apiKey: API_KEY, lang: 'es' })
	const urlKey = 'abc123'
	const result = await uss.delete({ urlKey })
	if (result.error) throw new Error(result.error.message)
	console.log(result.success)
	
	const response = await fetch(`https://ircg.dev/api/v1/urls/${urlKey}`, {
		method: 'DELETE',
		headers: { Authorization: `Bearer ${API_KEY}`,
			'Accept-Language': 'es' },
	})
	if (!response.ok) throw new Error(`Delete failed: ${response.status}`)
	console.log(response.status)

Segmento de ruta

https://ircg.dev/api/v1/urls/abc123

Segmento	Tipo	Descripción
urlKey	string	Funciona como identificador único de cada URL acortada.

Respuestas

204

Respuesta satisfactoria (No content)

401

Error de autenticación

404

No se encontró algún recurso

429

Demasiadas solicitudes

500

Error inesperado

Límites y costos

Crear URLs cortas y procesar sus visitas no consumen créditos.
El límite predeterminado es de 60 solicitudes por 60 segundos y 1,000 por 3,600 segundos por API key; ambas ventanas se aplican de forma independiente. Puedes solicitar cambios a esos límites desde el panel.

Reportar abuso