Integration Platform

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 é publicado como backend dinâmico de conectores para outros produtos do ecossistema, 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, e ele funciona como interruptor geral: um conector ou uma integração inativa barra qualquer execução antes de começar.
• 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 quatro 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, e variáveis interpoladas no script (``) viram parâmetros de comando reais, nunca concatenação de string, o que fecha a porta para injeção de SQL. SELECT devolve linhas; comandos de escrita devolvem a contagem de linhas afetadas.

SMTP Send. Envia e-mail via MailKit usando as credenciais do conector, com suporte a corpo em template interpolado. É o tipo de etapa que fecha o caso de uso de notificar por e-mail como parte de um fluxo maior, sem depender de um serviço de e-mail externo dentro do pipeline.

Cada etapa também pode ser condicional: uma expressão JavaScript curta (5s, 10 MB) decide se aquela etapa roda antes de gastar tempo com ela, útil para pipelines que ramificam conforme o resultado de uma etapa anterior.

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.
• Rotina agendada: uma rotina roda um pipeline em intervalos configurados, com o próximo disparo calculado sem deriva de horário a cada execução.
• Contrato de serviço: um catálogo de intenções de negócio (por exemplo, criar cobrança, gerar Pix, consultar título liquidado, enviar assinatura, enviar e-mail, enviar WhatsApp) resolve dinamicamente qual integração e pipeline atendem aquele contrato para o tenant, com schema de entrada e saída próprio e callback assíncrono de resultado.
• Via webhook: conectores de integrações que aceitam webhook recebem um token próprio; o endpoint público valida esse token dentro do próprio pipeline, em tempo constante, antes de deixar o restante do fluxo prosseguir.

Contratos de serviço e callback

Um contrato de serviço é a forma do sistema expor uma capacidade de negócio (não uma integração específica) para quem consome a plataforma: quem chama pede "emitir uma cobrança" ou "enviar um WhatsApp", sem saber qual integração concreta atende aquilo para aquele tenant. Cada contrato ativo aceita um payload de entrada validado por schema e devolve uma saída no mesmo formato.

Quando o resultado não está disponível na hora (por exemplo, aguardando confirmação de um gateway), a plataforma entrega o resultado depois por callback, com política de retry de backoff exponencial entre tentativas, até um número máximo antes de desistir. É esse mecanismo que sustenta fluxos assíncronos de cobrança e pagamento sem exigir polling do lado de quem consome.

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 em português (contas-a-receber, contas-a-pagar, assinatura-digital, email, whatsapp, entre outras). Sistemas que consomem o Integration Platform pedem conectores pela intenção (por exemplo, "me dê os conectores de contas a receber") 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

A superfície de risco de um motor que faz chamadas de saída configuráveis por quem administra o tenant é levada a sério em várias camadas: chamadas HTTP de saída passam por uma checagem que bloqueia destinos internos (loopback, redes privadas, endereços de metadados de nuvem) para evitar SSRF; conectores que precisam de certificado cliente suportam mTLS com certificado A1; atributos marcados como sensíveis nunca são expostos a um script de etapa, só o necessário chega ao contexto do Jint; e o token de webhook é validado por comparação em tempo constante, não por igualdade simples de string.

A API em si é 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, com cada tenant tendo sua própria chave, nunca compartilhada. 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.

Conectores reais

O catálogo não é um exemplo de brinquedo: tem conectores reais para bancos e cobrança (Asaas, com Banco do Brasil, Inter, Itaú, Santander e Sicredi mantidos no catálogo), assinatura digital (ClickSign e ZapSign), e-mail (SMTP e provedores transacionais como Mailgun) e WhatsApp (WhatsApp Cloud API). É esse catálogo que alimenta os contratos de serviço com integrações que realmente conversam com o mundo externo.

Consumido pelo Mainstay

O Integration Platform é publicado como o backend dinâmico de conectores do Mainstay, o sistema operacional para agências que hoje está em desenvolvimento de MVP: o Mainstay consulta, cria e edita conectores via API proxy autenticada por segredo de integração, e o desenho do módulo financeiro já parte da categoria de contas a receber para resolver 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.

Qualidade

O sistema tem 261 casos de teste cobrindo o motor de execução, a avaliação de condições, a parametrização de SQL, o guard de SSRF e os conectores reais, o que dá confiança para evoluir integrações que lidam com dinheiro e dados sensíveis sem regressão silenciosa.