API de códigos QR: crea, cambia y analiza códigos QR automáticamente

Para qué sirve una API de códigos QR

Una API de códigos QR es una interfaz de programación: en lugar de hacer clic en el navegador, tu programa envía solicitudes al servicio de códigos QR y recibe respuestas. Así se generan códigos QR directamente desde una tienda online, un programa de gestión, un script o una hoja de cálculo.

Merece la pena en cuanto el trabajo se repite: cien códigos QR para mesas o productos, informes mensuales de escaneos, el cambio de muchos destinos tras un rediseño de la web. Y solo funciona con códigos QR dinámicos. Un código QR dinámico de Same-QR contiene una dirección corta y constante; el destino que hay detrás está en nuestro sistema y se puede cambiar en cualquier momento, sin volver a imprimir.

Qué cubre la API de Same-QR

La API REST está en https://sameqr.com/api/v1. Llama a las mismas funciones que el panel, con los mismos límites de plan y las mismas comprobaciones:

• Listar, leer, crear, cambiar y eliminar códigos QR.
• Las estadísticas de un código QR: escaneos, fecha de creación, número de cambios de destino.
• Crear, cambiar, publicar y poner fuera de línea páginas de invitados como carta, lista de precios, horarios, página de enlaces, promoción, bodega, etiqueta electrónica de vino y contacto.
• Leer una carta a partir de hasta siete fotos o un PDF.
• Gestionar etiquetas y proyectos de clientes y leer las solicitudes de los formularios de contacto.

Una descripción legible por máquina de todas las solicitudes está en /api/v1/openapi.json, y la guía en sameqr.com/entwickler.

Clave de API y permisos

La clave se crea en el panel, en Cuenta, en el apartado «Acceso para CLI, scripts y agentes». Eliges uno de tres niveles, «solo lectura», «lectura + escritura» (crear, cambiar nombres y textos) o «completo» (además, cambiar destinos, poner fuera de línea, eliminar), y una validez de 30, 90, 180 o 365 días, o ilimitada si hace falta. La clave empieza por sqr_live_ y se muestra exactamente una vez. Nosotros solo guardamos una suma de comprobación.

Una clave que solo puede leer recibe un rechazo claro en cada solicitud que modifique algo. Para informes y análisis es la elección correcta. Todo lo que cambia a dónde lleva un código QR impreso tiene además una protección extra: cambiar destinos, poner fuera de línea y eliminar exigen el nivel «completo» y una confirmación con el estado leído previamente, y por la API solo se permiten 10 por hora y 30 por día. En el panel no existe este límite. Cada clave se puede revocar en cualquier momento y deja de ser válida al instante.

Un flujo típico

La clave va en la cabecera Authorization, nunca en una dirección. Guarda antes la clave como variable de entorno. Así listas tus códigos QR y cambias el destino de un código QR:

curl -H "Authorization: Bearer $SAMEQR_API_KEY" https://sameqr.com/api/v1/qr

curl -X PATCH https://sameqr.com/api/v1/qr/<id> \
  -H "Authorization: Bearer $SAMEQR_API_KEY" -H "Content-Type: application/json" \
  -H "X-Confirm: <stand>" \
  -d '{"targetUrl":"https://example.com/karte-neu"}'

El valor de X-Confirm, el estado, lo devuelve la solicitud de lectura a /api/v1/qr/<id>. Solo se cambia lo que envías. Quien quiera asegurarse de que nadie ha cambiado entretanto el mismo código QR envía el estado leído como _rev. Si algo ha cambiado, no se sobrescribe nada y la respuesta contiene el estado actual. Los errores siempre llegan en el mismo formato, con estado, código QR y un mensaje comprensible.

Límites y buenas prácticas

Cada clave admite como máximo 120 solicitudes por minuto. A esto se suma un límite por hora que depende del plan: 60 en el plan gratuito, 300 en Start, 1.000 en Pro y 5.000 en Agentur. Los límites frenan errores, por ejemplo un script en un bucle infinito, y no molestan en un uso honesto.

• Prueba primero con una clave de lectura y escribe después.
• Prueba los flujos nuevos con un solo código QR y escanéalo con el móvil.
• Evita eliminar cuando basta con un destino nuevo. Los códigos QR eliminados y sus enlaces cortos no se recuperan.
• Crea una clave propia para cada programa y guárdala en un gestor de contraseñas o en una variable de entorno.

Conclusión: por qué Same-QR

Same-QR no te ofrece la API como un extra caro, sino en todos los planes y con las mismas funciones que el panel: códigos QR, estadísticas, cartas, páginas de invitados, etiquetas y proyectos. A esto se suman permisos claros por clave, mensajes de error honestos y una comprobación nocturna de todos los destinos que te avisa por correo si alguno no está accesible.

Empieza ya: regístrate gratis en sameqr.com, 20 códigos QR dinámicos son gratuitos de forma permanente. La API, la CLI y el servidor MCP están en todos los planes, y la documentación está en sameqr.com/entwickler.

Preguntas frecuentes