Hub API

A Hub API é o gateway REST central do Simplafy Hub, a plataforma no-code de criação e operação de agentes de IA construída sobre LangGraph. Toda interação programática com agentes, organizações, credenciais, conversas e integrações passa por esta API.

A base URL de produção é https://hub.simplafy.com.br/api/v1. A documentação interativa Swagger está publicada em https://hub.simplafy.com.br/docs.

O que é o Hub API

O Hub API é uma aplicação Next.js 15 (Route Handlers, sem UI) que expõe os recursos do Hub para clientes internos e externos. Ela atua como camada de orquestração entre:

• O portal administrativo (apps/web) e o portal white-label (apps/client-portal), que consomem a API via React Query.
• O servidor LangGraph (apps/langgraph-server), onde rodam os agentes Python.
• O servidor MCP (apps/mcp-server), que expõe ferramentas para os agentes via Model Context Protocol.
• O servidor RAG (apps/rag-server), responsável por busca vetorial sobre pgvector.

Características principais:

• Autenticação JWT com jose (HS256), access token de 15 minutos e refresh token de 7 dias com rotação e detecção de reuso.
• Validação de schema com Zod e geração de OpenAPI via @asteasolutions/zod-to-openapi.
• Motor de permissões hierárquico no formato resource:action[] com suporte a wildcard, resolvido a partir dos claims do JWT (zero queries no banco por request).
• Isolamento multi-tenant por organização, com credenciais escopadas por (organizationId, key).

Casos de uso

A Hub API atende cenários como:

• Criar e gerenciar agentes no-code, incluindo prompts, ferramentas habilitadas e variáveis de configuração.
• Provisionar organizações e usuários, com convites, papéis e permissões granulares.
• Gerenciar credenciais de integrações (API keys, OAuth tokens, bearer tokens, valores customizados) por organização ou por agente.
• Ingerir mensagens de canais externos (WhatsApp via Evolution API, e demais adapters) no store canônico de conversas.
• Consultar conversas, leads e histórico do CRM unificado.
• Disparar e acompanhar execuções de agentes LangGraph via passthrough.
• Servir o portal white-label com configurações por organização (OrgPortalConfig, branding, módulos habilitados, blocos de dashboard).

Base URL e ambientes

A API roda na porta 3002 em desenvolvimento local e é exposta em produção via Ingress Kubernetes em simplafy-hub-api:3002.

Todas as chamadas devem usar HTTPS em produção e enviar o token JWT no header Authorization: Bearer <token>. Requisições server-to-server internas usam o segredo MCP_INTERNAL_SECRET para bypass administrativo controlado.

Stack técnico

A Hub API é construída sobre as seguintes tecnologias e bibliotecas principais (extraídas de apps/api/package.json):

• Framework: Next.js 15.4 (App Router, Route Handlers, modo standalone) sobre React 19.
• Runtime: Node 20+ em containers Linux, TypeScript 5.7.
• Autenticação: jose 6 para emissão e verificação de JWT, bcryptjs para hashing.
• Validação e OpenAPI: zod 3 + @asteasolutions/zod-to-openapi + @apidevtools/swagger-parser, com Swagger UI servido por swagger-ui-react.
• Persistência: Prisma 6 sobre PostgreSQL (schema compartilhado com apps/web).
• Cache e filas: ioredis para Redis.
• Integrações de agente: @langchain/langgraph-sdk e langgraph-nextjs-api-passthrough para encaminhar execuções ao servidor LangGraph.
• MCP: geração dinâmica de tools a partir de OpenAPI via openapi-mcp-generator.
• Email: resend 6 para envio transacional.
• Observabilidade: @sentry/nextjs (GlitchTip self-hosted) e @opentelemetry/sdk-trace-base + exporter OTLP HTTP para tracing distribuído.
• Utilitários internos: @simplafy/channel-formatter (formatação de mensagens por canal) e @simplafy/pii-utils (mascaramento de PII).
• Testes: vitest 3.

O código segue regras de estilo do monorepo: sem console.log (apenas console.warn/console.error), variáveis não usadas com prefixo _, e formatação Prettier obrigatória no CI.

Próximos passos