Crear un código QR con la API REST: guía con ejemplos de curl

Paso 1: crear la clave

En el panel, en Cuenta, sección “Acceso para CLI, scripts y agentes”, creas una clave. Para las primeras pruebas basta con “solo lectura”. Elige una vigencia corta, por ejemplo 30 días. La clave empieza por sqr_live_ y solo se muestra una vez. Guárdala como variable de entorno para que no acabe en el historial de tu shell, por ejemplo a través de tu gestor de contraseñas.

Paso 2: la primera consulta

La API está en https://sameqr.com/api/v1. La clave va en la cabecera Authorization, nunca en la dirección:

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

La primera consulta muestra tu cuenta, tu tarifa y tus límites; la segunda, tus códigos QR con identificador, nombre, destino, etiquetas, número de escaneos y el estado _rev.

Paso 3: crear un código QR

Para crear necesitas una segunda clave con “lectura + escritura”. Con una clave de lectura, la API responde a las consultas que modifican datos con 403 y el código NUR_LESEN. Un código QR nuevo necesita como mínimo un nombre y un destino:

curl -X POST https://sameqr.com/api/v1/qr \
  -H "Authorization: Bearer $SAMEQR_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Speisekarte","targetUrl":"https://example.com/karte"}'

Escanea el nuevo código QR con el móvil antes de continuar. Para crear, tu dirección de correo debe estar confirmada, y el código QR cuenta para la cuota de tu tarifa.

Paso 4: cambiar el destino

Los cambios de destino están especialmente protegidos. Necesitas una clave “completa” y envías el estado actual del código QR en la cabecera X-Confirm. El estado te lo da la consulta de lectura:

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

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"}'

Solo se modifican los campos que envías. Si el estado no coincide porque alguien ha modificado el código QR entretanto, no se sobrescribe nada. Por la API se permiten como máximo 10 cambios de destino por hora y 30 por día; en el panel no existe este límite. En la tarifa gratuita, el número de cambios de destino por código QR está limitado.

Paso 5: entender los errores y los límites

Los errores siempre se devuelven con la misma forma: un objeto error con status, code y message. Interprétalos en tu programa en lugar de seguir sin más.

• 401: falta la clave, es incorrecta, ha caducado o ha sido revocada.
• 403: a la clave le falta el nivel necesario, o tu tarifa no permite la acción.
• 400 con BESTAETIGUNG_FEHLT: para cambiar el destino, poner offline o eliminar falta X-Confirm con el estado actual.
• 409: alguien ha modificado el código QR entretanto.
• 429: demasiadas solicitudes. Cada clave admite 120 por minuto, y por hora 60 en la tarifa gratuita, 300 en Start, 1.000 en Pro y 5.000 en Agentur.

Todas las solicitudes están descritas en /api/v1/openapi.json, y la guía está en sameqr.com/entwickler.

Conclusión: por qué Same-QR

La API REST de Same-QR es ordenada, está bien documentada y viene incluida en todas las tarifas. Puede hacer todo lo que hace el panel, protege los códigos QR impresos de cambios de destino accidentales con confirmación y límites, permite claves en tres niveles y responde con errores que se entienden.

Empieza ya: regístrate gratis en sameqr.com, 20 códigos QR dinámicos son gratuitos para siempre. La API, la CLI y el servidor MCP están disponibles en todas las tarifas, y la documentación está en sameqr.com/entwickler.

Preguntas frecuentes