Quickstart de la API REST
- 1
Cree una clave API
En el panel: Ajustes → Claves API → Nueva clave. La clave en claro se muestra una sola vez y no se vuelve a almacenar — solo se guardan un hash HMAC-SHA-256 y un prefijo corto de visualización. Formato: `qrs_live_<64 caracteres hex>`; guárdela como `QCS_API_KEY`. Elija los scopes al crearla: `qrcodes:read`, `qrcodes:write`, `scans:read`, `conversions:write`. El formulario preselecciona los dos de lectura, el valor prudente para una credencial que acaba en un job de CI. El acceso API es una función del plan Business; una clave en un plan inferior se autentica pero recibe 403 `plan_limit`. Cada clave está limitada a 300 peticiones por minuto.
- 2
Cree un código QR dinámico
POST a `/api/v1/qrcodes` con la cabecera `Authorization: Bearer $QCS_API_KEY` y el cuerpo `{"name": "Flyer primavera", "type": "url", "destination_url": "https://example.com/landing"}`. La respuesta `{"data": {…}}` trae el id del código, el slug generado y `scan_url` — la dirección rastreada `/q/{slug}` que codifica el código impreso. `status` acepta `draft`, `active` o `paused`, y `campaign_id` vincula el código a una campaña existente. Si el workspace agotó su cuota de QR dinámicos, la llamada responde 403 `plan_limit` con `details.limit` y `details.current` en lugar de un error genérico. Los tipos estáticos nunca consumen esa cuota.
- 3
Lea los eventos de escaneo
GET `/api/v1/scans?qr_id={id}&days=30&per_page=50` devuelve una página de eventos de escaneo más un bloque `pagination`. Cada evento lleva `device_type`, `os`, `browser`, `country`, `region`, `city`, `language`, `referrer`, `is_bot`, `ab_variant` y el `destination` al que se envió al visitante. `days` acepta de 1 a 365 y por defecto es 30. No hay direcciones IP en la respuesta porque la plataforma no las almacena: solo un hash con clave llega a la base de datos. Omita `qr_id` para leer todos los escaneos del workspace.
- 4
Cambie el destino
PATCH `/api/v1/qrcodes/{id}` con el cuerpo `{"destination_url": "https://example.com/new-destination"}`. El mismo endpoint acepta `name`, `payload`, `campaign_id` y `status` con `draft`, `active`, `paused` o `archived`; se requiere al menos un campo. Responde 200 con el registro actualizado. El código impreso resuelve al nuevo URL en el siguiente escaneo — sin reimprimir, sin purgar caché. `DELETE /api/v1/qrcodes/{id}` responde 204 y retira el código.
- 5
Registre una conversión en servidor
POST `/api/v1/conversions` con el cuerpo `{"event_name": "purchase", "external_id": "order-1042", "amount": 49.9, "currency": "EUR", "qr_slug": "flyer-primavera"}`. Un evento nuevo responde 201 `{"id": …, "created": true}`; repetir el mismo `external_id` responde 200 `{"duplicate": true}`, así que un job que reintenta no puede contar los ingresos dos veces. La atribución acepta `qr_slug` o el valor `session_ref` capturado en la landing. La llamada exige el scope `conversions:write`.
- 6
Errores, y dónde encaja el plugin de WordPress
Cada fallo devuelve `{"error": {"code": …, "message": …}}` con un código estable sobre el que ramificar: `unauthorized`, `insufficient_scope`, `plan_limit`, `validation_error`, `not_found`, `rate_limited`. Los fallos de validación añaden `details.issues` indexado por campo. El plugin de WordPress es un conector, no una segunda API: se sincroniza en el mismo workspace vía `/api/v1/wp/*` con su clave de licencia, de modo que los códigos creados en WordPress aparecen en la misma lista `GET /api/v1/qrcodes` que los creados aquí. No necesita el plugin para usar la API, ni la API para usar el plugin.
Preguntas frecuentes
¿Qué es QRCode Suite?
QRCode Suite es una plataforma QR independiente: cree una cuenta gratuita y genere códigos QR dinámicos y personalizados en el navegador — sin necesidad de WordPress. Los conectores llevan los mismos códigos a WordPress y WooCommerce, donde los pedidos pueden atribuirse a códigos QR específicos.
¿QRCode Suite funciona sin WordPress?
Sí. QRCode Suite es un SaaS independiente: regístrese, cree sus códigos QR y siga los escaneos íntegramente en qrcode-suite.com. El plugin de WordPress es un conector opcional que lleva sus códigos a wp-admin y añade la atribución de pedidos WooCommerce.
¿QRCode Suite requiere una suscripción aparte?
El plan Free está disponible sin coste — sin tarjeta de crédito. Los planes de pago (Pro 9 €, Business 29 €, Agency 79 € al mes) desbloquean códigos ilimitados, reglas de redirección y más. No hay tarifa por escaneo.
¿Qué tipos de códigos QR admite QRCode Suite?
QRCode Suite admite 22 tipos de códigos QR: URL estática, URL dinámica, Texto plano, Teléfono, Email, Ubicación, Link Hub, SMS, WhatsApp, Wi-Fi, vCard, Perfil social, PDF, Descarga de archivo, Descarga de app, Cupón, Evento de calendario, Formulario de captación de leads, Recogida de reseñas, Solicitud mayorista, Recompensa de fidelidad y Payload personalizado.
¿Puedo cambiar el destino de un código QR después de imprimirlo?
Sí. Los códigos QR dinámicos utilizan una URL de redirección corta. Puede actualizar el destino desde su panel en cualquier momento, sin regenerar ni reimprimir el código.
¿Necesita ayuda para empezar?
Empiece gratis o consulte toda la documentación.