# Leer QR (1) - [leerCodigoQR]

## 🧾 Descripción

Este servicio valida un **código QR de acceso a buses internos** y determina si un empleado puede registrar un nuevo escaneo.  
El flujo consulta los registros previos, controla tiempos de reescaneo (mínimo 4 horas) y registra un nuevo ingreso si corresponde.

El servicio interactúa con:

- **Tabla “Registro de Escaneres de Bus”** (documento principal con el QR)
- **Tabla “Tabla Lista Blanca”** (registros de escaneo por empleado)
- **ERP vía dbErp() y ServiceErp()**
- **Carbon** para manejo de fechas

---

## 🚀 Endpoint

**POST** `/leer-codigo-qr`

---

## 📥 Request Body

<div class="contain-inline-size rounded-2xl relative bg-token-sidebar-surface-primary" id="bkmrk-%7B-%22qr%22%3A-%22string%22%2C-%22e"><div class="sticky top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs"><table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>`<span class="hljs-punctuation">{</span>  <span class="hljs-attr">"qr"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"string"</span><span class="hljs-punctuation">,</span>  <span class="hljs-attr">"employee"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"string"</span><span class="hljs-punctuation">}</span>`</td></tr></tbody></table>

</div></div></div><div class="overflow-y-auto p-4" dir="ltr"></div></div>### Parámetros

<div class="_tableContainer_1rjym_1" id="bkmrk-campo-tipo-obligator"><div class="group _tableWrapper_1rjym_13 flex w-fit flex-col-reverse" tabindex="-1"><table class="w-fit min-w-(--thread-content-width)" data-end="1168" data-start="910"><thead data-end="961" data-start="910"><tr data-end="961" data-start="910"><th data-col-size="sm" data-end="923" data-start="910">Campo</th><th data-col-size="sm" data-end="932" data-start="923">Tipo</th><th data-col-size="sm" data-end="946" data-start="932">Obligatorio</th><th data-col-size="md" data-end="961" data-start="946">Descripción</th></tr></thead><tbody data-end="1168" data-start="1014"><tr data-end="1074" data-start="1014"><td data-col-size="sm" data-end="1027" data-start="1014">qr</td><td data-col-size="sm" data-end="1036" data-start="1027">string</td><td data-col-size="sm" data-end="1051" data-start="1036">✔️</td><td data-col-size="md" data-end="1074" data-start="1051">Código QR escaneado</td></tr><tr data-end="1168" data-start="1075"><td data-col-size="sm" data-end="1088" data-start="1075">employee</td><td data-col-size="sm" data-end="1097" data-start="1088">string</td><td data-col-size="sm" data-end="1112" data-start="1097">✔️</td><td data-col-size="md" data-end="1168" data-start="1112">Código del empleado que intenta registrar el escaneo</td></tr></tbody></table>

</div></div>---

## 🔐 Seguridad

Requiere autenticación interna del ERP (vía `dbErp()` y `ServiceErp()`).

---

## 🧠 Flujo del Servicio (resumen real)

### 1️⃣ Validaciones iniciales

- El QR no puede venir vacío
- El código de empleado tampoco

Si falla, retorna error inmediato.

---

### 2️⃣ Buscar el documento del QR

Consulta el ERP:

<div class="contain-inline-size rounded-2xl relative bg-token-sidebar-surface-primary" id="bkmrk-get-registro-de-esca"><div class="sticky top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs"><table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>`<span class="hljs-keyword">GET</span> Registro de Escaneres de Bus <span class="hljs-keyword">JOIN</span> Tabla Lista Blanca<span class="hljs-keyword">WHERE</span> qr = <qr><span class="hljs-keyword">ORDER</span> <span class="hljs-keyword">BY</span> fecha <span class="hljs-keyword">DESC</span>`</td></tr></tbody></table>

</div></div></div><div class="overflow-y-auto p-4" dir="ltr"></div></div>Campos devueltos:

- `name` (documento padre)
- `empleado`
- `fecha` del escaneo

Si no hay resultados: **QR inválido**.

---

### 3️⃣ Filtrar último registro por empleado

Construye una lista de empleados únicos y toma el último escaneo para cada uno.

Si el empleado actual tiene un registro:

- Calcula diferencia de horas entre el último registro y ahora.
- Si es **menor a 4 horas**, se retorna:

<div class="contain-inline-size rounded-2xl relative bg-token-sidebar-surface-primary" id="bkmrk-%7B-%22status%22%3A-true%2C-%22m"><div class="sticky top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs"><table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>`<span class="hljs-punctuation">{</span>  <span class="hljs-attr">"status"</span><span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">true</span></span><span class="hljs-punctuation">,</span>  <span class="hljs-attr">"msn"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"denegado"</span><span class="hljs-punctuation">}</span>`</td></tr></tbody></table>

</div></div></div><div class="overflow-y-auto p-4" dir="ltr"></div></div>---

### 4️⃣ Registrar nuevo escaneo

Si cumple la validación, inserta un registro en la tabla:

<div class="contain-inline-size rounded-2xl relative bg-token-sidebar-surface-primary" id="bkmrk-post-tabla-lista-bla"><div class="sticky top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs"><table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>`POST Tabla Lista Blanca{  fecha,  parent,  empleado,  parentlink: Registro de Escaneres de Bus}`</td></tr></tbody></table>

</div></div></div><div class="overflow-y-auto p-4" dir="ltr"></div></div>Si falla el registro → error  
Si se registra correctamente → "permitido"

---

## 📤 Response 200 – Ejemplos

### ✔️ Permitido

<div class="contain-inline-size rounded-2xl relative bg-token-sidebar-surface-primary" id="bkmrk-%7B-%22status%22%3A-true%2C-%22m-1"><div class="sticky top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs"><table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>`<span class="hljs-punctuation">{</span>  <span class="hljs-attr">"status"</span><span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">true</span></span><span class="hljs-punctuation">,</span>  <span class="hljs-attr">"msn"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"permitido"</span><span class="hljs-punctuation">}</span>`</td></tr></tbody></table>

</div></div></div><div class="overflow-y-auto p-4" dir="ltr"></div></div>### ⛔ Denegado por escaneo reciente

<div class="contain-inline-size rounded-2xl relative bg-token-sidebar-surface-primary" id="bkmrk-%7B-%22status%22%3A-true%2C-%22m-2"><div class="sticky top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs"><table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>`<span class="hljs-punctuation">{</span>  <span class="hljs-attr">"status"</span><span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">true</span></span><span class="hljs-punctuation">,</span>  <span class="hljs-attr">"msn"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"denegado"</span><span class="hljs-punctuation">}</span>`</td></tr></tbody></table>

</div></div></div><div class="overflow-y-auto p-4" dir="ltr"></div></div>### ❌ QR sin registros

<div class="contain-inline-size rounded-2xl relative bg-token-sidebar-surface-primary" id="bkmrk-%7B-%22status%22%3A-false%2C-%22"><div class="sticky top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs"><table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>`<span class="hljs-punctuation">{</span>  <span class="hljs-attr">"status"</span><span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">false</span></span><span class="hljs-punctuation">,</span>  <span class="hljs-attr">"msn"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"No se encontraron registros para el QR escaneado"</span><span class="hljs-punctuation">}</span>`</td></tr></tbody></table>

</div></div></div><div class="overflow-y-auto p-4" dir="ltr"></div></div>### ❌ Error interno

<div class="contain-inline-size rounded-2xl relative bg-token-sidebar-surface-primary" id="bkmrk-%7B-%22status%22%3A-false%2C-%22-1"><div class="sticky top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs"><table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>`<span class="hljs-punctuation">{</span>  <span class="hljs-attr">"status"</span><span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">false</span></span><span class="hljs-punctuation">,</span>  <span class="hljs-attr">"msn"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"Error interno: <mensaje>"</span><span class="hljs-punctuation">}</span>`</td></tr></tbody></table>

</div></div></div><div class="overflow-y-auto p-4" dir="ltr"></div></div>---

## ❗ Posibles Errores

1. **QR vacío**

<div class="contain-inline-size rounded-2xl relative bg-token-sidebar-surface-primary" id="bkmrk-%7B-%22status%22%3A-false%2C-%22-2"><div class="sticky top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs"><table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>`<span class="hljs-punctuation">{</span>  <span class="hljs-attr">"status"</span><span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">false</span></span><span class="hljs-punctuation">,</span>  <span class="hljs-attr">"msn"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"El QR no puede estar vacio"</span><span class="hljs-punctuation">}</span>`</td></tr></tbody></table>

</div></div></div><div class="overflow-y-auto p-4" dir="ltr"></div></div>2. **Empleado vacío**

<div class="contain-inline-size rounded-2xl relative bg-token-sidebar-surface-primary" id="bkmrk-%7B-%22status%22%3A-false%2C-%22-3"><div class="sticky top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs"><table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>`<span class="hljs-punctuation">{</span>  <span class="hljs-attr">"status"</span><span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">false</span></span><span class="hljs-punctuation">,</span>  <span class="hljs-attr">"msn"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"El empleado no puede estar vacio"</span><span class="hljs-punctuation">}</span>`</td></tr></tbody></table>

</div></div></div><div class="overflow-y-auto p-4" dir="ltr"></div></div>3. **QR inexistente en ERP**

<div class="contain-inline-size rounded-2xl relative bg-token-sidebar-surface-primary" id="bkmrk-%7B-%22status%22%3A-false%2C-%22-4"><div class="sticky top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs"><table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>`<span class="hljs-punctuation">{</span>  <span class="hljs-attr">"status"</span><span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">false</span></span><span class="hljs-punctuation">,</span>  <span class="hljs-attr">"msn"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"No se encontraron registros para el QR escaneado"</span><span class="hljs-punctuation">}</span>`</td></tr></tbody></table>

</div></div></div><div class="overflow-y-auto p-4" dir="ltr"></div></div>4. **Error al insertar registro**

<div class="contain-inline-size rounded-2xl relative bg-token-sidebar-surface-primary" id="bkmrk-%7B-%22status%22%3A-false%2C-%22-5"><div class="sticky top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs"><table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>`<span class="hljs-punctuation">{</span>  <span class="hljs-attr">"status"</span><span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">false</span></span><span class="hljs-punctuation">,</span>  <span class="hljs-attr">"msn"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"No se pudo registrar el escaner de bus"</span><span class="hljs-punctuation">}</span>`</td></tr></tbody></table>

</div></div></div><div class="overflow-y-auto p-4" dir="ltr"></div></div>5. **Error interno (try–catch)**

<div class="contain-inline-size rounded-2xl relative bg-token-sidebar-surface-primary" id="bkmrk-%7B-%22status%22%3A-false%2C-%22-6"><div class="sticky top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs"><table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>`<span class="hljs-punctuation">{</span>  <span class="hljs-attr">"status"</span><span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">false</span></span><span class="hljs-punctuation">,</span>  <span class="hljs-attr">"msn"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"Error interno: <mensaje>"</span><span class="hljs-punctuation">}</span>`</td></tr></tbody></table>

</div></div></div><div class="overflow-y-auto p-4" dir="ltr"></div></div>---

## 🗃 Tablas / Schemas utilizados

### **Registro de Escaneres de Bus (tpr)**

Campos usados:

<div class="contain-inline-size rounded-2xl relative bg-token-sidebar-surface-primary" id="bkmrk-%7B-%22name%22%3A-%22string%22%2C-"><div class="sticky top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs"><table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>`<span class="hljs-punctuation">{</span>  <span class="hljs-attr">"name"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"string"</span><span class="hljs-punctuation">,</span>  <span class="hljs-attr">"qr"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"string"</span><span class="hljs-punctuation">}</span>`</td></tr></tbody></table>

</div></div></div><div class="overflow-y-auto p-4" dir="ltr"></div></div>### **Tabla Lista Blanca (teas)**

Campos usados:

<div class="contain-inline-size rounded-2xl relative bg-token-sidebar-surface-primary" id="bkmrk-%7B-%22empleado%22%3A-%22strin"><div class="sticky top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs"><table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>`<span class="hljs-punctuation">{</span>  <span class="hljs-attr">"empleado"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"string"</span><span class="hljs-punctuation">,</span>  <span class="hljs-attr">"fecha"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"datetime"</span><span class="hljs-punctuation">,</span>  <span class="hljs-attr">"parent"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"string"</span><span class="hljs-punctuation">}</span>`</td></tr></tbody></table>

</div></div></div><div class="overflow-y-auto p-4" dir="ltr"></div></div>### Registro Insertado

<div class="contain-inline-size rounded-2xl relative bg-token-sidebar-surface-primary" id="bkmrk-%7B-%22fecha%22%3A-%22datetime"><div class="sticky top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs"><table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>`<span class="hljs-punctuation">{</span>  <span class="hljs-attr">"fecha"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"datetime"</span><span class="hljs-punctuation">,</span>  <span class="hljs-attr">"parent"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"string"</span><span class="hljs-punctuation">,</span>  <span class="hljs-attr">"empleado"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"string"</span><span class="hljs-punctuation">,</span>  <span class="hljs-attr">"parentfield"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"table_1"</span><span class="hljs-punctuation">,</span>  <span class="hljs-attr">"parenttype"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"Registro de Escaneres de Bus"</span><span class="hljs-punctuation">}</span>`</td></tr></tbody></table>

</div></div></div><div class="overflow-y-auto p-4" dir="ltr"></div></div>---

## 🧩 Pseudocódigo del flujo

<div class="contain-inline-size rounded-2xl relative bg-token-sidebar-surface-primary" id="bkmrk-if-qr-is-empty-%E2%86%92-err"><div class="sticky top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs"><table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>`if qr is empty → errorif employee is empty → error// Buscar registros del QRdataQR = SELECT * FROM RegistroEscaneresBus JOIN TablaListaBlanca WHERE qr = qr ORDER BY fecha DESCif dataQR is empty → error// Obtener últimos registros por empleadoempleadosUnicos = agrupar_por_empleado(dataQR)if empleadosUnicos[employee] existe:    diffHoras = horas_entre(último registro, ahora)    if diffHoras < 4:        return "denegado"// Registrar nuevo escaneoinsert = POST TablaListaBlanca {    fecha: now,    empleado,    parent: documentoPrincipal}if insert.error:    return errorreturn "permitido"`</td></tr></tbody></table>

</div></div></div><div class="overflow-y-auto p-4" dir="ltr"></div></div>