API REST

Documentación

Integra el generador de códigos QR directamente en tus aplicaciones. La API es completamente gratuita, rápida y no requiere registro ni autenticación.

Base URL

https://qr.losperris.dev

Endpoint

Envía una solicitud POST con un cuerpo en formato JSON al siguiente endpoint. La respuesta será el archivo de imagen binario directamente.

POST/api/generate

Sin autenticación: No necesitas incluir ningún token, clave de API ni cabecera de autorización.

Ejemplo con fetch

const response = await fetch('https://qr.losperris.dev/api/generate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'\n  },
  body: JSON.stringify({
    text: 'https://losperris.dev',
    width: 1000,
    type: 'png'\n  })
});

const blob = await response.blob();

Parámetros

Todos los parámetros se envían en el cuerpo de la solicitud como JSON. Solo text es obligatorio.

Atributo	Tipo	Descripción
`text*`	string	El contenido del código QR. URL, texto, etc. (Máx: 2000 caracteres)
`width`	number	Tamaño en píxeles. Defecto: `300`. (Mín: `100`, Máx: `2000`)
`margin`	number	Grosor del margen. Defecto: `4`. (Mín: `0`, Máx: `10`)
`type`	string	Formato: `png`, `jpg`, `webp`

Payload mínimo

{ 
  "text": "https://losperris.dev"\n}

Payload completo

{
  "text": "https://losperris.dev",
  "width": 1000,
  "margin": 4,
  "type": "png"\n}

Colores y Estilos

Personaliza la apariencia visual del código QR cambiando los colores y la forma de los módulos.

Atributo	Tipo	Descripción
`colorDark`	string (hex)	Color de los módulos. Defecto: `#000000`
`colorLight`	string (hex)	Color de fondo. Defecto: `#ffffff`
`dotStyle`	string	Puntos: `square`, `rounded`, `dots`
`eyeStyle`	string	Ojos: `square`, `rounded`, `dots`
`eyeColor`	string (hex)	Color exclusivo para los ojos.

Estilo de LosPerris

{
  "text": "https://losperris.dev",
  "colorDark": "#22c55e",
  "colorLight": "#080a08",
  "dotStyle": "rounded",
  "eyeStyle": "rounded",
  "eyeColor": "#22c55e"\n}

Gradientes

Aplica un gradiente dinámico sobre el código QR. Esto anula por completo el parámetro colorDark.

Atributo	Tipo	Descripción
`gradientType`	string	Estilo: `linear` o `none`
`gradientColor1`	string (hex)	Color inicial (desde arriba)
`gradientColor2`	string (hex)	Color final (hacia abajo)

QR con gradiente

{
  "text": "https://losperris.dev",
  "gradientType": "linear",
  "gradientColor1": "#22c55e",
  "gradientColor2": "#0ea5e9"\n}

Logo e Imagen Central

Incrusta tu logo de marca en el centro del código QR proporcionando una URL pública a una imagen web.

Atributo	Tipo	Descripción
`logoUrl`	string (url)	URL pública a la imagen (PNG, JPG, WEBP).
`logoFile`	string (base64)	Imagen en formato base64. Alternativa a `logoUrl`.

QR con logotipo

{
  "text": "https://losperris.dev",
  "logoUrl": "https://losperris.dev/logo.png"\n}

Estructura de Respuesta

Si la solicitud es exitosa, la API NO responde con JSON, sino que devuelve el archivo de imagen directamente en el cuerpo de la respuesta.

HTTP 200 OK

El cuerpo contiene los datos binarios. El encabezado de Content-Type coincidirá con el parámetro "type" solicitado.

Respuesta Exitosa

HTTP/1.1 200 OK
Content-Type: image/png
Content-Disposition: attachment; filename="qr.png"

<Binary Image Data Stream...>

Rate Limit

Para garantizar la disponibilidad del servicio gratuito, la API está protegida por un límite de peticiones estricto.

Límite: 20 peticiones / minutoCalculado individualmente por cada dirección IP mediante ventana deslizante.

Respuesta de error 429

{
  "error": "Too Many Requests",
  "message": "Has superado el límite de generación de códigos QR. Por favor, espera un minuto."
}

Gestión de Errores

En caso de error de validación o fallo interno, la API responde con un objeto JSON descriptivo.

Código HTTP	Significado
400	Parámetros inválidos o faltantes.
429	Demasiadas peticiones (Rate Limit).
500	Error interno del servidor.

Respuesta de error 400

{
  "error": "Validation Error",
  "details": [
    {
      "message": "text is required",
      "path": ["text"]
    }
  ]\n}