Skip to content

Templates de Dataflow

Este documento describe la arquitectura y funcionamiento de los templates de Dataflow utilizados en Solvento. Para información sobre despliegue y operaciones, consulta Despliegue de Templates.

Overview

Los templates de Dataflow permiten reutilizar pipelines Apache Beam desplegándolos como templates en Google Cloud Storage (GCS) y ejecutándolos como jobs de Dataflow. Este documento describe qué templates existen y cómo funcionan desde una perspectiva arquitectónica.

Templates Disponibles

El sistema utiliza templates de Dataflow para procesar diferentes tipos de eventos. Cada template está diseñado para un caso de uso específico.

Templates Disponibles

1. invoices-webhook

Descripción: Procesa eventos de invoices desde webhooks de Syntage.

Características: - Lee desde Pub/Sub subscription: invoices-webhook-subscription - Escribe a BigQuery: solvento-data-prod:syntage.invoices - Escribe a ELK (Elasticsearch) para búsqueda en tiempo real - Maneja Dead Letter Queue: invoices-dlq

Destinos: - BigQuery: solvento-data-prod:syntage.invoices - ELK: Indexado por RFC para búsqueda en tiempo real - Dead Letter Queue: invoices-dlq para mensajes fallidos

2. invoices-api

Descripción: Procesa eventos de invoices desde APIs externas.

Características: - Lee desde Pub/Sub subscription: invoices-api-subscription - Escribe a BigQuery: solvento-data-prod:syntage.invoices - Escribe a ELK (Elasticsearch) para búsqueda en tiempo real - Configuración de workers: 1 worker (máximo 1)

Destinos: - BigQuery: solvento-data-prod:syntage.invoices - ELK: Indexado por RFC para búsqueda en tiempo real - Dead Letter Queue: invoices-dlq para mensajes fallidos

Nota: Este template utiliza configuración de 1 worker para procesamiento controlado.

3. items-api

Descripción: Procesa eventos de items desde APIs externas.

Características: - Lee desde Pub/Sub subscription: items-api-subscription - Escribe a BigQuery (tabla específica de items) - ELK deshabilitado por defecto (configurable)

Destinos: - BigQuery: Tabla específica de items - ELK: Deshabilitado por defecto (configurable)

4. cp-api-multischema

Descripción: Procesa eventos de CP (Comprobante de Pago) con soporte para múltiples schemas.

Características: - Procesamiento multi-schema - Manejo de diferentes tipos de comprobantes

5. tax-compliance

Descripción: Procesa eventos relacionados con cumplimiento fiscal (tax compliance).

Características: - Procesamiento de datos de cumplimiento fiscal - Integración con APIs de tax compliance

Flujos de Datos

Cada template procesa datos desde Pub/Sub hacia BigQuery (y opcionalmente ELK):

Flujo General

Pub/Sub Subscription → Dataflow Template → BigQuery (+ ELK si está habilitado)

Configuración de ELK

Los templates de invoices (invoices-webhook e invoices-api) incluyen soporte para escribir a ELK (Elasticsearch):

Parámetros de ELK

  • ELK_ENABLED: Habilita/deshabilita escritura a ELK (true/false)
  • ELK_HOST: Host de Elasticsearch (ej: elasticsearch.solvento.mx)
  • ELK_PORT: Puerto de Elasticsearch (default: 443)
  • ELK_USER: Usuario de Elasticsearch
  • ELK_PASSWORD: Contraseña de Elasticsearch
  • ELK_INDEX_PREFIX: Prefijo del índice (default: invoices)
  • ELK_MAX_RETRIES: Número máximo de reintentos (default: 3)
  • ELK_RETRY_DELAY_MS: Delay base para reintentos en milisegundos (default: 100)

Funcionalidad de ELK

  • Búsqueda en tiempo real: Las invoices se indexan en Elasticsearch para búsqueda rápida
  • Upsert con UUID: Utiliza UUID para identificar documentos únicos
  • Manejo de conflictos: Reintentos automáticos para conflictos de versión
  • Índices por RFC: Crea índices separados por RFC del contribuyente
  • Index templates: Utiliza index templates de ELK para creación automática

Dependencias

Los templates utilizan las siguientes dependencias principales (según requirements.txt):

  • apache-beam[gcp]: Framework Apache Beam con soporte GCP
  • elasticsearch==8.14.0: Cliente de Elasticsearch para escritura a ELK
  • pandas: Procesamiento de datos
  • Otras dependencias específicas por template

Referencias