Sección 02
Visión en 30 segundos
Andesmar opera hoy un pipeline de datos en Google Cloud que toma la información de ventas, boletos y manifiestos desde Betterez y la transforma en tableros de negocio.
Estados en tiempo casi real
Webhooks actualizan cancelaciones, cambios y reservas expiradas al instante — no en un batch nocturno.
Recuperación automática
13 jobs programados detectan transacciones o manifiestos faltantes y los reinyectan desde la API de Betterez.
¿Qué sistema usar para qué?
| Necesidad de negocio | Fuente recomendada |
|---|---|
| Tablero oficial (pasajes, revenue, agencias) | bi_rebuild.fact_ticket + filtros documentados |
| Auditoría técnica / reconciliación | PostgreSQL public + scripts SQL |
| Estado vivo de un boleto hoy | API Betterez (Operations) |
| Comparar con pantalla Betterez por agencia | BI con is_paid_including_partial_cancel, misma moneda y sale_date |
Sección 03
Arquitectura en 4 capas
Cada capa responde una pregunta distinta. Juntas forman un sistema auditable de punta a punta.
Fuente operativa
GCS + raw_events
public
bi_rebuild
Tableros
↑ Jobs de red de seguridad (consulta activa a Betterez) alimentan Capas 1 y 2 ↑
Capa 1 — Raw
¿Qué nos dijo Betterez exactamente?
JSON inmutable en Google Cloud Storage. Usado por ingeniería, auditoría y recuperación.
Capa 2 — OLTP
¿Cuál es el estado actual de cada boleto?
Tablas operativas: ventas, tickets, pagos, manifiestos. Copia fiel y actualizada.
Capa 3 — BI
¿Cuánto vendimos, por agencia, ruta, estado?
Hechos y dimensiones curados para MicroStrategy. Fuente oficial de KPIs.
Capa 4 — Safety nets
¿Se nos escapó algo?
13 Cloud Run Jobs que buscan y recuperan datos automáticamente, sin intervención humana.
Sección 04
De la venta al tablero
Cuando alguien compra un pasaje en Betterez, este es el camino que recorren los datos.
Webhook
Betterez envía el evento con firma criptográfica HMAC
JSON inmutable
Se guarda el original completo en GCS antes de interpretar
Tablas operativas
Se extraen ventas, boletos, pagos y manifiestos a PostgreSQL
ETL diario
El job bi-rebuild-incremental empaqueta para MicroStrategy
Tipos de eventos que procesamos
| Familia | Ejemplos | Qué guardamos |
|---|---|---|
| Transacciones | venta completada, cancelada, actualizada | Ventas, boletos, pagos, reembolsos, ítems vendidos |
| Tickets | boleto actualizado, movido | Estado actualizado del boleto (cancelación post-venta) |
| Manifiestos | creado, actualizado, cerrado | Pasajeros, paradas, ocupación del servicio |
| Horarios | cambio de itinerario | Catálogo de servicios y distancias en km |
Sección 05
Ecosistema Betterez integrado
Dos modos complementarios: escucha en tiempo real y consulta activa como red de seguridad.
Escucha (push)
Webhooks Betterez → POST /api/v1/webhooks/betterez
Fuente principal para ventas, tickets y manifiestos. Eventos en tiempo casi real con validación HMAC.
Consulta (pull)
Jobs y scripts contra API REST de Betterez
Red de seguridad, backfills históricos, reconciliación y sincronización de catálogos (rutas, agencias).
APIs de Betterez que usamos hoy
Operations
Manifiestos, tickets, transacciones, reintentos de webhooks
Inventory
Itinerarios, rutas, horarios y distancias en km
Accounts
Catálogo de ~300 agencias con nombres canónicos
Webhooks API
Diagnóstico de eventos no entregados
Matriz: problema → herramienta
| Situación | Cómo lo resolvemos |
|---|---|
| Venta no llegó por webhook | Job diario transactions-safety-net + API GET /transactions |
| Estado de boleto desactualizado | Webhook ticket.* + job status-reconciliation cada 6 h |
| Manifiesto sin actualizar | Sync cada 30 min + job manifests-safety-net diario |
| Agencia renombrada en Betterez | Job mensual agency-catalog-sync |
| Webhook perdido ayer | Job undelivered-webhooks (desplegado; scheduler PAUSED hasta smoke — ver runbook) |
| Itinerario o km faltante | Job semanal schedules-safety-net + Inventory API |
Sección 06
Principio Raw First
Guardamos el original antes de interpretar. Es la base de la confiabilidad del sistema.
1. Guardar primero
Cada evento de Betterez se persiste completo en Google Cloud Storage y en raw_events antes de extraer tablas de negocio.
2. Reprocesar sin perder
Si mañana cambia una regla de BI, podemos reprocesar desde el JSON original. El dato histórico nunca se pierde.
3. Idempotencia
Mismo payload → mismo hash SHA256. Los reintentos de Betterez se deduplican automáticamente: un evento nunca se cuenta dos veces.
Sección 07
Red de seguridad automatizada
13 Cloud Run Jobs activos en Google Cloud. Si algo no llegó por webhook, lo buscamos y lo traemos automáticamente.
Reconciliación = "¿coincide con Betterez?" → corrigen drift.
Incremental = empaqueta OLTP para MicroStrategy.
Ingesta de manifiestos
- •
andesmar-manifests-sync— cada 30 min - •
betterez-manifests-safety-net— diario - •
andesmar-manifest-labels-sync— semanal - •
manifest-leg-guard— semanal
Ventas y webhooks
- •
betterez-transactions-safety-net— diario 06:30 - •
betterez-undelivered-webhooks— diario 07:00 (scheduler PAUSED jun-2026) - •
betterez-status-reconciliation— cada 6 h - •
betterez-raw-events-relational-catchup— cada 15 min
Catálogos y metadatos
- •
andesmar-agency-catalog-sync— mensual - •
andesmar-route-catalog-sync— mensual - •
andesmar-manifest-tag-catalog-sync— mensual - •
schedules-safety-net— semanal
Capa analítica
- •
bi-rebuild-incremental— 2× al día (00:00 y 12:00 ART)
Reconstruye tablas bi_rebuild con tickets y manifiestos del lookback.
Sección 08
Capa BI bi_rebuild
La capa analítica activa — única fuente para tableros MicroStrategy nuevos. Datos limpios, con reglas de negocio y nombres estables.
fact_ticketfact_salefact_manifest_leg297 agencias
Catálogo canónico con agency_label unificado para rankings y filtros en MSTR.
13 etiquetas de servicio
Nacional, internacional, línea provincial, La Cuyanita, encomiendas, IP y más.
Multi-moneda
ARS, CLP, BOB y USD con currency explícita en cada hecho.
Capacidades analíticas
Seguros y menores
50.828 seguros VIAJE PROTEGIDO · 4.611 menores <3 años · 7.015 tarifas niño
Ocupación por parada
fact_manifest_leg: cuántos suben y bajan en cada estación de cada servicio.
Cambios de boleto
Trazabilidad de sucesores cuando un pasaje se cambia por otro (fase 1 y 2 implementadas).
Pregunta de negocio → dónde mirar
| Pregunta | Tabla BI | Filtro clave |
|---|---|---|
| ¿Cuántos pasajes vendimos? | fact_ticket | is_paid = true + una moneda |
| ¿Cuánto facturamos? | fact_ticket | Sum(ticket_amount) pagados |
| ¿Por agencia / ranking? | fact_sale + dim_agency | agency_label canónico |
| ¿Nacional vs internacional? | fact_ticket | has_nacional / has_internacional |
| ¿Seguros vendidos? | fact_sold_item | is_insurance = true |
| ¿Ocupación por parada? | fact_manifest_leg | Filtro por manifest_date |
Sección 09
Calidad de datos — evidencia
Comparaciones reproducibles entre GCP, Legacy y Betterez. Los números están auditados y documentados.
GCP vs Legacy — meses cerrados
Día calendario 03/06/2026 — cruce detallado
| Métrica | Legacy | GCP | Resultado |
|---|---|---|---|
| Boletos del día | 2.504 | 2.534 | 98,7% emparejados |
| Montos en intersección | $139.751.830 | $139.751.830 | Coincidencia exacta |
| Estados distintos | — | 37 boletos | GCP refleja cancelaciones y cambios en tiempo real |
payment expired | No modelado | 27 boletos | Mayor fidelidad al producto Betterez |
Remediación y backfills completados (jun 2026)
- Drift
is_cancelled: 14 → 0 tickets - Backfill manifiestos ene–may: 525.610 filas hasta 31-may
- Sync BI path-aware: +2.622
manifest_idasignados - Bridge paso 9: 540k tickets actualizados en
fact_ticket_mstr
- Backfill webhooks abr–jun: cientos de transacciones recuperadas
- GCP +3.626 TX vs Legacy en 2026 (más completo)
- Legacy sin equivalente en GCP en 2026: 0 transacciones
bi_match_gap_has_meene–jun: 0
Sección 10
Seguridad y calidad de desarrollo
Ingeniería de nivel empresarial: seguridad en capas, tests automatizados y documentación extensa.
Seguridad en capas
/ready verifica PostgreSQL y GCS antes de recibir tráficoCalidad de ingeniería
Tests unitarios e integración
Suite end-to-end local
Lint automático de código
Auditoría CVE en CI
Alembic — Migraciones versionadas de base de datos. 6+ migraciones activas con trazabilidad completa de cambios de schema.
Documentación canónica
Arquitectura
Informe vivo, modelo de datos, ingesta webhooks, seguridad
BI / MicroStrategy
Guías de métricas, estados de boleto, agencias, seguros, ocupación
Operación
Runbooks de jobs, reconciliación, manifiestos, ETL incremental
Sección 11
Línea de tiempo — Ene a Jun 2026
Seis meses de construcción continua: de las fundaciones OLTP al ecosistema completo automatizado.
- Fundaciones OLTP y raw-first
- Alembic + migraciones
- Validación HMAC webhooks
- Primeros tests pytest
- Módulo manifiestos completo
- JWT Betterez + cliente HTTP
- Primer ETL BI incremental
- Guías de seguridad
- ETL canónico con lookback
- Backfills históricos
- Guías MicroStrategy
- Dim schedule + km
- Reconciliación masiva
- Auditorías Legacy vs GCP
- Backfill webhooks abr–jun
- Posicionamiento BI oficial
- 13 jobs automatizados activos
- Seguridad staging (HMAC + API Key)
- Remediación datos Oleadas 1–2
- Backfill manifiestos cerrado
Sección 12
bi_rebuild es la fuente oficial
Una plataforma de datos propia, auditable y automatizada que transforma Betterez en inteligencia de negocio confiable para Andesmar.
Captura
Webhooks en tiempo casi real + 13 jobs de recuperación automática
Transformación
ETL diario con reglas de negocio, multi-moneda y 13 etiquetas de servicio
Confianza
Raw-first, auditorías Legacy vs GCP, seguridad HMAC y tests automatizados
Andesmar API · Google Cloud · Betterez · MicroStrategy · Junio 2026