Sección 01
La pregunta que todos hacemos
Cuando miramos un tablero de ventas, la confianza no viene del color del gráfico: viene de saber que detrás hay un proceso robusto.
Piensen en un banco, no en una planilla Excel
Un banco no guarda el dinero en un cajón suelto. Tiene caja fuerte (copia inmutable del original), libro contable (estado actual de cada operación), auditoría diaria (¿falta algo?) y revisión con el proveedor (¿coincide con Betterez?).
Nuestra plataforma en Google Cloud funciona con la misma lógica: varias capas independientes que se refuerzan entre sí.
Sección 02
De dónde vienen los datos
Betterez es el sistema donde se venden los pasajes. Nosotros no reemplazamos a Betterez: lo escuchamos y lo verificamos.
Betterez
Agencias, web, mostradores: cada venta ocurre acá
Nuestra API
Recibe avisos automáticos (webhooks) en Google Cloud
Base de datos GCP
Guardamos ventas, boletos, pagos y manifiestos
Tableros BI
MicroStrategy lee la capa curada bi_rebuild
Escucha (tiempo casi real)
Cada vez que alguien compra, cancela o cambia un boleto, Betterez nos envía un mensaje automático firmado digitalmente. Es como recibir un WhatsApp verificado: “acaba de ocurrir esta venta”.
Consulta (verificación activa)
Además del aviso, nuestros programas van periódicamente a Betterez y preguntan: “¿hay ventas que no me avisaste?”. Eso es la red de seguridad — no esperamos a que alguien note un hueco en un reporte.
Sección 03
Cinco capas de protección
Cada capa responde una pregunta distinta. Juntas forman un sistema auditable de punta a punta.
Recepción en vivo — la API de Andesmar
¿Llegó el aviso de Betterez? Lo validamos, lo guardamos y lo procesamos.
Copia inmutable — Raw First
¿Guardamos el mensaje original completo antes de interpretarlo? Sí, en la nube (GCS).
Estado operativo — base PostgreSQL
¿Cuál es el estado actual de cada boleto, venta y manifiesto?
Red de seguridad — jobs programados
¿Se nos escapó algo? Lo buscamos y lo traemos automáticamente.
Capa analítica — ETL diario
¿Los tableros reflejan las reglas de negocio acordadas?
Sección 04
La API: el canal principal
La mayoría de las ventas llegan solas, en segundos, sin que nadie tenga que hacer nada.
Validación de identidad
Cada mensaje trae una firma digital (HMAC). Si alguien intentara enviar datos falsos, la API los rechaza. Es como verificar el sello en un documento oficial.
Respuesta rápida
Primero guardamos el original; después procesamos las tablas. Así Betterez no reintenta innecesariamente y nosotros no perdemos el mensaje.
Sin duplicados
Si Betterez reenvía el mismo aviso (por un reintento de red), el sistema lo reconoce y no cuenta la venta dos veces.
Tipos de eventos que capturamos
| Qué pasa en Betterez | Qué guardamos |
|---|---|
| Alguien compra o cancela un pasaje | Venta, boleto, pagos, reembolsos |
| Cambian el estado de un boleto después de la venta | Actualización del boleto (cancelación, cambio, vencimiento de pago) |
| Se arma o cierra un manifiesto de un servicio | Pasajeros, paradas, ocupación |
| Cambia un horario o itinerario | Catálogo de servicios y distancias |
Sección 05
Raw First: guardar el original primero
Antes de “traducir” un evento a filas de ventas y boletos, guardamos el mensaje completo e intacto. Esa es nuestra póliza de seguro.
La analogía de la caja fuerte
Imaginen que Betterez manda una carta con todos los detalles de una venta. Nosotros fotografiamos la carta entera y la guardamos en una caja fuerte en Google Cloud antes de pasarla al departamento contable.
Si mañana cambia una regla de negocio o encontramos un error de interpretación, podemos volver a leer la carta original. El dato histórico no se pierde.
Paso 1 — Nube (GCS)
Archivo JSON inmutable por cada evento. Queda para siempre como evidencia.
Paso 2 — Registro de trazabilidad
Tabla raw_events: quién envió qué, cuándo, y dónde está el archivo original.
Paso 3 — Tablas de negocio
Solo después extraemos ventas, boletos, pagos y manifiestos a PostgreSQL.
Sección 06
Jobs y safety nets: la red de seguridad
Programas automáticos que corren en Google Cloud, sin intervención humana, para detectar y recuperar lo que no llegó por el canal principal.
Safety net = “¿se nos cayó algo?”
Compara lo que Betterez tiene en su sistema con lo que nosotros tenemos. Si falta una venta o un manifiesto, la trae y la guarda con el mismo proceso Raw First.
Reconciliación = “¿coincide?”
Corrige diferencias de estado (por ejemplo, un boleto que en Betterez ya está cancelado pero nuestro registro aún no se actualizó).
Los jobs más importantes para el negocio
| Si falla esto… | Job que lo resuelve | ¿Cuándo corre? |
|---|---|---|
| Una venta no llegó por webhook | transactions-safety-net | Todos los días ~06:30 (revisa últimos 3 días) |
| Betterez no pudo entregar un aviso ayer | undelivered-webhooks (Job desplegado; scheduler PAUSED hasta validación) | Diario ~07:00 cuando se active |
| Estado de boleto desactualizado | status-reconciliation | Cada 6 horas |
| Manifiesto sin actualizar | manifests-sync + manifests-safety-net | Cada 30 min + diario |
| Guardamos el original pero no las tablas | raw-events-relational-catchup | Cada 15 minutos |
| Horario o km de ruta faltante | schedules-safety-net | Semanal |
En total hay 13 jobs activos en Google Cloud (ventas, manifiestos, catálogos, BI). Cada uno deja registro de lo que hizo: logs y, en casos críticos, un manifiesto de auditoría en la nube.
Sección 07
Cómo se solapan API, jobs y safety nets
No es “o la API o los jobs”. Es un sistema de defensa en profundidad: varias líneas que cubren los mismos datos desde ángulos distintos.
Ejemplo: una venta en agencia
- Segundos: webhook llega → API guarda original → actualiza tablas.
- Al día siguiente: safety-net compara con Betterez → si faltaba, la recupera.
- Cada 6 h: reconciliación verifica que el estado del boleto coincida.
Ejemplo: manifiesto de un servicio
- Webhook: ~29% de actualizaciones (cuando Betterez avisa).
- Sync cada 30 min: consulta activa de manifiestos próximos.
- Safety-net diario: cubre huecos de días anteriores.
Para manifiestos, el polling no es redundancia: es parte del diseño porque Betterez no avisa todo por webhook.
Sección 08
¿Qué pasa si algo falla?
Escenarios reales y qué hace el sistema — sin necesidad de llamar a sistemas a las 3 de la mañana.
Betterez reintenta el mismo mensaje. Nuestro sistema lo reconoce (no duplica) y lo procesa.
→ Resuelto automáticamente por reintentos + idempotencia
Al día siguiente, el job transactions-safety-net pregunta a Betterez “¿qué ventas hubo?” y encuentra la transacción faltante. La reinyecta con copia original en GCS.
→ Resuelto en menos de 24–72 h, con auditoría de la recuperación
El original ya está en la caja fuerte. El job raw-events-relational-catchup (cada 15 min) reprocesa lo pendiente.
→ El dato no se pierde; se retrasa minutos, no días
El sync cada 30 min y el safety-net diario vuelven a consultar Betterez y actualizan ocupación y paradas.
→ Cobertura continua sin depender de un solo aviso
No llegan avisos nuevos ni consultas. Cuando Betterez vuelve, los jobs retoman y cubren la ventana atrasada (D-3 a D-1 en ventas).
→ Brecha temporal acotada; recuperación al restablecer el servicio
Sección 09
Evidencia de que el sistema funciona
No es una promesa de marketing: son comparaciones reproducibles entre Betterez, GCP y el sistema histórico (Legacy).
Lo que GCP captura mejor que antes
- Cancelaciones y cambios de boleto después de la venta
- Estados como “pago vencido” que Legacy no modelaba
- Recuperación automática de webhooks perdidos
- Copia original de cada evento para auditoría
Caso real de recuperación
El boleto Z9TDZP (03/06/2026, $96.000) inicialmente no entró por webhook. El sistema de reconciliación lo detectó y lo incorporó. Legacy no tenía un proceso equivalente para cerrar ese tipo de hueco.
Cada corrida del safety-net deja registro: qué encontró, qué recuperó y dónde quedó guardado el original.
Sección 10
Lo que sí y lo que no prometemos
La confianza se construye con honestidad. Esto es lo que podemos decir con respaldo técnico y documentación.
Sí podemos afirmar
- Cada evento procesado deja copia original en la nube antes de interpretarse
- Si un webhook se pierde, hay jobs que lo detectan y recuperan en días
- Los reintentos de Betterez no duplican ventas en nuestro sistema
- Podemos auditar cualquier transacción: original + tablas + logs
- GCP supera al pipeline histórico en estados, recuperación y trazabilidad
- Los tableros oficiales usan reglas documentadas (
bi_rebuild)
No afirmamos (límites honestos)
- “Nunca se pierde nada al instante” — hubo gaps de webhook; por eso existen safety-nets
- “GCP siempre tiene más ventas cobradas” — algunos registros extra son pagos vencidos, no revenue
- “Legacy y GCP deben dar el mismo número cada día” — usan criterios de fecha distintos en el borde del día
- “100% sin intervención humana” — incidentes graves tienen runbooks para el equipo técnico
Sección 11
Glosario en lenguaje simple
Términos que pueden aparecer en reuniones técnicas, traducidos para el día a día.
- Webhook
- Aviso automático que Betterez envía cuando ocurre algo. Como una notificación push verificada.
- API / API Andesmar
- El “portero” en Google Cloud que recibe avisos, los valida y los guarda. También responde consultas internas.
- Raw First
- Guardar el mensaje original completo antes de interpretarlo. Nuestra caja fuerte digital.
- GCS (Google Cloud Storage)
- Almacenamiento en la nube de Google donde guardamos cada JSON original, para siempre.
- OLTP / PostgreSQL
- Base de datos operativa: estado actual de ventas, boletos, pagos y manifiestos.
- bi_rebuild
- Capa preparada para tableros MicroStrategy, con reglas de negocio (pagado, moneda, cancelaciones).
- Cloud Run Job
- Tarea programada en Google Cloud que corre sola (safety-net, sync de manifiestos, ETL).
- Safety net
- Red de seguridad: programa que busca datos faltantes y los trae de Betterez.
- Reconciliación
- Comparar nuestros datos con Betterez para detectar y corregir diferencias.
- HMAC / firma digital
- Sello criptográfico que prueba que el mensaje viene de Betterez y no fue alterado.
- Idempotencia
- Si llega el mismo aviso dos veces, el sistema lo procesa una sola vez.
- ETL incremental
- Proceso diario que empaqueta datos operativos para los tableros de negocio.
Sección 12
Tres ideas para llevarse
La plataforma no es un cable entre Betterez y un Excel. Es un sistema diseñado para que un dato perdido sea la excepción detectable y recuperable — no un error silencioso.
Captura en vivo
La API recibe cada venta en segundos, con firma verificada y sin duplicados.
Respaldo automático
13 jobs revisan, comparan y recuperan — API, safety nets y consultas activas se solapan.
Evidencia auditable
Original guardado + comparaciones con Legacy y Betterez + registro de cada recuperación.
Andesmar API · Google Cloud · Betterez · Documentación interna · Junio 2026
Referencias técnicas: api_andesmar/INFORME_ARQUITECTURA.md · docs/integracion/ECOSISTEMA_BETTEREZ_CONSULTA_Y_ESCUCHA.md