E01 - Plataforma de Inteligência Artificial

Especificação de Requisitos

Versão: 2.0 | Data: 05/01/2026 | API Base: ConectEnvios API V1

---

1. Introdução

1.1 Propósito

Este documento especifica os requisitos funcionais e não-funcionais para a Plataforma de IA do módulo E01 do projeto TECNOVA III.

1.2 Escopo

A plataforma integra:

• WhatsApp Business API para comunicação com clientes
• OpenAI GPT-4 para processamento de linguagem natural
• API ConectEnvios V1 para operações de frete

1.3 Documentos Relacionados

• Arquitetura Técnica
• Casos de Uso
• Contratos de API
• Modelo de Dados

---

2. Requisitos Funcionais

2.1 RF-E01-001: Integração WhatsApp Business API

Atributo	Descrição
Prioridade	P0 - Crítico
Dependências	Meta Business Account, Webhook Server

Funcionalidades:

• Receber mensagens via webhook (text, image, document, location, interactive)
• Enviar respostas formatadas (text, template, interactive buttons/lists)
• Validar assinatura SHA256 do webhook
• Processar message status updates (sent, delivered, read)

2.2 RF-E01-002: Integração OpenAI GPT-4

Atributo	Descrição
Prioridade	P0 - Crítico
API	gpt-4-turbo com Function Calling

Function Calling Schema:

{
    "tools": [
        {
            "type": "function",
            "function": {
                "name": "get_shipping_quote",
                "description": "Calcula cotação de frete usando POST /package/shipping",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "origin_cep": { "type": "string", "pattern": "^\\d{8}$" },
                        "destination_cep": { "type": "string", "pattern": "^\\d{8}$" },
                        "weight": { "type": "integer", "description": "Peso em gramas" },
                        "width": { "type": "integer", "description": "Largura em cm" },
                        "height": { "type": "integer", "description": "Altura em cm" },
                        "length": { "type": "integer", "description": "Comprimento em cm" },
                        "type": { "type": "string", "enum": ["box", "letter"] }
                    },
                    "required": ["origin_cep", "destination_cep", "weight", "type"]
                }
            }
        },
        {
            "type": "function",
            "function": {
                "name": "track_package",
                "description": "Rastreia envio usando GET /package/track/:id",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "package_id": { "type": "integer" }
                    },
                    "required": ["package_id"]
                }
            }
        },
        {
            "type": "function",
            "function": {
                "name": "validate_cep",
                "description": "Valida CEP usando GET /cep/address",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "cep": { "type": "string", "pattern": "^\\d{8}$" }
                    },
                    "required": ["cep"]
                }
            }
        }
    ]
}

Mapeamento Functions → API ConectEnvios:

Function	Endpoint API	Método
get_shipping_quote	/package/shipping	POST
track_package	/package/track/:id	GET
validate_cep	/cep/address/?cep={cep}	GET
get_cities	/city	GET
get_carriers	/postal_company	GET

2.3 RF-E01-003: Rastreamento de Envios

Consulta status via API ConectEnvios.

Endpoint: GET /package/track/:id

Estrutura TrackingEvent:

interface TrackingEvent {
    city_id: number | null;
    city: string;
    state_id: number | null;
    state: string;
    correios_date: string;        // ISO 8601 UTC+0
    correios_type: string | null; // PO, RO, DO, OEC, BDE
    correios_status: string | null;
    description: string;
    error_message: string | null;
}

2.4 RF-E01-004: Cotação de Frete

Calcula frete via API ConectEnvios.

Endpoint: POST /package/shipping

Parâmetros (form-data):

Campo	Tipo	Obrigatório	Descrição
type	string	Sim	"box" ou "letter"
weight	integer	Sim	Peso em gramas
height	integer	Para box	Altura em cm
width	integer	Para box	Largura em cm
length	integer	Para box	Comprimento em cm
addr_from_cep	string	Sim	CEP origem (8 dígitos)
addr_to_cep	string	Sim	CEP destino (8 dígitos)
declared_value	decimal	Não	Valor declarado em R$

Response:

{
    "error": false,
    "data": [
        {
            "postal_company_id": 1,
            "company_name": "Correios",
            "company_code": "correios",
            "name": "SEDEX",
            "code": "04014",
            "price": 71.46,
            "price_discounted": 70.04,
            "deadline": 1
        }
    ]
}

2.5 RF-E01-005: Validação de CEP

Valida e enriquece dados de CEP via API ConectEnvios.

Endpoint: GET /cep/address/?cep={cep}

Response:

{
    "error": false,
    "data": {
        "address": "QR 219",
        "cep": "72345-000",
        "city_id": 5564,
        "city_title": "Brasília",
        "state_abbreviation": "DF",
        "state_id": 7
    }
}

---

3. Requisitos Não-Funcionais

3.1 Performance

Métrica	Requisito	Crítico
Tempo resposta (p95)	< 3 segundos	> 10 segundos
Throughput	100 msg/segundo	< 50 msg/segundo
Disponibilidade	99.5%	< 99%

3.2 Segurança

• Autenticação via Bearer Token para API ConectEnvios
• Validação de assinatura SHA256 para webhooks WhatsApp
• Rate limiting: 60 requests por período
• Dados sensíveis criptografados

3.3 Escalabilidade

• Horizontal scaling via Kubernetes
• Cache Redis para rastreamento e CEP
• Filas RabbitMQ para processamento assíncrono

---

4. Transportadoras Suportadas

ID	Transportadora	Serviços
1	Correios	MINI, PAC, SEDEX
2	Jadlog	PACKAGE, .COM, PICKUP, RODOVIÁRIO
3	AzulCargo	ECOMM, STANDARD
4	Loggi	ECONOMIC, EXPRESS
5	JTExpress	EZ

---

5. 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 API ConectEnvios V1

---

Próximo: Arquitetura Técnica →