Saltar a contenido

SDD — Bot Caja Chica · Registro de facturas en DARA

Ficha técnica

Campo Valor
Repositorio / carpeta salesiq/bot-caja-chica/
Plataforma Zoho SalesIQ · Zobot con código Deluge
Disparo Mensaje entrante en telegram
Código flujos/message_handler.dg (5 líneas) · flujos/context_handler.dg (932 líneas) · flujos/error_handler.dg (3 líneas)
Integraciones API de DARA
Proceso de negocio PDD

1. Arquitectura general

flowchart LR
    U[Usuario] --> SIQ[Zoho SalesIQ<br/>Zobot Deluge]
    SIQ -->|accesar3 · usuarios/estado<br/>listar-chatbot · listar-chatbot-estacion<br/>movimiento/registrar-chatbot| D[API DARA]
    SIQ -->|siq_email| P[Perfil del visitante]
    SIQ -->|forward, solo en error| AG[Agentes]

La lógica vive en los tres handlers y se ejecuta en Zoho en cada mensaje. El bot no tiene base de datos: la identidad del usuario se guarda en el correo del visitante de SalesIQ y el avance de la subida de facturas se guarda dentro del context_id.

2. Componentes

Handler Responsabilidad
message_handler Punto de entrada. Muestra el botón "Comenzar" y abre el contexto factura
context_handler Login, enrolamiento, listado de cajas, cantidad y subida de facturas
error_handler Ante una excepción no controlada responde "inconveniente técnico" y hace forward

Bloques del context_handler:

Líneas Bloque Se ejecuta
8–47 Login en DARA En cada mensaje
49–181 Subida de facturas (contextos f1_… y f2_…) Durante la subida
183–613 Lectura de identidad y enrolamiento (tipo, región, estación, usuario, confirmación) Si el perfil no tiene identidad
225–443 Catálogos regionIdMap, estMap, stIdDara Dentro del enrolamiento de Estaciones
615–688 Listado de cajas chicas según tipo Hasta que hay caja elegida
690–878 Bloque heredado: identidad, enrolamiento DARA1 y caja chica No se ejecuta (sección 9)
880–931 Cantidad de facturas y arranque de la subida Después de elegir caja

3. Flujo detallado

3.1 Login

POST /v1/usuarios/accesar3 con el usuario de servicio → data.token. Se arma dara_headers con Bearer <token>. Si falla, responde "No pudimos conectar" y termina. Se ejecuta en cada turno, incluso cuando el usuario solo está eligiendo una opción.

3.2 Identidad del visitante

La identidad se lee del correo del visitante con el formato <usuario>__<IdEstacion>@<dominio>:

IdEstacion Tipo Listado de cajas
0 Viáticos-Oficinas GET /v1/caja-chica/listar-chatbot/<usuario>
> 0 Estaciones GET /v1/caja-chica/listar-chatbot-estacion/<IdEstacion>

El dominio actual es @caja.chica; el flujo heredado usaba @dara1.local. El código toma lo que está antes de @, así que ambos funcionan. El comentario de la línea 187 dice @donarturo.com, pero el código no lo usa.

3.3 Enrolamiento

Solo si el correo no trae __:

  1. tipo_0: Estaciones o Viáticos-Oficinas.
  2. Estaciones: region_0 (dos páginas, 9 + "Ver más regiones") y estacion_0 (si la región tiene más de 9: primeras 8 + ➡️ Ver más (<IdRegion>), y siempre ⬅️ Volver a regiones). Se obtiene IdEstacion de stIdDara. Viáticos usa 0.
  3. usuario_<n>: el usuario. Se valida con GET /v1/usuarios/estado/<usuario>?tipoUsuarioID=2; si no existe, se pide usuario_<n+1>.
  4. cenr_<n>: pregunta con field_name: siq_email y un botón cuyo texto es <usuario>__<IdEstacion>@caja.chica. Al presionarlo, SalesIQ guarda ese valor como correo del visitante.
  5. En el siguiente turno el correo ya trae __, el enrolamiento se salta y el flujo sigue al listado de cajas.

3.4 Caja chica y cantidad

  1. Si hay una sola caja, se pregunta directamente cantidad_cc<CajaID>. Si hay varias, se pregunta caja con opciones <CajaID> - <TipoCajaChica>.
  2. La caja elegida se recupera del sufijo de cantidad_cc… o del prefijo de caja.
  3. La cantidad debe ser numérica, de 1 a 20. 0 cancela.
  4. Se abre el contexto de subida: f1 si IdEstacion es 0, f2 en otro caso.

3.5 Subida de facturas

Todo el estado va en el context_id:

f<tipo>_<CajaID>_<total>_<índice>_<intento>_<movs>_<montos>
Parte Uso
f1 / f2 TipoCajaChicaID que se envía a DARA (1 Viáticos, 2 Estaciones)
CajaID Caja chica elegida
total / índice Cuántas facturas y cuál toca
intento Contador de reintentos de la factura actual (solo hace único el contexto)
movs / montos Movimientos y montos registrados, unidos con - (x al inicio)

Por cada mensaje:

  1. Busca un archivo en answers. Si no hay, repite la misma factura con intento + 1.
  2. Toma la justificación del comentario del archivo (meta.comments[meta.value]).
  3. POST /v1/caja-chica/movimiento/registrar-chatbot multipart con file, Justificacion, CajaChicaID y TipoCajaChicaID.
  4. Si la respuesta trae MovCajaChicaID, agrega el movimiento y el monto al contexto y pide la siguiente, o envía el resumen y hace end si era la última.
  5. Si no, muestra MensajeError o mensaje de DARA y pide la misma factura otra vez.

4. Sistemas y dependencias

Sistema Uso Endpoint Notas
DARA Login de servicio POST /v1/usuarios/accesar3 En cada turno
DARA Validar usuario GET /v1/usuarios/estado/<usuario>?tipoUsuarioID=2 Responde Existe: true
DARA Cajas por usuario GET /v1/caja-chica/listar-chatbot/<usuario> Viáticos-Oficinas
DARA Cajas por estación GET /v1/caja-chica/listar-chatbot-estacion/<IdEstacion> Estaciones
DARA Registrar factura POST /v1/caja-chica/movimiento/registrar-chatbot Multipart; DARA calcula el monto

Base: https://api-dara.somosdonarturo.com.

5. Credenciales y configuración

Nombre Tipo Dónde se guarda
Usuario de servicio de DARA Usuario y contraseña En el context_handler (líneas 14–15).

6. Estados y datos persistentes

Elemento Dónde Uso
<usuario>__<IdEstacion>@caja.chica Correo del visitante (SalesIQ) Identidad permanente del usuario
context_id f… Sesión Avance de la subida de facturas
tipo_0, region_0, estacion_0, usuario_<n>, cenr_<n> answers Enrolamiento
caja, cantidad_cc<CajaID>, archivo answers Caja, cantidad y archivo actual

Catálogo dentro del código: 17 regiones, 179 estaciones en menú y 182 IDs de estación.

7. Manejo de errores y reintentos

Tipo Ejemplo Comportamiento
Negocio Usuario inexistente Pide usuario_<n+1>
Negocio Cantidad no numérica o mayor a 20 Elimina la respuesta y vuelve a preguntar
Negocio Mensaje sin archivo Repite la factura actual
Negocio DARA rechaza la factura Muestra el motivo y repite la factura
Negocio Estación sin IdEstacion end con aviso a soporte
Aplicación Sin cajas asignadas end con aviso a soporte
Infraestructura Login fallido end: "No pudimos conectar"
Infraestructura Excepción no controlada error_handler: mensaje y forward

Los reintentos de una factura no tienen límite.

8. Monitoreo y notificaciones

El bot no tiene bitácora propia. El registro real queda en DARA como movimientos de caja chica. Los mensajes info (HANDLER_INICIO, CAJAS_RAW, ESTADO_RAW) solo se ven en los registros de ejecución del Zobot; CAJAS_RAW y ESTADO_RAW vuelcan respuestas completas de DARA.

9. Restricciones conocidas y trampas

La salida del enrolamiento depende de que SalesIQ guarde el correo al momento

La condición de la línea 594 compara la respuesta del botón contra <usuario> y <usuario>__<IdEstacion> (sin @caja.chica), así que nunca coincide. El flujo avanza solo porque en el siguiente turno el correo del visitante ya está actualizado y el enrolamiento se salta. Si SalesIQ dejara de guardar siq_email en el mismo turno, el usuario quedaría en un ciclo de confirmación.

Enrolamiento permanente

El bot advierte que el registro no se podrá cambiar, y no hay opción para hacerlo. Si alguien se enrola en la estación equivocada o cambia de estación, solo se corrige editando el correo del visitante en SalesIQ (10.4).

Bloque heredado sin uso (líneas 690–878)

Repite la lectura de identidad, un enrolamiento solo por usuario de DARA1 (tipoUsuarioID=1, dominio @dara1.local) y el listado de cajas por usuario. Al llegar ahí siempre hay identidad y caja elegida, así que no hace nada. Incluye la bandera de prueba forzar_identidad con un usuario fijo. Conviene eliminarlo: confunde al leer el código y cualquier cambio podría reactivarlo. Busca tipo_1, que nunca existe porque el tipo se guarda como tipo_0.

Inconsistencias en el catálogo de estaciones

  • La Rosélia y San Rafael las Flores comparten el IdEstacion 1183: las dos listarían las mismas cajas.

  • Km122, Estacion Morales y Texaco Amatitlán están en stIdDara pero no en ningún menú. Texaco Amatitlán tiene el mismo ID que Amatitlán (1041).

  • Este catálogo es una copia del que usa el bot CDS, pero con IDs de DARA. Al abrir o cerrar una estación hay que actualizar los dos bots.

La validación de usuario es contra MACC, no contra Kira ni DARA

El bot le pide al usuario "el de Kira" o "el de DARA" según el tipo de caja, pero los dos tipos de usuario están registrados en MACC, y la validación siempre consulta MACC (tipoUsuarioID=2). Por eso ambos tipos usan el mismo valor. El 1 del flujo heredado validaba contra DARA1 y ya no se usa. Si algún día un tipo de usuario deja de estar en MACC, este es el punto a cambiar.

Login en cada mensaje

Se hace un login a DARA en cada turno, aunque el paso no llame a la API (por ejemplo, elegir región). Si DARA está lento, todo el bot se siente lento, y si el login falla, el usuario pierde la conversación aunque estuviera a mitad de la subida.

Justificación vacía

Si la persona envía la factura sin texto, la justificación va vacía y depende de DARA rechazarla.

10. Cómo aplicar cambios

Al terminar cualquiera: copiar el Deluge a flujos/, actualizar sincronizado_el en meta.yml y hacer commit con el número de ticket.

10.1 Agregar, renombrar o cerrar una estación
  1. Edita estMap (lista de la región) y stIdDara (nombre → IdEstacion de DARA). El nombre debe ser idéntico en los dos mapas.
  2. Si la región pasa de 9 estaciones, la paginación se activa sola.
  3. Al cerrar una estación, quítala del menú. Los usuarios ya enrolados en ella siguen teniendo su IdEstacion en el correo; revisa si hay que corregirlos (10.4).
  4. Revisa si el mismo cambio aplica al bot CDS.
10.2 Agregar una región

Agrega la región en regionIdMap y estMap, y en la lista de opciones de la página correspondiente (líneas 455 y 459, y la lista de "Volver a regiones" en la línea 475).

10.3 Cambiar el límite de facturas o los formatos

El máximo está en la condición > 20 y en su mensaje. Los formatos aceptados solo aparecen en el texto; la validación real la hace DARA.

10.4 Corregir el enrolamiento de un usuario
  1. En SalesIQ, abre el visitante y cambia o borra su correo.
  2. Si lo borras, en la siguiente conversación el bot lo enrolará de nuevo.
  3. Si lo editas, usa el formato <usuario>__<IdEstacion>@caja.chica (0 para Viáticos-Oficinas).
10.5 Un usuario dice que no le aparecen cajas
  1. Revisa su correo en SalesIQ para ver con qué usuario y estación quedó enrolado.
  2. Consulta en DARA las cajas de esa estación o de ese usuario.
  3. Si la identidad está mal, corrígela (10.4).
10.6 Cambió la contraseña del usuario de servicio

Actualízala en el Zobot publicado (no en el repositorio) y prueba con "Comenzar".

11. Historial de cambios

Versión Fecha Cambio Autor
1.0 2026-10-08 Documento inicial a partir del código Angel