Documentación

Referencia de la API

Crea y gestiona redireccionamientos, rutas personalizadas y códigos QR desde tu propio código. Una API REST pequeña, con JSON de entrada y de salida.

Descripción general

Todo lo que haces en el panel con redireccionamientos, rutas personalizadas y códigos QR también se puede hacer con la API: crear un redireccionamiento cuando un cliente se registra, añadir rutas de campaña desde un script o generar códigos QR para imprimir en lote.

URL base

https://api.redirect-301.com/v1

Formato

Cuerpo de solicitudes y respuestas en JSON (Content-Type: application/json). Fechas en UTC, ISO 8601.

Planes

Incluida en los planes Studio y Enterprise.

Mismas reglas

La API sigue las mismas reglas que el panel, como la cantidad de redireccionamientos de tu plan.

Autenticación

Cada solicitud necesita una clave de API, enviada en el encabezado Authorization como token Bearer.

En el panel, abre Claves de API en el menú de la izquierda.
Haz clic en Crear clave y ponle un nombre que diga dónde se usará, como “Zapier” o “CMS”.
Copia la clave enseguida: por seguridad, se muestra solo una vez. Puedes tener hasta 10 claves activas.

Terminal

export R301_KEY="r301_…"   # your key, from the dashboard

Prueba tu clave

curl https://api.redirect-301.com/v1/me \
  -H "Authorization: Bearer $R301_KEY"

Respuesta

{
  "email": "you@example.com",
  "plan": "studio",
  "maxRedirects": 5
}

Trata las claves como contraseñas: guárdalas en tu servidor, nunca en una página o app que otros puedan inspeccionar. Si una clave se filtra, revócala en el panel; deja de funcionar de inmediato.

Errores y límites

Las llamadas correctas devuelven 200, 201 (creado) o 204 (eliminado, sin cuerpo). Los errores siempre tienen la misma forma: un code estable que tu código puede comprobar y un message legible.

Respuesta de error

{
  "error": {
    "code": "plan_limit_reached",
    "message": "Your plan allows 5 redirect(s)."
  }
}

Status	Código	Cuándo
400	`validation_error`	Falta un campo o no es válido. El mensaje dice cuál.
401	`invalid_api_key`	Sin clave, o la clave es incorrecta o fue revocada.
403	`api_not_enabled`	Tu plan actual no incluye la API.
403	`account_inactive`	La cuenta está inactiva (por ejemplo, la suscripción fue cancelada).
404	`not_found`	El redireccionamiento, la ruta o el código QR no existe en tu cuenta.
409	`plan_limit_reached`	Ya tienes tantos redireccionamientos como permite tu plan.
409	`host_taken`	El dominio ya está registrado.
409	`path_exists`	Esa ruta ya existe en el redireccionamiento.
429	`rate_limited`	Demasiadas solicitudes: espera los segundos del encabezado `Retry-After`.

Cada clave puede hacer 60 solicitudes por minuto.

Redireccionamientos

Un redireccionamiento envía cada visita a uno de tus dominios (host) a otra URL (redirectTo). Se identifica por el nombre del dominio.

GET/redirectsLista tus redireccionamientos, con el maxRedirects de tu plan.

POST/redirectsCrea un redireccionamiento.

GET/redirects/{host}Devuelve un redireccionamiento.

PATCH/redirects/{host}Cambia redirectTo, redirectType, followPath o followQueryString.

DELETE/redirects/{host}Elimina el redireccionamiento, con sus rutas, códigos QR y estadísticas.

GET/redirects/{host}/statusEstado del DNS y del certificado (ver abajo).

Campo	Tipo	Descripción
`host`	string	El dominio que redirige, como `marca-antigua.com`. Obligatorio al crear; no se puede cambiar.
`redirectTo`	string	URL de destino completa (`http://` o `https://`), en otro dominio. Obligatorio al crear.
`redirectType`	number	`301` (permanente, el predeterminado) o `302` (temporal).
`followPath`	boolean	Conserva la ruta visitada: `marca-antigua.com/nosotros` → `marca-nueva.com/nosotros`. Predeterminado `true`.
`followQueryString`	boolean	Conserva la query string (`?utm_source=…`). Predeterminado `true`.
`status`	string	`not_configured` (el DNS aún no apunta), `pending` (certificado en emisión), `active`, `disabled` o `error`. Solo lectura.
`dns`	object	El registro DNS a crear en tu proveedor de dominio. Solo lectura.

Crear un redireccionamiento

curl -X POST https://api.redirect-301.com/v1/redirects \
  -H "Authorization: Bearer $R301_KEY" \
  -H "Content-Type: application/json" \
  -d '{"host": "old-brand.com", "redirectTo": "https://new-brand.com"}'

Respuesta · 201

{
  "host": "old-brand.com",
  "redirectTo": "https://new-brand.com",
  "redirectType": 301,
  "followPath": true,
  "followQueryString": true,
  "status": "not_configured",
  "dns": { "type": "A", "name": "old-brand.com", "value": "18.215.89.131" },
  "certificateExpiresAt": null,
  "errorMessage": null,
  "createdAt": "2026-09-26T14:02:11"
}

Después crea el registro A de dns en tu proveedor de dominio. En cuanto el dominio apunta a nosotros, emitimos el certificado HTTPS y el status pasa a pending y luego a active. Llama al endpoint de status para comprobar el DNS e iniciar el certificado enseguida:

Comprobar DNS y certificado

curl https://api.redirect-301.com/v1/redirects/old-brand.com/status \
  -H "Authorization: Bearer $R301_KEY"

Respuesta

{
  "host": "old-brand.com",
  "status": "pending",
  "dns": {
    "expected": { "type": "A", "name": "old-brand.com", "value": "18.215.89.131" },
    "resolved": ["18.215.89.131"],
    "pointing": true
  },
  "certificate": { "expiresAt": null },
  "errorMessage": null
}

Cambiar un redireccionamiento

curl -X PATCH https://api.redirect-301.com/v1/redirects/old-brand.com \
  -H "Authorization: Bearer $R301_KEY" \
  -H "Content-Type: application/json" \
  -d '{"redirectType": 302, "followPath": false}'

Rutas personalizadas

Una ruta personalizada envía una ruta de tu dominio a un lugar específico, como marca-antigua.com/promo → marca-nueva.com/rebajas. Las demás rutas siguen la regla principal del redireccionamiento.

GET/redirects/{host}/pathsLista las rutas del redireccionamiento.

POST/redirects/{host}/pathsCrea una ruta.

PATCH/redirects/{host}/paths/{id}Cambia cualquier campo.

DELETE/redirects/{host}/paths/{id}Elimina la ruta y los códigos QR que apuntan a ella.

Campo	Tipo	Descripción
`fromPath`	string	La ruta en tu dominio, como `/promo`. La `/` inicial se añade si falta; las rutas no distinguen mayúsculas y son únicas por redireccionamiento. Obligatorio.
`redirectTo`	string	A dónde va. Una ruta en el destino del redireccionamiento (`/rebajas`), o una URL completa cuando `absolute` es `true`. Obligatorio.
`absolute`	boolean	`true` para enviar la ruta a cualquier URL, incluso en otro dominio. Predeterminado `false`.
`statusCode`	number	`301` (predeterminado), `302`, `307` o `308`.

Crear una ruta

curl -X POST https://api.redirect-301.com/v1/redirects/old-brand.com/paths \
  -H "Authorization: Bearer $R301_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fromPath": "/promo", "redirectTo": "/summer-sale"}'

Respuesta · 201

{
  "id": 42,
  "fromPath": "/promo",
  "redirectTo": "/summer-sale",
  "absolute": false,
  "statusCode": 301,
  "createdAt": "2026-09-26T14:05:40"
}

Códigos QR

Un código QR abre el dominio del redireccionamiento, o una de sus rutas personalizadas. Cada código QR tiene su propia url con una marca ?_qr=, así sus escaneos se cuentan por separado en tus estadísticas; la marca se quita antes de redirigir al visitante.

GET/redirects/{host}/qr-codesLista los códigos QR del redireccionamiento.

POST/redirects/{host}/qr-codesCrea un código QR.

PATCH/redirects/{host}/qr-codes/{id}Cambia cualquier campo. Envía "pathId": null para que vuelva a apuntar al dominio.

DELETE/redirects/{host}/qr-codes/{id}Elimina el código QR.

GET/redirects/{host}/qr-codes/{id}/imageLa imagen: format=png (predeterminado) o svg, size en píxeles de 64 a 2048 (predeterminado 512).

Campo	Tipo	Descripción
`label`	string	El nombre que le das, como “Flyer A5”. Obligatorio.
`pathId`	number	La ruta personalizada que abre. Omítelo (o `null`) para el propio dominio.
`color`	string	Color hexadecimal del código, como `#0A0E14` (el predeterminado).
`format`	string	Formato de descarga preferido en el panel: `png`, `svg` o `pdf`.
`url`	string	Lo que codifica el código QR. Solo lectura.

Crear un código QR

curl -X POST https://api.redirect-301.com/v1/redirects/old-brand.com/qr-codes \
  -H "Authorization: Bearer $R301_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label": "Flyer A5", "pathId": 42, "color": "#0A0E14"}'

Respuesta · 201

{
  "id": 7,
  "label": "Flyer A5",
  "pathId": 42,
  "color": "#0A0E14",
  "format": "png",
  "url": "https://old-brand.com/promo?_qr=7",
  "imageUrl": "/v1/redirects/old-brand.com/qr-codes/7/image",
  "createdAt": "2026-09-26T14:07:02"
}

Descargar la imagen

curl -o flyer.png "https://api.redirect-301.com/v1/redirects/old-brand.com/qr-codes/7/image?format=png&size=1024" \
  -H "Authorization: Bearer $R301_KEY"

Las imágenes se generan al momento y no caducan, así que puedes volver a descargarlas cuando quieras. Una vez impreso un código QR, consérvalo: el código impreso sigue redirigiendo después de eliminarlo, pero sus escaneos dejan de contarse, y si eliminas su ruta abre el destino principal del redireccionamiento.

← Volver al inicio

Soporte

¿Necesitas ayuda?

No dudes en contactarnos con cualquier pregunta. ¡Estamos aquí para ayudarte! Escanea el código QR o haz clic en el botón de abajo para unirte a nuestro grupo de WhatsApp.

Abrir WhatsApp →