Integration Platform

Motor de orquestração de integrações: em vez de espalhar chamadas entre sistemas por jobs e serviços soltos, transforma integração em objeto configurável, conector parametrizado e pipeline executável, com execução observável e depurável.

Visão geral

O Integration Platform é o orquestrador técnico de integrações do ecossistema. A ideia central é tirar a lógica de integração de dentro do código de cada sistema e transformá-la em algo que se modela, parametriza e executa: uma integração descreve um tipo de conexão, um conector é uma instância concreta com credenciais reais, e um pipeline é um fluxo executável de etapas.

Construído sobre o framework base (Archon), ele herda pipeline HTTP, multi-tenant, persistência e autorização, e é consumido por outros produtos do ecossistema como backend dinâmico de conectores, autenticado por segredo de integração.

O modelo: integração, conector, pipeline

A força do sistema está em separar três camadas que normalmente vivem misturadas no código:

• Integração — o tipo de conexão (um gateway de pagamento, um banco, um marketplace). Tem categoria, identificador lógico e atributos configuráveis, e pode declarar que aceita webhook.
• Conector — a instância concreta daquela integração, com os valores reais dos atributos (URLs, credenciais, tokens). É o conector que entra na execução.
• Pipeline — o fluxo executável dentro de uma integração, composto por etapas ordenadas. Uma integração pode ter vários pipelines.

Essa separação é o que permite reusar a mesma integração em contextos diferentes só trocando o conector, sem reescrever fluxo.

O motor de execução

O coração do sistema é o motor que executa os pipelines. Ele carrega o conector e seus atributos, monta o pipeline com as etapas e recursos associados, abre um registro de execução e percorre as etapas ativas em ordem, dentro de um contexto compartilhado.

O detalhe que torna isso um motor de verdade, e não um loop de chamadas, é a passagem de dados entre etapas. Depois de cada etapa, o engine inspeciona o corpo da resposta e, quando ela é JSON ou vem com envelope (result, data, response, value), promove as propriedades para um conjunto de variáveis disponíveis às etapas seguintes. A partir daí, qualquer etapa pode interpolar dinamicamente atributos do conector, dados do payload e variáveis produzidas pelas etapas anteriores.

A saída final não é o payload bruto da última chamada: é uma estrutura acumulada por etapa, e cada etapa decide se contribui ou não para esse resultado. Tudo isso é registrado com duração, status e logs.

Tipos de etapa

O pipeline compõe três tipos de etapa, cada um cobrindo uma necessidade real de integração:

HTTP Request. Reusa uma chamada HTTP cadastrada (método, URL, headers e body como templates) e interpola tudo no momento da execução. Suporta os verbos REST usuais e registra request e response. Respostas binárias viram um envelope com base64, nome de arquivo, mime type e tamanho, e o frontend já tem fluxo para baixar esse resultado no debug.

JavaScript Function. Executa código JavaScript armazenado, usando o Jint num ambiente isolado que expõe variables, payload, attributes e result ao script. É sandboxed de verdade: timeout de 30s, teto de 50 MB de memória e limite de 100 níveis de recursão. Serve para transformar e compor payloads entre etapas sem precisar de um serviço externo.

Execute Script. Roda SQL em bancos externos (executor real para PostgreSQL e SQL Server). Tem bloqueios de segurança no domínio: UPDATE e DELETE sem WHERE são rejeitados. SELECT devolve linhas; comandos de escrita devolvem a contagem de linhas afetadas.

Modos de execução

O mesmo pipeline pode ser disparado de várias formas, conforme quem chama:

• Manual — escolhe conector e pipeline, envia um payload opcional e recebe o resumo da execução.
• Por identificador lógico — dispara por identificadores de integração e pipeline, útil quando o sistema chamador conhece os nomes lógicos e não os IDs internos do banco.
• Em fila — o item entra numa fila persistida com prioridade e agendamento e é processado de forma assíncrona.
• Via webhook — conectores de integrações que aceitam webhook recebem um token próprio; o endpoint público valida esse token, identifica o conector e dispara o pipeline.

Debug passo a passo

Além de executar, o sistema permite depurar. O debugger mantém uma sessão de execução em memória e avança etapa por etapa: inicia a sessão, executa a próxima etapa sob demanda, acumula logs e saídas a cada passo e finaliza ao terminar. Dá para escolher a etapa inicial, comparar os outputs de cada etapa, inspecionar request e response e baixar respostas binárias.

É a diferença entre "rodou e deu erro" e conseguir ver exatamente em qual etapa, com qual entrada e qual resposta o fluxo quebrou.

Tratamento de erro

Cada etapa define a estratégia em caso de falha. Com Stop, o erro interrompe o pipeline e a execução termina como falha. Com Continue, a falha é registrada mas o fluxo segue, e a execução pode terminar como parcial. Isso permite modelar tanto integrações estritas (qualquer erro aborta) quanto tolerantes (uma etapa opcional pode falhar sem derrubar o resto).

Observabilidade

Toda execução é rastreável. O sistema guarda o registro da execução (tipo, status, entrada, saída, erros, início, fim e duração) e logs detalhados por etapa, com nível, mensagem, request, response, status HTTP e duração. Há ainda um mapa de referências entre identificadores internos e externos por conector (por exemplo, um produto interno e o mesmo produto num marketplace), que é o que mantém os dois lados de uma integração sincronizados.

Categorias semânticas

Um detalhe de design que vale destacar: as integrações têm categorias com um identificador semântico (payment, banking, digital-signature, email, entre outras). Sistemas que consomem o Integration Platform pedem conectores pela intenção (por exemplo, "me dê os conectores de banco") em vez de fazer string-matching no nome da integração. Isso desacopla o consumidor da nomenclatura e evita o tipo de quebra silenciosa que acontece quando alguém renomeia uma integração.

Segurança e multi-tenant

A API é protegida por um único atributo de autorização que aceita tanto um Bearer JWT de usuário quanto um segredo de integração entre serviços (comparado em tempo constante), com cada tenant tendo sua própria chave, nunca compartilhada. Os endpoints de webhook são públicos por necessidade, mas validam o token do conector antes de disparar qualquer pipeline.

Quando integrado ao Identity Management, o sistema usa o login centralizado, valida sessão a cada requisição e sincroniza seus recursos protegidos no startup, de forma que autorização de tela e de API têm a mesma origem.

Consumido em produção

O Integration Platform não é um exercício isolado: ele é o backend dinâmico de conectores do Kanvas (o sistema operacional para agências), que consulta, cria e edita conectores via API proxy autenticada por segredo de integração. O módulo financeiro do Kanvas, por exemplo, usa a categoria de banco para resolver suas contas a partir de conectores reais.

Dashboard

O dashboard consolida a operação: integrações, conectores e pipelines ativos, execuções e erros do dia, taxa de sucesso, volume mensal e execuções recentes. É a leitura rápida de saúde de tudo que passa pelo motor.

Diferenciais do projeto

• motor de execução com passagem de variáveis entre etapas e interpolação de conector, payload e resultados anteriores;
• três tipos de etapa cobrindo HTTP, JavaScript (sandbox com limites de tempo, memória e recursão) e SQL (com bloqueios de segurança);
• cinco modos de disparo: manual, por identificador, fila, webhook e debug passo a passo;
• estratégia de erro por etapa (interromper ou continuar), com status final parcial;
• observabilidade completa: execuções, logs de request/response e mapa de referências interno/externo;
• categorias semânticas que desacoplam o consumidor da nomenclatura das integrações;
• autorização unificada para usuários e serviços, multi-tenant com chave por tenant, consumido de fato por outro produto.

Resumo executivo

O Integration Platform transforma integração entre sistemas em algo configurável e operável: integrações que se modelam, conectores que se parametrizam e pipelines que se compõem e se executam, com etapas HTTP, JavaScript e SQL, vários modos de disparo, depuração passo a passo e rastreabilidade ponta a ponta.

O ponto mais sólido do projeto é o motor de execução e a camada operacional em volta dele, e o fato de ele já sustentar, em produção, os conectores dinâmicos de outro sistema do ecossistema.