Crea códigos QR desde tu propia app con una API REST: guía de 10 minutos

2026-10-12 · Actualizado 2026-10-26 api developers automation

Para crear códigos QR desde tu propio sistema, envía una petición POST autenticada a la API REST de QR Maker con la URL de destino y tu propio identificador de referencia, y luego muestra el enlace corto que devuelve. Usa el identificador para que los reintentos sean seguros, pide el SVG en la misma llamada y haz un PATCH del destino más adelante cuando cambie la página. La API está disponible en el plan Business y está pensada para llamarse desde tu servidor, no desde un navegador.

Qué necesitas

Un plan Business y un token de API. Crea el token en la página Ajustes, en Tokens de API, y cópialo cuando aparezca: empieza por qrs_ y solo se muestra una vez. Elige el permiso de solo lectura para los tokens que solo descargan informes.
Un entorno de servidor. La API no permite llamadas de navegador entre orígenes, así que guarda el token en tu servidor.
Una referencia estable para cada código en tu propio sistema, como un número de pedido, un SKU o un código de referido. Será el external_id.

La URL base es https://qrmaker.ai/api/v1, y cada petición lleva Authorization: Bearer qrs_....

Paso 1: crea un código

curl -X POST "https://qrmaker.ai/api/v1/qrcodes?include=svg" \
  -H "Authorization: Bearer $QR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "target_url": "https://shop.example.com/product/AB12CD?ref=qr",
    "external_id": "AB12CD",
    "name": "Product AB12CD",
    "folder": "spring-campaign"
  }'

Solo target_url es obligatorio. La respuesta contiene el código, incluido un short_link como https://qrmk.cc/hzu23X y, gracias a ?include=svg, el marcado SVG en el campo svg. El enlace corto es lo único que debe codificarse en la imagen o compartirse. Cambiar target_url más adelante no cambia la imagen.

Paso 2: haz que los reintentos sean seguros con external_id

Las redes fallan y las tareas se ejecutan dos veces. Si envías de nuevo el mismo external_id con el mismo target_url, la API no crea un segundo código: devuelve el existente con estado 200 y la cabecera X-Idempotent-Replay: true. Un target_url distinto para un external_id existente devuelve 409, así que un reintento nunca puede cambiar en silencio adónde lleva un código impreso.

Paso 3: usa el SVG

Guarda o sirve el SVG tal cual. Se escala a cualquier tamaño de impresión y funciona en una etiqueta img. Para obtenerlo más tarde, llama a GET /v1/qrcodes/{id}/svg con los parámetros opcionales size y margin; la respuesta incluye un ETag, así que puedes guardarlo en caché y volver a descargarlo solo cuando cambie el estilo. La API no genera archivos PNG. Si necesitas PNG, convierte el SVG en tu propio sistema.

Paso 4: cambia el destino sin reimprimir

curl -X PATCH "https://qrmaker.ai/api/v1/qrcodes/by-external-id/AB12CD" \
  -H "Authorization: Bearer $QR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "target_url": "https://shop.example.com/product/AB12CD-v2" }'

Puedes buscar códigos por tu propia referencia, así que no necesitas guardar el ID de QR Maker. La nueva URL pasa por los mismos controles de seguridad que una introducida en la web.

Paso 5: consulta los resultados

GET /v1/qrcodes/{id}/analytics devuelve los escaneos, los visitantes únicos por día y desgloses por país, dispositivo, sistema operativo, navegador, referente, idioma y etiqueta de ubicación, para el rango de fechas y la zona horaria que elijas. GET /v1/analytics/summary agrega muchos códigos en una sola llamada, lo que evita una petición por código. Si prefieres un flujo de eventos, GET /v1/scans devuelve los nuevos escaneos en orden, y tú guardas el último next_since_id que viste.

Límites de frecuencia y cuotas

Cada cuenta puede hacer 120 peticiones a la API por minuto, compartidas por todos sus tokens, y cada respuesta incluye cabeceras con el margen restante. El plan Business incluye 50.000 peticiones correctas al mes; las que fallan con un estado 4xx o 5xx no cuentan. Para trabajos masivos, POST /v1/qrcodes/batch crea hasta 100 códigos por petición, cada uno idempotente por separado.

Un pequeño ejemplo en Node

const res = await fetch('https://qrmaker.ai/api/v1/qrcodes?include=svg', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.QR_TOKEN}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ target_url: url, external_id: orderId }),
})
if (!res.ok) throw new Error(`QR API ${res.status}: ${(await res.json()).code}`)
const { data } = await res.json()
// data.short_link es lo que codifica el código impreso; data.svg es la imagen

Básate en el campo estable code de las respuestas de error, no en el mensaje legible.

Siguientes pasos

La referencia de la API enumera todos los endpoints y códigos de error, y la página de presentación enlaza al archivo OpenAPI, a la colección de Postman y a programas de ejemplo completos. Para crear códigos sin escribir un servidor, consulta las guías de Google Sheets y de Make, n8n y Zapier.

Preguntas frecuentes

¿Puedo llamar a la API desde el navegador?

No. Si los navegadores llamaran directamente a la API, tu token quedaría expuesto a todos los visitantes. Llámala desde tu servidor y pasa el SVG o el enlace corto a la página.

¿Qué pasa si se filtra mi token?

Revócalo en Ajustes y crea uno nuevo. Los tokens solo pueden llamar a la API de códigos QR, no cambiar tu contraseña, tu facturación ni tus dominios, y un token de solo lectura no puede crear, modificar ni eliminar nada.

¿Pueden los códigos usar mi propio dominio?

Sí. En el plan Business puedes conectar un dominio propio para enlaces cortos. Pásalo como short_domain al crear un código y el enlace corto usará tu dominio en lugar del compartido.