Ingeniería de datos

API Integration Pipeline

Los workers de Node.js programados por GitHub Actions recopilan datos operativos de Hablla, Zoho Creator, Zenvia Voice y API de SIGE ERP, luego persisten cargas estructuradas en tablas de Supabase SQL para análisis y informes.

Contexto de APIs, integraciones, almacenamiento SQL y arquitectura

API Integration Pipeline resuelve un problema de ingeniería de datos que aparece en muchos entornos operativos: los API de terceros son la fuente de la verdad, pero los análisis y los informes necesitan una capa sin procesar confiable que pueda reproducirse, auditarse y modelarse más adelante. El proyecto mantiene la ingesta separada del modelado de negocios para que los payloads de API permanezcan disponibles incluso cuando cambian las transformaciones de SQL, los paneles de BI y las reglas operativas.

Tiempo de ejecuciónNode.js 20 workers ejecutados localmente o por GitHub Actions.
AlmacenamientoSupabase/PostgreSQL tablas raw_* con retención de payload sin procesar.
APIsHablla personas/tarjetas/servicios, Zoho creador de leads/programación, Zenvia voz, SIGE ERP facturación.
FiabilidadValores de external_id idempotentes, ventanas reproducibles, flujo de trabajo_dispatch, registros desinfectados.

Alcance técnico

  • Stack: JavaScript, Node.js 20, GitHub Actions, Supabase, PostgreSQL, SQL, REST APIs, OAuth, programación cron.
  • Tipo de sistema: Pipeline de ingesta de datos sin procesar, sistema de integración de APIs, capa de preparación de análisis, flujo de trabajo de automatización de backend.
  • Contexto SEO: Arquitectura Supabase SQL, almacenamiento de payload JSON sin procesar, diseño de pipelines ETL, extracción de datos vía API, ingesta idempotente, CRM e integración de ERP vía API.

Trabajo relacionado: Zoho Integration Worker, Hablla Integration Worker, Zenvia Integration Worker y SIGE Integration Worker.

Arquitectura de un vistazo

GitHub Actions / Local Runner -> Node.js ingestion workers -> API de Hablla | API de Zoho Creator | API de Zenvia Voice | API de SIGE ERP -> Supabase PostgreSQL raw_* tables -> SQL-derived layers, analytics, BI, and operational reporting
Hablla ClientesEndpoint de personas a raw_contact_hablla con ID externos de cliente-{id}.
Hablla TarjetasLas tarjetas terminan en raw_events_hablla con ventanas de día rejugables.
Hablla AsistentesResumen diario de servicios a raw_cs_avaliacao_atendimento para evitar errores de agregación de períodos.
Zenvia LlamadasInformes de llamadas de voz a raw_contact_telefonia para análisis operativos de telefonía.
SIGE FaturaciónPedidos facturados a raw_events_faturado con ID externos de pedido-{Codigo}.
Zoho Clientes potencialesEl creador lleva registros a raw_contact_site con modos de sincronización completos y recientes.
Zoho ProgramaciónProgramación de registros en raw_events_agendamento con mes y ventanas recientes.

Documentación del proyecto

API Integration Pipeline

Nodo 20 GitHub Actions Supabase

API Integration Pipeline recopila datos operativos de Hablla, Zoho Creator, Zenvia Voice y API de SIGE ERP. Ejecuta llamadas de API programadas, mantiene la transformación intencionalmente delgada en el límite de ingesta y almacena payloads en tablas de Supabase SQL para modelado, análisis y capas de BI posteriores.

Objetivo

El objetivo principal es desacoplar la recopilación de APIs del modelado analítico. En lugar de escribir directamente en una tabla u hoja de cálculo lista para el panel, cada worker almacena el payload sin procesar con un identificador idempotente, una tabla de destino y suficientes metadatos para admitir el reprocesamiento.

  • Recopile datos de terceros API de forma programada.
  • Conservar registros sin procesar confiables en Supabase/PostgreSQL.
  • Mantenga los payloads históricas reprocesables sin otra llamada externa API.
  • Dejemos que SQL, BI y los modelos operativos evolucionen fuera de la capa de ingesta.

Principios arquitectónicos

  • los salvados payload permanece crudo.
  • La envoltura de ingestión puede variar: external_id, tabla de destino, ventana de recopilación, registros y programación.
  • La tabla sin formato refleja la fuente API. No es el modelo de negocio.
  • Los registros exponen metadatos operativos, no secretos ni payloads totalmente confidenciales.

Por qué GitHub Actions y Supabase

Para una ingesta ligera, GitHub Actions más Supabase elimina la necesidad de un worker permanente o una máquina virtual. Los flujos de trabajo programados brindan auditabilidad y reproducción manual con workflow_dispatch, secretos GitHub centralizados y control de costos simple, mientras que Supabase actúa como una capa de almacenamiento SQL duradera para registros sin procesar.

SQL y estrategia de datos sin procesar

La decisión de diseño importante de SQL es almacenar primero las salidas sin procesar de APIs y luego derivar modelos normalizados. tablas como raw_contact_hablla, raw_events_hablla, raw_contact_telefonia, raw_events_faturado, raw_contact_site, y raw_events_agendamento puede admitir vistas SQL posteriores, tablas materializadas, uniones y conjuntos de datos compatibles con BI sin perder la forma del proveedor original.

el external_id El campo hace que las ventanas de recopilación repetidas sean seguras: el mismo período de cinco, siete, quince o meses se puede reproducir sin duplicar filas cuando se aplica la lógica de inserción de manera consistente.

Integraciones actuales

  • Hablla Clientes: endpoint de personas a raw_contact_hablla, usando client-{id}.
  • Hablla Tarjetas: endpoint de tarjetas a raw_events_hablla, con una ventana reciente predeterminada.
  • Hablla Asistentes: resumen de servicios para raw_cs_avaliacao_atendimento, recogido día a día.
  • Zenvia Llamadas: informes de llamadas de voz a raw_contact_telefonia, generalmente adecuado para recorridos diarios de cierre del día.
  • SIGE Faturamento: pedidos facturados a raw_events_faturado, usando pedido-{Codigo}.
  • Zoho Clientes potenciales completos y recientes: El creador principal informa a raw_contact_site.
  • Zoho Programación completa y reciente: programar informes para raw_events_agendamento.

Modelo de programación

El proyecto combina frecuentes ventanas cortas con ventanas más grandes, menos frecuentes. Hablla clientes/tarjetas y trabajos recientes Zoho se ejecutan varias veces al día. Zenvia, SIGE, Hablla asistentes y cargas completas Zoho se ejecutan diariamente. Esto reduce la presión de API, mantiene disponibles datos operativos actualizados y reduce el riesgo de superposición del flujo de trabajo.

Seguridad y registros

Debido a que los flujos de trabajo pueden exponer metadatos de ejecución pública, los registros de errores se desinfectan. El proyecto evita el registro de tokens, secretos, payloads sin procesar completas y respuestas completas de error del proveedor. Los registros se centran en códigos de estado, mensajes resumidos y contexto operativo que se pueden depurar sin filtrar credenciales.

Migración desde Google Sheets

El patrón anterior sincronizaba los datos de API directamente en Google Sheets después del mapeo y filtrado iniciales. El pipeline de ingesta bruta de APIs mueve el límite de almacenamiento antes: los payloads sin procesar de APIs se capturan en Supabase primero, luego el modelado SQL y el análisis se realizan en sentido descendente. Esto mejora la auditabilidad, la rejugabilidad y la resiliencia frente a las reglas comerciales cambiantes.

Stack tecnológico

Node.js 20
JavaScript
GitHub Actions
Supabase
PostgreSQL / SQL
REST APIs
OAuth
Flujos de trabajo cron

Ver el código fuente

Ver en GitHub