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://advanceqr.com/q/aB3xQ9k) 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
`name`	string	req	Nombre interno para identificar el QR.
`type`	string	req	`url` · `text` · `wifi` · `vcard` · `email` · `phone` · `sms` · `geo` · `social` · `file`.
`fields`	object	req	Contenido según `type`. Para `url`/`social`: `{ "url": "..." }`. Para `wifi`: `{ "ssid", "password", "encryption" }`. Para `vcard`: `{ "full_name", "phone", "email", ... }`. Etc.
`tracking_enabled`	bool	opt	Si mide escaneos vía redirección `/q/{code}` (default `true`). En `false` el contenido se codifica directo en la imagen, sin métricas ni posibilidad de editar el destino después.
`design`	object	opt	`foreground_color`, `background_color`, `module_style`, `eye_style`, `margin`, `error_correction`, `logo_url`.
`campaign_id`	int	opt	Campaña donde agruparlo.

cURL

curl -X POST "https://advanceqr.com/api/v1/qr" \
  -H "Authorization: Bearer aqr_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Flyer verano 2026",
    "type": "url",
    "fields": { "url": "https://advanceqr.com/promo-verano" },
    "design": { "foreground_color": "#1B1540", "error_correction": "H" }
  }'

201 Created

{
  "success": true,
  "data": {
    "id": 8123,
    "name": "Flyer verano 2026",
    "type": "url",
    "short_code": "aB3xQ9k",
    "short_url": "https://advanceqr.com/q/aB3xQ9k",
    "tracking_enabled": true,
    "active": true,
    "image_url": "/api/v1/qr-image.php?id=8123&format=svg"
  }
}

image_url es relativa a https://advanceqr.com; acepta &format=png y &size= para otros formatos/tamaños.

Listar QRs

GET/api/v1/qr-list

Parámetros: page, per_page (máx 50, default 20), search (nombre), campaign_id.

200 OK

{
  "success": true,
  "data": [
    { "id": 8123, "name": "Flyer verano 2026",
      "short_code": "aB3xQ9k", "short_url": "https://advanceqr.com/q/aB3xQ9k",
      "type": "url", "destination": "https://advanceqr.com/promo-verano",
      "destination_summary": "https://advanceqr.com/promo-verano",
      "campaign_id": 6, "campaign_name": "Verano 2026",
      "active": true, "status": "active", "tracking_enabled": true,
      "scans": 1840, "unique_scans": 1122,
      "created_at": "13 Aug 2026", "image_url": "/api/v1/qr-image.php?id=8123&format=svg&size=160" }
  ],
  "meta": { "page": 1, "per_page": 20, "total": 57 }
}

Consultar un QR

GET/api/v1/qr?id={id}

Devuelve el objeto QR completo, incluido fields (el contenido según su type, listo para reenviar tal cual a un PATCH) y su diseño actual.

Actualizar un QR

PATCH/api/v1/qr?id={id}

Cambia el destino sin tocar el código impreso: reenvía name + fields (mismo formato que al crear) para actualizar el contenido. También acepta tracking_enabled, design y campaign_id. El type no se puede cambiar después de creado.

cURL

curl -X PATCH "https://advanceqr.com/api/v1/qr?id=8123" \
  -H "Authorization: Bearer aqr_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Flyer verano 2026", "fields": { "url": "https://advanceqr.com/promo-otono" } }'

Pausar o reactivar un QR

PATCH/api/v1/qr?id={id}

No hay endpoint de borrado — un QR impreso no se puede "eliminar" de la calle. En su lugar, envía solo active para pausarlo (deja de redirigir, muestra un aviso al escanear) o reactivarlo, sin tocar su nombre ni su contenido.

cURL

curl -X PATCH "https://advanceqr.com/api/v1/qr?id=8123" \
  -H "Authorization: Bearer aqr_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'

200 OK

{ "success": true, "data": { "id": 8123, "status": "paused" } }

Tráfico y analíticas del QR

GET/api/v1/analytics?qr_id={id}

Sin qr_id, agrega el tráfico de toda tu organización. Parámetro range: 7 · 30 · 90 · 365 (días, default 30).

200 OK

{
  "success": true,
  "data": {
    "range": 30, "qr_id": 8123,
    "kpis": { "total_scans": 18400, "unique_scans": 11220, "countries": 37, "avg_per_day": 613 },
    "timeseries": [
      { "date": "2026-07-24", "total": 2200, "unique": 1510 }
    ],
    "by_country": [ { "country": "DO", "scans": 9200 } ],
    "by_city": [ { "city": "Santo Domingo", "scans": 4100 } ],
    "by_device": [ { "type": "mobile", "scans": 15020 } ],
    "by_os": [ { "name": "iOS", "scans": 8600 } ],
    "by_browser": [ { "name": "Safari", "scans": 7300 } ],
    "by_referrer": [ { "referrer": "instagram", "scans": 5400 } ],
    "by_hour": [ { "hour": 20, "scans": 1600 } ]
  }
}

Eventos de escaneo (crudo)

GET/api/v1/scans

Lista paginada de cada escaneo, útil para exportar o auditar. Parámetros: qr_id, page, per_page (máx 100), from/to (YYYY-MM-DD) o range (7·30·90·365) si no das fechas.

200 OK

{
  "success": true,
  "data": [
    { "id": 71412, "scanned_at": "2026-08-13 20:14:07",
      "qr_name": "Flyer verano 2026", "short_code": "aB3xQ9k",
      "country": "Rep. Dominicana", "flag": "🇩🇴", "city": "Santo Domingo",
      "device_type": "mobile", "os": "iOS", "browser": "Safari",
      "referrer": "Instagram", "is_unique": true }
  ],
  "meta": { "page": 1, "per_page": 25, "total": 18400 }
}

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

Webhooks

Próximamente. Los webhooks salientes (qr.scanned, qr.updated) están en el roadmap pero todavía no están disponibles — por ahora, consulta eventos de escaneo o analíticas por polling.

Objetos

QR

Campo	Tipo	Descripción
`id`	int	Identificador del QR.
`short_code`	string	Código corto (parte de la short URL).
`short_url`	string	URL rastreable que se codifica en el QR (`https://advanceqr.com/q/{short_code}`).
`type`	string	Tipo de contenido: `url`, `text`, `wifi`, `vcard`, `email`, `phone`, `sms`, `geo`, `social`, `file`.
`fields`	object	Contenido actual según `type` (solo en `GET` de un QR puntual).
`destination` / `destination_summary`	string	Destino resuelto en forma legible (solo en el listado).
`name`	string	Nombre interno.
`status`	string	`active`, `paused`, `expired`.
`active`	bool	Atajo de `status === 'active'`.
`tracking_enabled`	bool	Si mide escaneos vía `/q/{short_code}`.
`scans` / `unique_scans`	int	Contadores de tráfico (solo en el listado).
`image_url`	string	URL relativa de la imagen del QR (SVG por defecto).
`created_at`	string	Fecha de creación.

Scan

Campo	Tipo	Descripción
`scanned_at`	string	Fecha/hora del escaneo (`YYYY-MM-DD HH:mm:ss`, hora del servidor).
`qr_name` / `short_code`	string	A qué QR pertenece el escaneo.
`country` / `flag` / `city`	string	Geolocalización aproximada por IP.
`device_type` / `os` / `browser`	string	Datos del dispositivo.
`referrer`	string	Origen del escaneo cuando está disponible.
`is_unique`	bool	Si es la primera vez que este visitante escanea este QR.

Las IPs nunca se exponen en la API — se almacenan solo como hash internamente, para respetar la privacidad.

Códigos de error

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

Error

{ "success": false, "error": { "code": "unauthorized", "message": "API key inválida." } }

HTTP	code	Significado
400	`bad_request`	Parámetros faltantes o inválidos.
401	`unauthorized`	Sin sesión ni API key válida (revisa formato, revocación o expiración de la key).
403	`forbidden`	Autenticado, pero sin permiso para esa acción.
404	`not_found`	El recurso (QR, campaña, documento…) no existe en tu organización.
409	`in_use`	No se puede completar porque el recurso está en uso (p. ej. un documento con QR asignados).
413	`content_too_large`	Contenido o archivo supera el máximo permitido.
403	`plan_limit`	Alcanzaste un límite de tu plan actual (QR, almacenamiento, campañas…).
500	`server_error`	Error interno.

El API Free no requiere autenticación y no aplica límites de plan de organización — solo el uso justo por IP.