API REST v1

API para desarrolladores

Automatice la creación, actualización y organización de QR desde backend, scripts o pipelines CI.

Endpoints

Método	Ruta	Descripción
GET	/api/v1/qr	Listar códigos QR
POST	/api/v1/qr	Crear código QR
POST	/api/v1/qr/bulk	Crear códigos QR en masa (items JSON o CSV)
GET	/api/v1/qr/:id	Obtener un código QR
GET	/api/v1/qr/:id/analytics	Analítica de escaneos de un QR
PATCH	/api/v1/qr/:id	Actualizar código QR
DELETE	/api/v1/qr/:id	Eliminar código QR
GET	/api/v1/folders	Listar carpetas
POST	/api/v1/folders	Crear carpeta
GET	/api/v1/folders/:id	Obtener una carpeta
PATCH	/api/v1/folders/:id	Actualizar carpeta
DELETE	/api/v1/folders/:id	Eliminar carpeta

Autenticación

Cree una clave API en Panel → Configuración. Envíela como:

Authorization: Bearer qb_live_...

# or

X-API-Key: qb_live_...

Webhooks de escaneo

Añada endpoints HTTPS en Configuración → Webhooks de escaneo. Escaneos, leads de landing y clics CTA envían POST JSON con X-QRbanner-Signature (HMAC-SHA256).

{
  "event": "scan",
  "qr_code_id": "...",
  "qr_name": "Store Istanbul",
  "short_code": "abc12",
  "scan": {
    "country": "TR",
    "city": "Istanbul",
    "device": "mobile",
    "scanned_at": "2026-06-29T12:00:00.000Z"
  }
}

Ver integraciones →

Verificar firmas

Lea el cuerpo de la solicitud sin procesar, calcule HMAC-SHA256 con el secreto de firma y compárelo con X-QRbanner-Signature (prefijo sha256=). Los fallos de entrega se reintentan hasta 3 veces; use Enviar prueba en Configuración.

const crypto = require('crypto');

function verifyWebhook(body, signatureHeader, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signatureHeader),
    Buffer.from(expected)
  );
}

Especificación OpenAPI

OpenAPI 3.0 legible por máquina para REST API v1, API móvil y SCIM 2.0 — impórtelo en Postman, Insomnia o API Gateway.

Explorar referencia interactiva de la API →Descargar openapi.json →

Límites de tasa

Dos límites por plan: ráfaga por minuto más cuota mensual. Cada respuesta incluye cabeceras X-RateLimit-*; al superar el límite devuelve 429 con Retry-After.

Free — 60/min · 1000/mes
Pro — 120/min · 10.000/mes
Business — 300/min · 100.000/mes
Agency — 600/min · 500.000/mes

URL base

https://qrbanner.com

Obtener acceso a la API

API móvil

Endpoints complementarios para PWA y clientes móviles propios. Autentique con cookie de sesión o la misma API key que REST v1. Los campos de respuesta usan camelCase (véase OpenAPI MobileQr).

Página de PWA y apps móviles →

Método	Ruta	Descripción
GET	/api/mobile/v1/summary	Uso del plan y escaneos recientes
GET	/api/mobile/v1/qr	Listar códigos QR (formato móvil)
POST	/api/mobile/v1/qr	Crear código QR
GET	/api/mobile/v1/qr/:id	Detalle QR más escaneos recientes
PATCH	/api/mobile/v1/qr/:id	Actualizar código QR
DELETE	/api/mobile/v1/qr/:id	Eliminar código QR

Aprovisionamiento SCIM 2.0

Los espacios de trabajo de equipo Business y Agency pueden sincronizar miembros desde Okta, Microsoft Entra ID (Azure AD), Google Workspace o cualquier IdP SCIM 2.0. Active SCIM en Configuración → Equipo, copie el token bearer una vez y apunte su IdP a la URL base siguiente.

Ver endpoints SCIM en la referencia API interactiva →

Configuración del IdP

Abra Panel → Configuración → Equipo → SCIM y active el aprovisionamiento.
Copie el token bearer mostrado una sola vez (prefijo qrb_scim_) y guárdelo en su IdP.
Configure la URL base SCIM en https://qrbanner.com/api/scim/v2 con Authorization: Bearer <token>.
Asigne grupos o roles del IdP a los Groups virtuales admin, editor o viewer — controlan el rol del miembro en el espacio de trabajo.

Base URL: https://qrbanner.com/api/scim/v2
Authorization: Bearer qrb_scim_...

# Roles ↔ virtual Groups: admin | editor | viewer

Método	Ruta	Descripción
GET	/api/scim/v2/Users	Listar miembros del espacio de trabajo
POST	/api/scim/v2/Users	Invitar o aprovisionar un miembro
GET	/api/scim/v2/Users/:id	Obtener un miembro
PATCH	/api/scim/v2/Users/:id	Actualizar atributos o rol del miembro
PUT	/api/scim/v2/Users/:id	Reemplazar miembro (alias de PATCH)
DELETE	/api/scim/v2/Users/:id	Eliminar un miembro
GET	/api/scim/v2/Groups	Listar grupos de rol virtuales
POST	/api/scim/v2/Groups	Asegurar que exista un grupo de rol virtual (idempotente)
GET	/api/scim/v2/Groups/:id	Obtener un grupo de rol y sus miembros
PATCH	/api/scim/v2/Groups/:id	Actualizar membresía del grupo / mapeo de roles
PUT	/api/scim/v2/Groups/:id	Reemplazar membresía del grupo (alias de PATCH)
DELETE	/api/scim/v2/Groups/:id	Eliminar grupo (los grupos de rol virtuales responden 400)
GET	/api/scim/v2/ServiceProviderConfig	Configuración del proveedor de servicios SCIM
GET	/api/scim/v2/ResourceTypes	Tipos de recurso admitidos
GET	/api/scim/v2/Schemas	Esquemas SCIM

Páginas relacionadas

Solicitud de ejemplo

curl -X POST https://qrbanner.com/api/v1/qr \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Store Istanbul",
    "category": "url",
    "qr_data": { "url": "https://example.com/tr" }
  }'