Una API de códigos QR: qué automatizar y qué no

La mayoría de los códigos QR debería crearlos una persona, una vez, e imprimirlos. Una API se gana su sitio donde eso es imposible: un código por pedido, por reserva, por activo, por usuario — creado en un momento imprevisible y en una cantidad que nadie quiere clicar.

Cuándo la API es la respuesta

• Un código por registro en un sistema que ya operas: entrada, orden de trabajo, etiqueta de activo, envío.
• Destinos que se calculan, no se eligen. Si la URL se deduce de tus datos, teclearla no es una decisión sino una fuente de errores.
• Datos de escaneo que deben vivir en tu propio reporting, junto a pedidos e ingresos.

Cuándo no

• Una campaña de marketing. Media docena de códigos elegidos y diseñados por personas.
• Todo donde importe el diseño. La API crea y redirige; estilo, marcos y plantillas son del editor.
• Una tanda única. Para eso está la subida de CSV: una hoja de cálculo es una integración más rápida que una integración.

Autenticación

La clave se crea en el panel y se muestra una sola vez. Solo se guarda un hash SHA-256 y sus primeros caracteres para distinguirlas: una clave perdida no se recupera, se sustituye.

Authorization: Bearer enq_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

La API pertenece al plan Business. Límite: 60 peticiones por minuto y cuenta; por encima, 429 con rate_limited.

Crear un código

POST /api/v1/qrcodes
Authorization: Bearer enq_…
Content-Type: application/json

{ "name": "Pedido 10432 – albarán", "url": "https://shop.example/orders/10432" }

• Pon tu identificador en el nombre.
• Guarda el id devuelto junto a tu registro.

El resto

• GET /api/v1/qrcodes — tus códigos, del más reciente, con paginación por cursor.
• GET /api/v1/qrcodes/{id} — un código.
• PATCH /api/v1/qrcodes/{id} — cambiar el destino. Ahí descansa toda la idea del código dinámico.
• DELETE /api/v1/qrcodes/{id} — borrar; lo impreso deja de funcionar.
• GET /api/v1/qrcodes/{id}/scans — hasta 1.000 escaneos, del más reciente.

Qué contiene un escaneo

Hora, tipo de dispositivo, sistema y navegador declarados, referente si lo hay. Sin identidad, sin cuenta y sin ubicación: ni ciudad ni país. «Cuántos, cuándo, en qué tipo de dispositivo»: sí. «Quién» y «dónde»: no.

Errores reales

• 401 invalid_api_key
• 400 invalid_body — casi siempre una URL que no lo es.
• 402 plan_limit_reached — Business no tiene límite, así que la clave es de un plan menor.
• 429 rate_limited

Dos cosas desde el primer día

Haz la creación idempotente en tu lado. Dos llamadas crean dos códigos; los reintentos acaban llamando dos veces.

No imprimas lo que no has releído. Una petición tras crear evita el único error irrecuperable del sistema.

Respuestas rápidas

• ¿Qué plan? Business.
• ¿Autenticación? Authorization: Bearer enq_….
• ¿Clave perdida? Irrecuperable: crea otra y revoca la anterior.
• ¿Límite? 60 peticiones por minuto y cuenta.
• ¿Cambiar destino? Sí, PATCH.
• ¿Ubicación en los escaneos? No.
• ¿500 códigos una vez? Subida de CSV.