Engenharia de Dados

API Integration Pipeline

workers Node.js programados por GitHub Actions coletam dados operacionais de Hablla, Zoho Creator, Zenvia Voice e SIGE APIs de ERP e, em seguida, persistem payloads estruturados em tabelas do Supabase SQL para análises e relatórios.

Contexto de APIs, integrações, armazenamento SQL e arquitetura

API Integration Pipeline resolve um problema de engenharia de dados que aparece em muitos ambientes operacionais: APIs de terceiros são a fonte da verdade, mas análises e relatórios precisam de uma camada bruta confiável que possa ser reproduzida, auditada e modelada posteriormente. O projeto mantém a ingestão separada da modelagem de negócios para que as payloads de API permaneçam disponíveis mesmo quando as transformações SQL, os painéis de BI e as regras operacionais mudam.

Tempo de execuçãoNode.js 20 workers executados localmente ou por GitHub Actions.
ArmazenamentoSupabase/PostgreSQL tabelas raw_* com retenção de payload bruta.
APIsHablla pessoas/cartões/serviços, Zoho Leads/agendamento de criadores, Zenvia Voice, SIGE ERP cobrança.
ConfiabilidadeValores idempotentes de external_id, janelas reproduzíveis, workflow_dispatch, logs higienizados.

Escopo Técnico

  • Stack: JavaScript, Node.js 20, GitHub Actions, Supabase, PostgreSQL, SQL, REST APIs, OAuth, agendamento cron.
  • Tipo de sistema: pipeline de ingestão de dados brutos, sistema de integração de APIs, camada de teste de análise, fluxo de trabalho de automação de backend.
  • Contexto SEO: Arquitetura Supabase SQL, armazenamento de payload JSON bruto, design de pipeline ETL, extração de dados via API, ingestão idempotente e integração de CRM/ERP via API.

Trabalho relacionado: Zoho Integration Worker, Hablla Integration Worker, Zenvia Integration Worker e SIGE Integration Worker.

Visão geral da arquitetura

GitHub Actions / Local Runner -> Node.js ingestion workers -> Hablla API | Zoho Creator API | Zenvia Voice API | SIGE API de ERP -> Supabase PostgreSQL raw_* tables -> SQL-derived layers, analytics, BI, and operational reporting
Hablla ClientesEndpoint de pessoas para raw_contact_hablla com IDs externos client-{id}.
Hablla CartõesEndpoint dos cartões para raw_events_hablla com janelas de dia reproduzíveis.
Hablla AtendentesResumo diário dos serviços para raw_cs_avaliacao_atendimento para evitar erros de agregação de períodos.
Zenvia ChamadasRelatórios de chamadas de voz para raw_contact_telefonia para análise operacional de telefonia.
SIGE FaturamentoPedidos faturados para raw_events_faturado com IDs externos pedido-{Codigo}.
Zoho LeadsRegistros de leads do criador para raw_contact_site com modos de sincronização completos e recentes.
Zoho AgendamentoAgendamento de registros para raw_events_agendamento com mês e janelas recentes.

Documentação do Projeto

API Integration Pipeline

Nó 20 GitHub Actions Supabase

API Integration Pipeline coleta dados operacionais de Hablla, Zoho Creator, Zenvia Voice e SIGE APIs de ERP. Ele executa chamadas de API programadas, mantém a transformação intencionalmente reduzida no limite de ingestão e armazeno payloads em tabelas do Supabase SQL para modelagem, análise e camadas de BI posteriores.

Objetivo

O objetivo principal é dissociar a coleta via API da modelagem analítica. Em vez de gravar diretamente em uma tabela ou planilha pronta para painel, cada worker armazena a carga bruta com um identificador idempotente, uma tabela de destino e metadados suficientes para suportar o reprocessamento.

  • Colete dados API de terceiros de acordo com uma programação.
  • Persista registros brutos confiáveis em Supabase/PostgreSQL.
  • Mantenha as cargas históricas reprocessáveis sem outra chamada à API externa.
  • Deixe SQL, BI e modelos operacionais evoluirem fora da camada de ingestão.

Princípios Arquitetônicos

  • Os salvos payload permanece cru.
  • O envelope de ingestão pode variar: external_id, tabela de destino, janela de coleta, logs e agendamento.
  • A tabela bruta espelha a fonte API. Não é o modelo de negócios.
  • Os logs expõem metadados operacionais, não segredos ou cargas totalmente confidenciais.

Por que GitHub Actions e Supabase

Para ingestão leve, GitHub Actions mais Supabase elimina a necessidade de um worker permanente ou VM. Fluxos de trabalho agendados fornecem auditabilidade, reprodução manual com workflow_dispatch, segredos GitHub centralizados e controle de custos simples, enquanto Supabase atua como uma camada de armazenamento SQL durável para registros brutos.

SQL e estratégia de dados brutos

A importante decisão de projeto SQL é armazenar primeiro as saídas brutas de APIs e derivar modelos normalizados posteriormente. Tabelas como raw_contact_hablla, raw_events_hablla, raw_contact_telefonia, raw_events_faturado, raw_contact_sitee raw_events_agendamento pode oferecer suporte a visualizações SQL downstream, tabelas materializadas, junções e conjuntos de dados compatíveis com BI sem perder o formato original do provedor.

O external_id O campo torna seguras as janelas de coleta repetidas: o mesmo período de cinco, sete, quinze ou mensal pode ser reproduzido sem duplicar linhas quando a lógica de upsert é aplicada de forma consistente.

Integrações atuais

  • Hablla Clientes: pessoas endpoint para raw_contact_hablla, usando client-{id}.
  • Hablla Cartões: endpoint dos cartões para raw_events_hablla, com uma janela recente padrão.
  • Hablla Atendentes: resumo de serviços para raw_cs_avaliacao_atendimento, coletados dia a dia.
  • Zenvia Chamadas: relatórios de chamadas de voz para raw_contact_telefonia, geralmente adequado para execuções diárias no final do dia.
  • SIGE Faturamento: pedidos faturados para raw_events_faturado, usando pedido-{Codigo}.
  • Zoho Leads completos e recentes: Relatórios de leads de criadores para raw_contact_site.
  • Zoho Agendamento Completo e Recente: agendar relatórios para raw_events_agendamento.

Modelo de agendamento

O projeto mistura janelas curtas frequentes com janelas maiores menos frequentes. Hablla clientes/cartões e trabalhos recentes Zoho são executados várias vezes por dia. Zenvia, SIGE, Hablla atendentes e cargas completas Zoho são executadas diariamente. Isso reduz a pressão sobre a API, mantém disponíveis dados operacionais atualizados e reduz o risco de sobreposição de fluxo de trabalho.

Segurança e registros

Como os fluxos de trabalho podem expor metadados de execução pública, os logs de erros são limpos. O projeto evita registrar tokens, segredos, cargas brutas completas e respostas completas a erros do provedor. Os logs concentram-se em códigos de status, mensagens resumidas e contexto operacional que podem ser depurados sem vazamento de credenciais.

Migração do Google Sheets

O padrão mais antigo sincronizava dados via API diretamente no Google Sheets após mapeamento e filtragem iniciais. O pipeline de ingestão bruta de APIs move o limite de armazenamento mais cedo: os payloads brutos de APIs são capturadas em Supabase primeiro e, em seguida, a modelagem e a análise SQL acontecem no downstream. Isso melhora a auditabilidade, a capacidade de reprodução e a resiliência contra mudanças nas regras de negócios.

Stack tecnológica

Node.js 20
JavaScript
GitHub Actions
Supabase
PostgreSQL / SQL
REST APIs
OAuth
Fluxos de trabalho Cron

Veja o código-fonte

Ver no GitHub