{"openapi":"3.0.3","info":{"title":"Veltra TMS - API Oficial & Webhooks","version":"1.0.0","description":"\nAPI RESTful e Webhooks da plataforma **Veltra TMS**.\n\nPermite que embarcadores, sistemas de ERP, plataformas de e-commerce e ferramentas de BI (PowerBI, Looker, Tableau, Metabase) integrem:\n1. **Cotação de fretes multi-tabela** em tempo real.\n2. **Rastreamento unificado de despachos e ocorrências**.\n3. **Extração de métricas analíticas e faturas de frete para BI**.\n4. **Disparo de Webhooks de eventos logísticos** com assinatura criptográfica HMAC SHA-256.\n\n### Autenticação & Segurança\n- **Ambiente de Testes / Admin**: Usuários autenticados no painel administrativo podem autorizar requisições diretamente.\n- **Produção (M2M / BI)**: Envie o cabeçalho `Authorization: Bearer <API_KEY>`.\n- **Criptografia**: TLS 1.3 obrigatório em trânsito.\n      ","contact":{"name":"Suporte Veltra API & Integrações","email":"contato@veltra.log.br","url":"https://veltra.log.br"}},"servers":[{"url":"https://veltra.log.br","description":"Servidor Principal de Produção"},{"url":"http://localhost:9003","description":"Ambiente Local de Desenvolvimento"}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT / API_KEY","description":"Insira sua Chave de API de Integração ou Token JWT corporativo."}},"schemas":{"CotacaoRequest":{"type":"object","required":["peso","altura","largura","comprimento","cep_origem","cep_destino"],"properties":{"peso":{"type":"number","description":"Peso em quilogramas (kg)","example":10.5},"altura":{"type":"number","description":"Altura do volume em centímetros (cm)","example":20},"largura":{"type":"number","description":"Largura do volume em centímetros (cm)","example":30},"comprimento":{"type":"number","description":"Comprimento do volume em centímetros (cm)","example":40},"cep_origem":{"type":"string","description":"CEP de origem no formato 00000-000","example":"01001-000"},"cep_destino":{"type":"string","description":"CEP de destino no formato 00000-000","example":"20000-000"}}},"CotacaoResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"cotacoes":{"type":"array","items":{"type":"object","properties":{"nome":{"type":"string","example":"Braspress"},"preco":{"type":"number","example":125.5},"prazo":{"type":"integer","example":3}}}},"informacoes":{"type":"object","properties":{"peso":{"type":"number","example":10.5},"peso_cubado":{"type":"string","example":"4.00"},"cep_origem":{"type":"string","example":"01001-000"},"cep_destino":{"type":"string","example":"20000-000"},"distancia_estimada":{"type":"string","example":"420 km"}}}}},"timestamp":{"type":"string","format":"date-time"}}},"RastreioResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"codigo_rastreamento":{"type":"string","example":"BR123456789"},"status":{"type":"string","example":"em_transporte"},"transportadora":{"type":"string","example":"Braspress Transportes"},"previsao_entrega":{"type":"string","format":"date-time"},"historico":{"type":"array","items":{"type":"object","properties":{"data":{"type":"string","format":"date-time"},"evento":{"type":"string","example":"Coleta realizada"},"local":{"type":"string","example":"São Paulo, SP"},"status":{"type":"string","example":"coletado"}}}}}},"timestamp":{"type":"string","format":"date-time"}}},"BiExportPayload":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"total_registros":{"type":"integer","example":1250},"periodo":{"type":"string","example":"2026-04-01 a 2026-04-30"},"metricas":{"type":"object","properties":{"total_gasto_frete":{"type":"number","example":84520.3},"divergencias_identificadas":{"type":"number","example":3420.5},"ctes_auditados":{"type":"integer","example":840},"sla_cumprimento_percentual":{"type":"number","example":98.4}}}}}}},"WebhookRegistrationRequest":{"type":"object","required":["url","eventos"],"properties":{"url":{"type":"string","format":"uri","example":"https://meu-bi.empresa.com.br/api/veltra-webhook"},"eventos":{"type":"array","items":{"type":"string","enum":["rastreio.status_atualizado","rastreio.entregue","rastreio.ocorrencia","auditoria.divergencia_detectada","bi.fechamento_mensal"]},"example":["rastreio.status_atualizado","auditoria.divergencia_detectada"]},"descricao":{"type":"string","example":"Ingestão no Data Lake / PowerBI corporativo"}}}}},"paths":{"/api/docs/cotacao":{"post":{"summary":"Cotação de Frete Multi-tabela","description":"Calcula valor e prazo de entrega em tempo real comparando todas as tabelas homologadas do embarcador.","operationId":"calcularCotacao","tags":["Cotação & Frete"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CotacaoRequest"}}}},"responses":{"200":{"description":"Cotações calculadas com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CotacaoResponse"}}}},"400":{"description":"Dados de requisição inválidos ou campos obrigatórios ausentes"}}}},"/api/docs/rastreio":{"get":{"summary":"Consulta de Rastreamento de Despacho","description":"Consulta o status atual, ocorrências e previsão de entrega por código de rastreamento ou despacho.","operationId":"consultarRastreio","tags":["Rastreamento & Tracking"],"parameters":[{"name":"codigo_rastreamento","in":"query","required":true,"schema":{"type":"string","example":"BR123456789"},"description":"Código do rastreio ou número do pedido"}],"responses":{"200":{"description":"Rastreamento localizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RastreioResponse"}}}},"400":{"description":"Código de rastreamento não informado"}}}},"/api/bi/export":{"get":{"summary":"Exportação Segura de Dados para BI / Data Lake","description":"Endpoint seguro para ingestão periódica em PowerBI, Looker, Tableau ou Snowflake. Requer autorização de Admin.","operationId":"exportarMetricasBI","tags":["Business Intelligence (BI) & Analytics"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"data_inicio","in":"query","required":false,"schema":{"type":"string","format":"date","example":"2026-04-01"},"description":"Data inicial do filtro (YYYY-MM-DD)"},{"name":"data_fim","in":"query","required":false,"schema":{"type":"string","format":"date","example":"2026-04-30"},"description":"Data final do filtro (YYYY-MM-DD)"}],"responses":{"200":{"description":"Métricas agregadas para BI","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BiExportPayload"}}}},"401":{"description":"Não autenticado ou token inválido"},"403":{"description":"Acesso negado (requer perfil de Administrador)"}}}},"/api/bi/webhooks":{"post":{"summary":"Cadastrar Webhook para Alimentação Contínua de BI / SLA","description":"Registra uma URL de destino para receber notificações em tempo real sempre que ocorrerem divergências ou alterações de status.","operationId":"cadastrarWebhookBI","tags":["Business Intelligence (BI) & Analytics","Webhooks"],"security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookRegistrationRequest"}}}},"responses":{"200":{"description":"Webhook registrado com sucesso","content":{"application/json":{"example":{"success":true,"webhook_id":"wh_live_839210","secret":"whsec_7b82f9104c81a...","message":"Webhook cadastrado. Guarde a chave secret para validação da assinatura HMAC."}}}},"401":{"description":"Autenticação obrigatória"}}}}}}