E01 - Plataforma de Inteligência Artificial
Arquitetura Técnica Detalhada
Versão: 2.0 | Data: 05/01/2026 | API Base: ConectEnvios API V1
1. Visão Geral
1.1 Diagrama de Arquitetura
┌─────────────────────────────────────────────────────────────────────────────────┐
│ PLATAFORMA E01 - IA │
├────────────────────────── ───────────────────────────────────────────────────────┤
│ │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ API GATEWAY (Kong) │ │
│ │ Rate Limiting │ Auth │ Logging │ Metrics │ Load Balancing │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌─────────────────┼─────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐ │
│ │ Webhook Handler │ │ NLP Processor │ │ Message Sender │ │
│ │ (WhatsApp) │ │ (GPT-4 + Functions)│ │ (Outbound) │ │
│ └─────────────────────┘ └─────────────────────┘ └─────────────────────┘ │
│ │ │ │ │
│ └────────────────────────┼────────────────────────┘ │
│ ▼ │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ INTEGRATIONS LAYER │ │
│ │ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌───────────────────┐ │ │
│ │ │ WhatsApp │ │ OpenAI │ │ ConectEnvios │ │ │
│ │ │ Business │ │ GPT-4 │ │ API V1 │ │ │
│ │ │ API │ │ │ │ (Multi-Carrier) │ │ │
│ │ └─────────────┘ └─────────────┘ └───────────────────┘ │ │
│ │ │ │ │
│ │ ┌──────────────────┼──────────────────┐ │ │
│ │ ▼ ▼ ▼ │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ Correios │ │ Jadlog │ │ Loggi │ │ │
│ │ │ Azul │ │ │ │ JTExpress│ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ DATA LAYER │ │
│ │ │ │
│ │ ┌───────────────────┐ ┌───────────────────┐ ┌─────────────────┐ │ │
│ │ │ PostgreSQL │ │ Redis │ │ RabbitMQ │ │ │
│ │ │ (Persistence) │ │ (Cache) │ │ (Queues) │ │ │
│ │ └───────────────────┘ └───────────────────┘ └─────────────────┘ │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
2. Componentes Principais
2.1 Webhook Handler
Recebe mensagens do WhatsApp e publica na fila de processamento.
// src/webhooks/whatsapp.controller.ts
@Controller('webhook')
export class WhatsAppWebhookController {
@Post('whatsapp')
async handleWebhook(
@Body() payload: WhatsAppWebhookPayload,
@Headers('x-hub-signature-256') signature: string
) {
// Validar assinatura
if (!this.validateSignature(payload, signature)) {
throw new UnauthorizedException('Invalid signature');
}
// Publicar na fila para processamento assíncrono
await this.messageQueue.publish('inbound.messages', payload);
return { status: 'received' };
}
}
2.2 NLP Processor com Function Calling
Processa mensagens usando GPT-4 e executa funções via API ConectEnvios.
// src/services/nlp-processor.service.ts
export class NLPProcessor {
private openai = new OpenAI();
private conectEnvios = new ConectEnviosAPI();
async processMessage(message: InboundMessage): Promise<BotResponse> {
const completion = await this.openai.chat.completions.create({
model: 'gpt-4-turbo',
messages: this.buildMessages(message),
tools: this.getToolDefinitions(),
tool_choice: 'auto'
});
// Executar function calls
if (completion.choices[0].message.tool_calls) {
return this.executeFunctions(completion.choices[0].message.tool_calls);
}
return { text: completion.choices[0].message.content };
}
private async executeFunctions(toolCalls: ToolCall[]): Promise<BotResponse> {
for (const call of toolCalls) {
switch (call.function.name) {
case 'get_shipping_quote':
return this.executeShippingQuote(JSON.parse(call.function.arguments));
case 'track_package':
return this.executeTracking(JSON.parse(call.function.arguments));
case 'validate_cep':
return this.executeCEPValidation(JSON.parse(call.function.arguments));
}
}
}
private async executeShippingQuote(params: ShippingParams): Promise<BotResponse> {
// Chama POST /package/shipping da API ConectEnvios
const response = await this.conectEnvios.post('/package/shipping', {
type: params.type,
weight: params.weight,
height: params.height,
width: params.width,
length: params.length,
addr_from_cep: params.origin_cep,
addr_to_cep: params.destination_cep
});
return this.formatQuoteResponse(response.data);
}
}
2.3 Cliente API ConectEnvios
// src/clients/conectenvios.ts
import axios, { AxiosInstance } from 'axios';
export class ConectEnviosAPI {
private client: AxiosInstance;
constructor() {
this.client = axios.create({
baseURL: process.env.CONECTENVIOS_API_URL || 'https://app.conectenvios.com.br/api/v1',
headers: {
'Accept': 'application/json',
'Authorization': `Bearer ${process.env.CONECTENVIOS_API_TOKEN}`
},
timeout: 10000
});
}
async get(endpoint: string, params?: any): Promise<any> {
const response = await this.client.get(endpoint, { params });
return response.data;
}
async post(endpoint: string, data: FormData | object): Promise<any> {
const response = await this.client.post(endpoint, data, {
headers: { 'Content-Type': 'multipart/form-data' }
});
return response.data;
}
}
3. Fluxo de Dados
3.1 Fluxo de Cotação
┌ ─────────────────────────────────────────────────────────────────────────────────┐
│ FLUXO DE COTAÇÃO DE FRETE │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ 1. Cliente envia: "Quanto custa enviar de 70000-000 para 01310-100, 2kg?" │
│ │
│ 2. GPT-4 extrai parâmetros e chama function: get_shipping_quote │
│ │
│ 3. Sistema valida CEPs via GET /cep/address │
│ │
│ 4. Sistema chama POST /package/shipping com form-data │
│ │
│ 5. API retorna array de ShippingOption (múltiplas transportadoras) │
│ │
│ 6. Sistema formata resposta e envia via WhatsApp │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
3.2 Fluxo de Rastreamento
┌─────────────────────────────────────────────────────────────────────────────────┐
│ FLUXO DE RASTREAMENTO │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ 1. Cliente envia: "Rastrear envio 12345" │
│ │
│ 2. GPT-4 identifica intenção e chama function: track_package │
│ │
│ 3. Sistema verifica cache Redis (key: tracking:12345) │
│ │
│ 4. [Cache miss] Chama GET /package/track/12345 │
│ │
│ 5. API retorna array de TrackingEvent ordenado │
│ │
│ 6. Sistema salva no cache (TTL: 5min) e formata resposta │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
4. Cache Strategy
4.1 Redis Keys
# Rastreamento (GET /package/track/:id)
tracking:{package_id}:
ttl:
in_transit: 300 # 5 minutos
out_for_delivery: 60 # 1 minuto
delivered: 86400 # 24 horas
# CEP (GET /cep/address)
cep:{zipcode}:
ttl: 86400 # 24 horas
# Cotação (POST /package/shipping)
quote:{origin}:{destination}:{weight}:
ttl: 3600 # 1 hora
# Contexto de conversa
context:{phone}:
ttl: 1800 # 30 minutos
5. Variáveis de Ambiente
# ConectEnvios API V1
CONECTENVIOS_API_URL=https://app.conectenvios.com.br/api/v1
CONECTENVIOS_API_TOKEN=your_bearer_token
# Staging: https://staging.conectenvios.com.br/api/v1/
# WhatsApp Business API
WHATSAPP_PHONE_NUMBER_ID=your_phone_number_id
WHATSAPP_ACCESS_TOKEN=your_access_token
WHATSAPP_APP_SECRET=your_app_secret
# OpenAI
OPENAI_API_KEY=your_openai_key
# Database
DATABASE_URL=postgresql://user:pass@host:5432/db
# Redis
REDIS_URL=redis://host:6379
# RabbitMQ
RABBITMQ_URL=amqp://user:pass@host:5672
6. Histórico de Revisões
| Versão | Data | Descrição |
|---|---|---|
| 1.0 | 05/01/2026 | Versão inicial |
| 2.0 | 05/01/2026 | Integração com ConectEnvios API V1 |