API de códigos QR y webhooks
La API permite que tu propio software cree, actualice, lea y elimine códigos QR, y consulte el resumen de sus escaneos. Los webhooks envían un aviso firmado a tu servidor cuando un código cambia, llega un escaneo humano o alguien envía un formulario de una página de destino.
Qué hacen la API y los webhooks
La API REST vive bajo la ruta /api/v1 y responde en JSON. Puede listar códigos con búsqueda, filtro por etiqueta y páginas de hasta cien, leer un código, crearlo, actualizarlo y eliminarlo, devolver un SVG plano del código y resumir los últimos treinta días de escaneos. Una clave es un token Bearer que empieza por qrk_ y pertenece a un solo espacio, así que una petición solo puede tocar los códigos de ese espacio.
Un webhook es una dirección HTTPS que registras con los eventos que quieres recibir. La app envía un mensaje JSON por cada evento: se crea, se actualiza o se elimina un código, se registra un escaneo humano o se envía un formulario de una página de destino. Una acción de prueba envía un evento ping, para que compruebes tu receptor antes de recibir tráfico real. Cada entrega se firma con HMAC-SHA256 usando el secreto del webhook, sobre la marca de tiempo y el cuerpo.
La API es para quien construye integraciones, y no cambia el aspecto de los códigos. El SVG es blanco y negro, sin logo, forma ni color, porque las imágenes con estilo salen del editor. La API requiere el plan Team. Las claves sobreviven a una bajada de plan, pero dejan de funcionar hasta que el espacio vuelva a un plan que incluya la API.
Cómo empezar a usar la API
-
01
Crea una clave como propietario
Abre la página de API como propietario, ponle a la clave un nombre, por ejemplo el del servidor que la usará, y créala. El token completo aparece una sola vez, así que cópialo de inmediato en tu gestor de secretos. Después, la página muestra solo el nombre, el prefijo, la fecha de creación y el último uso.
-
02
Envía la clave en cada petición
Envía el token en una cabecera Authorization, con la palabra Bearer, un espacio y el token. Empieza con la consulta de la cuenta: la respuesta indica el espacio, la clave y los créditos que quedan, lo que confirma que la configuración funciona. Una clave ausente o incorrecta recibe una respuesta de no autorizado.
-
03
Crea, actualiza y lee códigos
Envía el nombre, el tipo (por defecto es un enlace web), el contenido y los campos opcionales: dinámico, slug, caducidad, contraseña, un dominio verificado, etiquetas y estilo. Crear un código cuesta un crédito, mientras que leer y actualizar son gratis. Una petición que no pasa la validación devuelve los motivos y devuelve el crédito.
Dónde encaja la API
-
Venta de entradas y reservas
Cuando un sistema de reservas confirma una plaza, crea un código dinámico para esa entrada y envía el enlace corto y el SVG al comprador. El correo o el pase de la cartera llevan el mismo código, y nadie lo copia a mano.
-
Inventario y etiquetas de activos
Un sistema de almacén puede crear un código por artículo, con el número de artículo como etiqueta. Cada escaneo queda registrado, y el sistema puede leer el resumen de treinta días de cualquier artículo para ver qué etiquetas se revisaron hace poco.
-
Cartas de restaurante desde una hoja de cálculo
Un script puede leer una hoja con los enlaces de la carta y actualizar el contenido de cada código dinámico mediante la API. Los códigos impresos siguen igual, y el cambio se aplica desde el siguiente escaneo.
-
Registro en eventos y formularios de opinión
Un equipo de eventos puede publicar una página de destino con un formulario y recibir un webhook por cada respuesta. Un sistema aparte reacciona al evento, así que nadie tiene que consultar las respuestas una a una.
-
Monitorización y alertas
Un receptor de webhooks puede guardar los escaneos por país y dispositivo, y avisar cuando un código deja de escanearse. Tu sistema decide qué cuenta como problema, porque la app entrega los eventos y no los juzga.
Consejos para una integración fiable
- Guarda la clave como si fuera una contraseña
- Las claves se muestran una vez y se guardan solo como resumen, así que la app no puede volver a mostrarlas. Si una clave se filtra, revócala desde la página de API y crea otra. Revocarla detiene de inmediato cada petición que use el token antiguo.
- Respeta el límite de velocidad y los créditos
- Cada clave puede enviar 120 peticiones por minuto. Una petición por encima de ese ritmo recibe una respuesta de demasiadas peticiones. Cuando se acaban los créditos, crear un código devuelve una respuesta de pago requerido cuyo código de error indica que no quedan créditos. La app todavía no permite comprar más, así que planifica los procesos por lotes según el saldo.
- Verifica firmas y marcas de tiempo
- Calcula el HMAC-SHA256 de la marca de tiempo, un punto y el cuerpo sin procesar con tu secreto, y compáralo con la cabecera de firma. Rechaza las marcas de tiempo demasiado antiguas, para que una petición capturada no se reproduzca, y usa el identificador de entrega para ignorar un reenvío.
- Usa un destino que controles
- Las direcciones de webhook deben ser HTTPS, no pueden llevar credenciales y tienen que resolver a direcciones públicas. Los hosts locales y los rangos de red privada se rechazan, y las redirecciones no se siguen. Una entrega fallida se reintenta hasta cinco veces con esperas crecientes.
Preguntas sobre la API y los webhooks
¿Qué plan incluye la API?
El plan Team. Crear claves y webhooks lo requiere, y la API responde con un estado de pago requerido cuando el espacio está en un plan que no la incluye. Las claves existentes se conservan al bajar de plan, así que vuelven a funcionar cuando el plan regresa.
¿En qué se gasta un crédito?
Se gasta un crédito por cada código creado mediante la API. Leer, actualizar y eliminar códigos, así como leer el resumen de escaneos, no cuesta nada. Si una creación no pasa la validación, el crédito se devuelve.
¿Con cuántos créditos empieza un espacio?
Con cuarenta, que es el valor por defecto en la base de datos para cada espacio. La app todavía no tiene una página para comprar más, así que revisa el saldo en la página de API o con la consulta de la cuenta antes de una importación grande.
¿Puedo obtener el código como imagen desde la API?
Sí, como SVG plano. Eliges el tamaño de módulo entre uno y veinte y el margen entre cero y diez. La imagen es blanca y negra, sin logo, y si el contenido es demasiado largo para un código QR, la API lo indica. Para formas, colores o un logo, usa el editor.
¿A qué eventos puedo suscribirme?
A la creación, actualización y eliminación de un código, a un escaneo humano y al envío de un formulario de página de destino. Las peticiones de bots y las vistas previas de enlaces no disparan eventos de escaneo, y se puede enviar un evento de prueba a cualquier webhook.
¿Qué pasa si mi endpoint está caído?
La entrega se reintenta hasta cinco veces con esperas crecientes, y cada intento tiene un tiempo límite de conexión de cinco segundos y de lectura de diez. Tras el último fallo, la entrega se marca como fallida y la página de webhooks muestra el código de respuesta y el último error.
Crea tu primer código en un minuto
El editor es gratuito. Crea una cuenta cuando quieras guardar códigos, medir escaneos o cambiar un destino más adelante.