Desarrolladores
Referencia de la API e integraciones
Todo lo que necesitas para llamar a la API Business, gestionar claves y recibir webhooks.
Autenticación
La API Business autentica cada solicitud con una clave de API. Envíala en la cabecera X-Api-Key o como token Bearer en la cabecera Authorization.
Las claves llevan el prefijo qrg_ y solo se muestran una vez, al crearlas. Guárdalas en un lugar seguro: después no podrás volver a consultarlas.
Las solicitudes sin una clave válida devuelven 401. Una clave sin el permiso necesario recibe 403 con el error insufficient_scope. Los recursos fuera de tu espacio de trabajo devuelven 404, como si no existieran.
URL base
Todos los endpoints de la API Business están bajo el prefijo /v1.
Por ejemplo, para listar tus códigos QR usa https://qr-global.com/api/v1/qr-codes.
- URL base resuelta
- https://qr-global.com
Endpoints
Todos los endpoints están bajo /api/v1 y requieren una clave con el permiso indicado.
| Método | Ruta | Permiso | Qué hace |
|---|---|---|---|
| GET | /qr-codes | qr:read | Listar códigos QR (filtros: type, search, folder_id, tag, archived) |
| POST | /qr-codes | qr:write | Crear un código QR |
| POST | /qr-codes/bulk | qr:write | Crear hasta 100 códigos QR a la vez |
| GET | /qr-codes/{id} | qr:read | Obtener un código QR |
| PUT | /qr-codes/{id} | qr:write | Actualizar un código QR, su carpeta y sus etiquetas |
| DELETE | /qr-codes/{id} | qr:write | Eliminar un código QR |
| GET | /qr-codes/{id}/image | qr:read | Generar la imagen (PNG o SVG) |
| GET | /qr-codes/{id}/stats | analytics:read | Estadísticas de escaneo |
| GET | /qr-codes/{id}/scans | analytics:read | Registro de escaneos |
| GET | /folders | qr:read | Listar carpetas |
| GET | /tags | qr:read | Listar etiquetas |
| GET | /webhooks | webhooks:manage | Listar suscripciones a webhooks |
| POST | /webhooks | webhooks:manage | Suscribirse a eventos |
| DELETE | /webhooks/{id} | webhooks:manage | Cancelar la suscripción |
Una descripción legible por máquinas (OpenAPI 3.1) para Postman, generadores de código y herramientas no-code: Descargar openapi.json
Claves de API
Crea y revoca claves en la página Claves de API de tu panel.
Cada clave pertenece a tu espacio de trabajo y hereda el límite de solicitudes de tu plan.
La revocación de una clave surte efecto de inmediato.
Permisos (scopes)
Al crear una clave, dale acceso completo o solo los permisos que necesite la integración. Una clave sin un permiso recibe 403 con el error insufficient_scope y required_scope en la respuesta.
qr:read— Leer códigos QR- Listar y ver códigos QR, sus imágenes, carpetas y etiquetas.
qr:write— Gestionar códigos QR- Crear códigos QR (también de forma masiva), editarlos, moverlos entre carpetas, etiquetarlos y eliminarlos.
analytics:read— Leer analíticas- Estadísticas de escaneo y registro de escaneos de cada código QR.
webhooks:manage— Gestionar webhooks- Suscribir endpoints a eventos y cancelar sus suscripciones (Zapier, Make).
Las claves creadas antes de que existieran los permisos conservan el acceso completo. El acceso completo también cubre los permisos que se añadan más adelante.
Ejemplos
Comandos curl listos para copiar y pegar. Sustituye YOUR_API_KEY por una clave de la página Claves de API.
Listar códigos QR
curl -sS -H "X-Api-Key: YOUR_API_KEY" -H "Accept: application/json" \ "https://qr-global.com/api/v1/qr-codes"
Crear un código QR
Envía el tipo de QR y el contenido; el servidor genera y guarda el código.
curl -sS -X POST "https://qr-global.com/api/v1/qr-codes" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"type":"url","content":"https://example.com","display_name":"Example link"}'Generar una imagen
Obtén un archivo PNG o SVG listo: pasa ?format=png
curl -sS "https://qr-global.com/api/v1/qr-codes/123/image?format=png&size=512" \ -H "X-Api-Key: YOUR_API_KEY" -o qr.png # SVG (vector, no size limit on scale): curl -sS "https://qr-global.com/api/v1/qr-codes/123/image?format=svg" \ -H "X-Api-Key: YOUR_API_KEY" -o qr.svg
Ejemplo de payload de webhook
{
"event": "qr.scan.created",
"timestamp": "2026-04-03T12:00:00+00:00",
"data": {
"qr_code_id": 7,
"qr_code_uuid": "9b2f0c1e-4d4a-4f7e-9a51-2a7c3c1d8e10",
"type": "url",
"scan_id": 42,
"country": "UA",
"device_type": "mobile",
"scanned_at": "2026-04-03T12:00:00+00:00"
}
}Analítica de escaneos
GET /qr-codes/{id}/stats devuelve totales, visitantes únicos, principales países, dispositivos, navegadores y escaneos por día. GET /qr-codes/{id}/scans devuelve el registro de escaneos, del más reciente al más antiguo, 50 por página (per_page hasta 100).
Ambos aceptan from y to (una fecha como 2026-10-01 o una marca de tiempo completa) y timezone (UTC por defecto). Una fecha sin hora abarca el día entero en esa zona horaria.
Solo está disponible el período de historial de tu plan: los escaneos más antiguos se eliminan. Nunca se devuelven las direcciones IP ni los user agents de los visitantes.
Estadísticas de escaneo de un período
curl -sS "https://qr-global.com/api/v1/qr-codes/123/stats?from=2026-10-01&to=2026-10-31&timezone=Europe/Kyiv" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Accept: application/json"
Registro de escaneos, segunda página
curl -sS "https://qr-global.com/api/v1/qr-codes/123/scans?per_page=100&page=2" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Accept: application/json"
Carpetas y etiquetas
GET /folders y GET /tags listan las carpetas y etiquetas de tu espacio de trabajo. Envía folder_id y tags (slugs de las etiquetas) al crear o actualizar un código QR: folder_id null saca el código de su carpeta, y tags sustituye todo el conjunto.
Filtra la lista de códigos QR con ?folder_id= o ?tag=.
Mover un código QR a una carpeta y etiquetarlo
curl -sS -X PUT "https://qr-global.com/api/v1/qr-codes/123" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"folder_id": 4,
"tags": [
"campaign",
"priority"
]
}'Creación masiva
POST /qr-codes/bulk crea hasta 100 códigos QR en una sola solicitud. Requiere un plan con creación masiva, como la importación CSV del panel, y respeta tu límite de códigos QR activos.
Cada elemento se procesa por separado: la respuesta incluye cada elemento con el estado created (y el código nuevo) o failed (con error y errors). No reenvíes todo el lote, solo los elementos fallidos.
Crear dos códigos QR
curl -sS -X POST "https://qr-global.com/api/v1/qr-codes/bulk" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"codes": [
{
"type": "url",
"content": "https://example.com/spring",
"display_name": "Spring flyer",
"tags": [
"campaign"
]
},
{
"type": "url",
"content": "https://example.com/menu",
"display_name": "Table menu",
"folder_id": 4
}
]
}'Suscripciones a webhooks (REST hooks)
Zapier, Make y tus propios servicios pueden suscribirse a eventos a través de la API: POST /webhooks con url y events, y DELETE /webhooks/{id} para cancelar la suscripción. Son los mismos endpoints que ves en la página Webhooks.
La respuesta a POST contiene secret, que se muestra una sola vez: úsalo para verificar la cabecera X-Webhook-Signature. Si no envías tu propio secret (16 caracteres o más), generamos uno.
Eventos: qr.scan.created, subscription.updated, payment.succeeded, lead.captured, rsvp.received, feedback.received, poll.voted. Para suscribirse hace falta un plan con webhooks; cancelar la suscripción siempre funciona. Un espacio de trabajo puede tener hasta 25 endpoints.
Suscribirse a los escaneos
curl -sS -X POST "https://qr-global.com/api/v1/webhooks" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"url": "https://hooks.zapier.com/hooks/catch/123/abc/",
"events": [
"qr.scan.created"
]
}'Cancelar la suscripción
curl -sS -X DELETE "https://qr-global.com/api/v1/webhooks/42" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Accept: application/json"
Webhooks
Los webhooks envían los eventos a tu endpoint en cuanto ocurren, así no tienes que consultar periódicamente.
Configura los endpoints en la página Webhooks de tu panel.
Cada entrega va firmada y, si falla, se reintenta con un retardo exponencial.
El evento scan se dispara cuando alguien escanea uno de tus códigos QR.
Consulta los intentos de entrega, los payloads y las respuestas en el registro de entregas.
Devuelve un estado 2xx para confirmar la entrega; cualquier otro estado se considera un fallo.
Seguimiento de conversiones
Las conversiones indican al test A/B qué destino trae pedidos o registros, no solo escaneos. Con la optimización automática activada, el tráfico pasa a la variante que mejor convierte.
Añade el script a la página que el visitante ve tras convertir: confirmación del pedido, agradecimiento o éxito. Funciona en cualquier dominio y no necesita clave de API.
Fragmento
<script src="https://qr-global.com/c.js" async></script>
- Cada escaneo añade a la URL de destino un parámetro firmado qrg_v, para vincular la conversión al código QR y a la variante.
- El script guarda el token en una cookie propia durante 30 días, así la conversión cuenta aunque el visitante navegue antes por otras páginas.
- Cada escaneo cuenta una vez: recargar la página de agradecimiento no suma conversiones.
- Funciona con códigos QR que redirigen a una página http(s).
Exportaciones
Exporta tus códigos QR, escaneos, ubicaciones y actividad en CSV desde la página Exportaciones.
Las exportaciones usan la sesión de tu panel, no una clave de API — ábrelas con la sesión iniciada.
Consejos y errores frecuentes
- 401 Unauthorized — falta la clave de API o no es válida. Revisa la cabecera X-Api-Key.
- 403 Forbidden — a la clave le falta el permiso necesario (insufficient_scope) o tu plan no incluye la función (api_access_required, bulk_not_available, webhooks_not_available).
- 404 Not Found — el recurso no existe o pertenece a otro espacio de trabajo.
- 429 Too Many Requests — has alcanzado el límite por minuto de tu plan. Espera los segundos indicados en la cabecera Retry-After.
- Algunas funciones (como los webhooks) dependen de tu plan. Mejora tu plan si un endpoint devuelve un error de función.
- ¿Aún no hay entregas de webhooks? Escanea uno de tus códigos QR para generar una.
- Las entregas de webhooks fallidas se reintentan automáticamente; también puedes reintentarlas manualmente desde el registro de entregas.
- Los miembros del equipo trabajan dentro de tu espacio de trabajo; las claves y los datos pertenecen al propietario del espacio.