E01 - Plataforma de Inteligência Artificial
Contratos de API
Versão: 2.0 | Data: 05/01/2026 | API Base: ConectEnvios API V1
1. Visão Geral da Integração
┌────────────────────────────────────────────────────────────────────────────────┐
│ MAPA DE INTEGRAÇÃO - E01 │
├────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────┐ │
│ │ WhatsApp │ │
│ │ Business API │ │
│ │ (Meta) │ │
│ └──────────┬──────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────┐ ┌─────────────────────┐ │
│ │ OpenAI │◀────▶│ PLATAFORMA E01 │ │
│ │ GPT-4 │ │ (Backend Node.js) │ │
│ │ (Function Calling) │ └──────────┬──────────┘ │
│ └─────────────────────┘ │ │
│ ▼ │
│ ┌─────────────────────┐ │
│ │ ConectEnvios API │ │
│ │ V1 │ │
│ │ (Multi-Carrier) │ │
│ └──────────┬──────────┘ │
│ │ │
│ ┌────────────────────┼────────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Correios │ │ Jadlog │ │ Loggi │ │
│ │ Azul │ │ │ │ JTExpress│ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ │
└────────────────────────────────────────────────────────────────────────────────┘
2. ConectEnvios API V1
2.1 Configuração Base
Base URL (Produção): https://app.conectenvios.com.br/api/v1/
Base URL (Staging): https://staging.conectenvios.com.br/api/v1/
Autenticação: Bearer Token
Content-Type: application/json (GET) | multipart/form-data (POST)
Rate Limit: 60 requests/período
2.2 Endpoints Utilizados
| Endpoint | Método | Descrição | Documentação |
|---|---|---|---|
/cep/address/?cep={cep} | GET | Validar CEP | Ver detalhes |
/package/shipping | POST | Cotação multi-carrier | Ver detalhes |
/package/track/:id | GET | Rastreamento | Ver detalhes |
/city | GET | Listar cidades | Ver detalhes |
/postal_company | GET | Listar transportadoras | Ver detalhes |
/user/balance | GET | Saldo da conta | Ver detalhes |
3. Cotação de Frete
3.1 Request
POST /package/shipping
Content-Type: multipart/form-data
Authorization: Bearer {token}
type=box
weight=2000
height=10
width=20
length=30
addr_from_cep=70000000
addr_to_cep=01310100
declared_value=150.00
3.2 Response
{
"error": false,
"data": [
{
"postal_company_id": 2,
"company_name": "Jadlog",
"company_code": "jadlog",
"name": "PICKUP",
"code": "11",
"price": 13.26,
"price_discounted": 13.26,
"price_formatted": "R$ 13,26",
"price_discounted_formatted": "R$ 13,26",
"deadline": 5,
"deadline_api": true,
"extra": 0,
"club": null
},
{
"postal_company_id": 1,
"company_name": "Correios",
"company_code": "correios",
"name": "PAC",
"code": "04510",
"price": 32.43,
"price_discounted": 31.79,
"deadline": 5
},
{
"postal_company_id": 1,
"company_name": "Correios",
"company_code": "correios",
"name": "SEDEX",
"code": "04014",
"price": 71.46,
"price_discounted": 70.04,
"deadline": 1
}
]
}
3.3 Implementação TypeScript
interface ShippingQuoteParams {
origin_cep: string;
destination_cep: string;
weight: number; // gramas
width?: number; // cm
height?: number; // cm
length?: number; // cm
type: 'box' | 'letter';
declared_value?: number;
}
async function getShippingQuote(params: ShippingQuoteParams): Promise<ShippingOption[]> {
const formData = new FormData();
formData.append('type', params.type);
formData.append('weight', params.weight.toString());
formData.append('addr_from_cep', params.origin_cep.replace(/\D/g, ''));
formData.append('addr_to_cep', params.destination_cep.replace(/\D/g, ''));
if (params.type === 'box') {
formData.append('height', (params.height || 2).toString());
formData.append('width', (params.width || 11).toString());
formData.append('length', (params.length || 16).toString());
}
if (params.declared_value) {
formData.append('declared_value', params.declared_value.toString());
}
const response = await conectEnviosAPI.post('/package/shipping', formData);
if (response.error) {
throw new Error(response.message?.join(', ') || 'Erro na cotação');
}
return response.data;
}
4. Rastreamento
4.1 Request
GET /package/track/12345
Accept: application/json
Authorization: Bearer {token}
4.2 Response
{
"error": false,
"data": [
{
"city_id": 5270,
"city": "São Paulo",
"state_id": 26,
"state": "SP",
"correios_date": "2026-01-05T14:30:00.000000Z",
"correios_type": "RO",
"correios_status": null,
"description": "Objeto em trânsito - por favor aguarde",
"error_message": null
},
{
"city_id": 5564,
"city": "Brasília",
"state_id": 7,
"state": "DF",
"correios_date": "2026-01-04T10:00:00.000000Z",
"correios_type": "PO",
"correios_status": null,
"description": "Objeto postado",
"error_message": null
}
]
}
4.3 Implementação TypeScript
interface TrackingEvent {
city_id: number | null;
city: string;
state_id: number | null;
state: string;
correios_date: string;
correios_type: string | null;
correios_status: string | null;
description: string;
error_message: string | null;
}
async function trackPackage(packageId: number): Promise<TrackingEvent[]> {
// Verificar cache primeiro
const cacheKey = `tracking:${packageId}`;
const cached = await redis.get(cacheKey);
if (cached) {
return JSON.parse(cached);
}
const response = await conectEnviosAPI.get(`/package/track/${packageId}`);
if (response.error || !response.data) {
throw new Error('Envio não encontrado');
}
// Salvar no cache (5 min para em trânsito)
await redis.setex(cacheKey, 300, JSON.stringify(response.data));
return response.data;
}
5. Validação de CEP
5.1 Request
GET /cep/address/?cep=70000000
Accept: application/json
Authorization: Bearer {token}
5.2 Response
{
"error": false,
"message": [],
"data": {
"address": "SQN 302",
"cep": "70000-000",
"city_id": 5564,
"city_title": "Brasília",
"complement": null,
"neighborhood": "Asa Norte",
"state_abbreviation": "DF",
"state_id": 7,
"state_title": "Distrito Federal"
}
}
6. GPT-4 Function Calling
6.1 Tool Definitions
{
"tools": [
{
"type": "function",
"function": {
"name": "get_shipping_quote",
"description": "Calcula cotação de frete entre dois CEPs. Retorna opções de múltiplas transportadoras com preços e prazos.",
"parameters": {
"type": "object",
"properties": {
"origin_cep": {
"type": "string",
"description": "CEP de origem (8 dígitos)",
"pattern": "^\\d{8}$"
},
"destination_cep": {
"type": "string",
"description": "CEP de destino (8 dígitos)",
"pattern": "^\\d{8}$"
},
"weight": {
"type": "integer",
"description": "Peso em gramas"
},
"type": {
"type": "string",
"enum": ["box", "letter"],
"description": "Tipo de embalagem"
}
},
"required": ["origin_cep", "destination_cep", "weight", "type"]
}
}
},
{
"type": "function",
"function": {
"name": "track_package",
"description": "Rastreia um envio pelo ID do pacote no sistema ConectEnvios.",
"parameters": {
"type": "object",
"properties": {
"package_id": {
"type": "integer",
"description": "ID do pacote no sistema"
}
},
"required": ["package_id"]
}
}
}
]
}
7. 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 |