Referencia del API

API de AdvanceQR

Genera, personaliza y mide códigos QR de forma programática. El API se ofrece en dos niveles: Free para generar QR al vuelo, y Full con API key para QR dinámicos editables y analíticas de tráfico completas.

Nivel	Base URL	Autenticación
Free	`https://advanceqr.com/generator/qr/`	Ninguna
Full	`https://advanceqr.com/api/v1/`	API key (Bearer)

Free vs Full

Sin key

API Free

Genera un QR con un solo GET
Devuelve base64 listo para <img>
Personalización: tamaño, color, margen, ECL, formato
QR estático (el contenido va dentro del código)

Con API key

API Full

QR dinámicos: cambia el destino sin reimprimir
URLs cortas rastreables por cada QR
Listar, consultar y actualizar tus QRs
Tráfico completo por QR (escaneos, geo, dispositivo)
Webhooks de eventos de escaneo

Convenciones

Todas las respuestas son JSON (salvo cuando pides una imagen).
Los parámetros del API Free se prefijan con aqr_ para no chocar con la URL que codificas.
Marcas de tiempo en ISO 8601 (UTC).
Errores con la forma { "success": false, "error": { "code", "message" } }.
Paginación con page y per_page; la meta viaja en meta.

API Free · Endpoint Free

El contenido a codificar es lo que va después del prefijo del endpoint.

GET/generator/qr/{contenido}

Formas equivalentes (usa la de index.php si tu host no reescribe las URLs bonitas):

Peticiones

GET /generator/qr/https://advanceqr.com
GET /generator/qr/index.php/https://advanceqr.com
GET /generator/qr/index.php?aqr_data=https%3A%2F%2Fadvanceqr.com

URLs con su propio ?query: se conservan. Solo las claves aqr_* se interpretan como opciones; el resto se re-adjunta al contenido. Ej.: /generator/qr/https://shop.com/p?utm=ig&aqr_size=512 codifica https://shop.com/p?utm=ig a 512 px.

Parámetros

Parámetro	Valores	Default
`aqr_format`	`json` · `png` · `svg` · `base64`	`json`
`aqr_size`	80–1000 (px)	`300`
`aqr_margin`	0–100 (px)	`16`
`aqr_color`	hex (con o sin `#`)	`000000`
`aqr_bg`	hex	`ffffff`
`aqr_ecl`	`L` · `M` · `Q` · `H`	`M`
`aqr_label`	texto bajo el código (PNG)	—
`aqr_download`	`1` fuerza descarga	—
`aqr_pretty`	`1` formatea el JSON	—
`aqr_data`	contenido URL-encoded (forma query)	—

Respuesta (JSON por defecto)

200 OK

{
  "success": true,
  "url": "https://advanceqr.com",
  "data": "https://advanceqr.com",
  "img": "data:image/png;base64,iVBORw0KGgoAAA...",
  "format": "png",
  "mime": "image/png",
  "size": 300,
  "margin": 16,
  "error_correction": "M",
  "foreground": "#000000",
  "background": "#FFFFFF",
  "bytes": 1234,
  "links": { "png": "...", "svg": "...", "download": "..." },
  "generated_at": "2026-06-30T23:00:00+00:00"
}

El campo img ya es un data URI: úsalo directo sin nada más.

HTML

<img src="data:image/png;base64,iVBORw0KGgoAAA...">

Formatos de salida

aqr_format=json — metadata + img en base64 (default).
aqr_format=png — bytes PNG con Content-Type: image/png (úsalo como src directo).
aqr_format=svg — SVG vectorial.
aqr_format=base64 — el data URI como texto plano.

Sin extensión GD: el PNG cae automáticamente a SVG (también válido como data URI en <img>).

Ejemplos

cURL

# QR básico (JSON)
curl "https://advanceqr.com/generator/qr/https://advanceqr.com"

# Personalizado, imagen PNG directa
curl "https://advanceqr.com/generator/qr/https://advanceqr.com?aqr_size=512&aqr_color=1B1540&aqr_ecl=H&aqr_format=png" --output qr.png

JavaScript

const res = await fetch('https://advanceqr.com/generator/qr/https://advanceqr.com');
const { img, url } = await res.json();
document.querySelector('#qr').src = img; // listo, sin más pasos

PHP

$endpoint = 'https://advanceqr.com/generator/qr/' . rawurlencode('https://advanceqr.com');
$data = json_decode(file_get_contents($endpoint), true);
echo '<img src="' . $data['img'] . '">';

Límites

Contenido máximo: 2000 caracteres.
Tamaño: 80–1000 px. Margen: 0–100 px.
Uso justo sujeto a límite de tasa por IP. Para volumen y SLA, usa el API Full.

API Full · Autenticación Full

El API Full usa una API key en la cabecera Authorization. Consigue tu key en el panel de AdvanceQR. Existen keys de prueba (aqr_test_…) y de producción (aqr_live_…).

Basehttps://advanceqr.com/api/v1/

Cabecera

Authorization: Bearer aqr_live_9f2c1a7b8e4d...
Content-Type: application/json

Nunca expongas una key aqr_live_ en el navegador o en repositorios públicos. Úsala desde tu servidor.

¿Qué es un QR dinámico?

Un QR dinámico codifica una URL corta de AdvanceQR (p. ej. https://aqr.to/abcd12) que redirige al destino real. Como el destino se guarda del lado del servidor, puedes cambiarlo cuando quieras sin reimprimir el código, y cada escaneo queda registrado para las analíticas.

Crear un QR dinámico

POST/api/v1/qr

Campo	Tipo		Descripción
`destination`	string	req	URL destino (editable después).
`name`	string	opt	Nombre interno para identificar el QR.
`folder_id`	string	opt	Carpeta/campaña donde agruparlo.
`design`	object	opt	`size`, `margin`, `color`, `background`, `ecl`, `logo_url`, `frame`.
`active`	bool	opt	Si el QR redirige (default `true`).

cURL

curl -X POST "https://advanceqr.com/api/v1/qr" \
  -H "Authorization: Bearer aqr_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "https://advanceqr.com/promo-verano",
    "name": "Flyer verano 2026",
    "design": { "size": 600, "color": "1B1540", "ecl": "H" }
  }'

201 Created

{
  "success": true,
  "data": {
    "id": "qr_8Kd2mN4pQ",
    "code": "abcd12",
    "short_url": "https://aqr.to/abcd12",
    "destination": "https://advanceqr.com/promo-verano",
    "name": "Flyer verano 2026",
    "active": true,
    "image": "data:image/png;base64,iVBORw0KGgoAAA...",
    "image_url": "https://advanceqr.com/api/v1/qr/qr_8Kd2mN4pQ/image.png",
    "created_at": "2026-06-30T18:00:00+00:00"
  }
}

Listar QRs

GET/api/v1/qr

Parámetros: page, per_page (máx 100), folder_id, search, sort (created_at, scans).

200 OK

{
  "success": true,
  "data": [
    { "id": "qr_8Kd2mN4pQ", "short_url": "https://aqr.to/abcd12",
      "destination": "https://advanceqr.com/promo-verano",
      "total_scans": 1840, "unique_scans": 1122 }
  ],
  "meta": { "page": 1, "per_page": 25, "total": 57 }
}

Consultar un QR

GET/api/v1/qr/{id}

Devuelve el objeto QR completo con un resumen de escaneos (total_scans, unique_scans, last_scan_at).

Actualizar destino o diseño

PATCH/api/v1/qr/{id}

La función estrella: cambia el destination sin tocar el código impreso. También puedes actualizar name, design o active.

cURL

curl -X PATCH "https://advanceqr.com/api/v1/qr/qr_8Kd2mN4pQ" \
  -H "Authorization: Bearer aqr_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "destination": "https://advanceqr.com/promo-otono" }'

Eliminar un QR

DELETE/api/v1/qr/{id}

Archiva el QR y detiene la redirección. Responde { "success": true, "deleted": true }.

Tráfico y analíticas del QR

GET/api/v1/qr/{id}/analytics

Parámetros: from, to (fechas ISO), granularity (day | hour).

200 OK

{
  "success": true,
  "data": {
    "totals": { "scans": 18400, "unique": 11220, "countries": 37 },
    "timeseries": [
      { "date": "2026-06-24", "scans": 2200, "unique": 1510 }
    ],
    "by_country": [ { "country": "DO", "scans": 9200 } ],
    "by_city": [ { "city": "Santo Domingo", "scans": 4100 } ],
    "by_device": [ { "device": "mobile", "scans": 15020 } ],
    "by_os": [ { "os": "iOS", "scans": 8600 } ],
    "by_referrer": [ { "referrer": "instagram", "scans": 5400 } ],
    "by_hour": [ { "hour": 20, "scans": 1600 } ]
  }
}

Eventos de escaneo (crudo)

GET/api/v1/qr/{id}/scans

Lista paginada de cada escaneo, útil para exportar o auditar. Parámetros: page, per_page, from, to.

200 OK

{
  "success": true,
  "data": [
    { "id": "scan_71af3c", "scanned_at": "2026-06-30T20:14:07+00:00",
      "country": "DO", "city": "Santo Domingo",
      "device": "mobile", "os": "iOS", "browser": "Safari",
      "referrer": "instagram", "ip_hash": "a1b2c3..." }
  ],
  "meta": { "page": 1, "per_page": 50, "total": 18400 }
}

Las IPs se almacenan con hash para respetar la privacidad; no se exponen direcciones en crudo.

Webhooks

POST/api/v1/webhooks

Registra una URL para recibir eventos en tiempo real (qr.scanned, qr.updated). AdvanceQR firma cada envío con la cabecera X-AdvanceQR-Signature (HMAC-SHA256) para que valides el origen.

Evento qr.scanned

{
  "event": "qr.scanned",
  "qr_id": "qr_8Kd2mN4pQ",
  "scan": { "scanned_at": "2026-06-30T20:14:07+00:00", "country": "DO", "device": "mobile" }
}

Objetos

QR

Campo	Tipo	Descripción
`id`	string	Identificador del QR.
`code`	string	Código corto (parte de la short URL).
`short_url`	string	URL rastreable que se codifica en el QR.
`destination`	string	Destino actual (editable).
`name`	string	Nombre interno.
`active`	bool	Si redirige o no.
`total_scans` / `unique_scans`	int	Contadores de tráfico.
`image` / `image_url`	string	Data URI y URL de la imagen.
`created_at` / `updated_at`	string	Marcas de tiempo ISO 8601.

Scan

Campo	Tipo	Descripción
`scanned_at`	string	Fecha/hora del escaneo (UTC).
`country` / `city`	string	Geolocalización aproximada por IP.
`device` / `os` / `browser`	string	Datos del dispositivo.
`referrer`	string	Origen del escaneo cuando está disponible.
`ip_hash`	string	Hash de IP (sin IP en crudo).

Códigos de error

Los errores usan códigos HTTP estándar y esta forma:

Error

{ "success": false, "error": { "code": "unauthorized", "message": "Invalid API key." } }

HTTP	code	Significado
400	`bad_request`	Parámetros faltantes o inválidos.
401	`unauthorized`	API key ausente o inválida (Full).
404	`not_found`	El recurso (QR) no existe.
413	`content_too_large`	Contenido supera el máximo.
429	`rate_limited`	Demasiadas peticiones; reintenta luego.
500	`server_error`	Error interno al generar el QR.