Integração de APIs Logísticas em Sistemas TMS e ERP: Guia de Arquitetura, Idempotência e Resiliência em Alta Escala

{
  "type": "https://api.geodagio.com/errors/invalid-route-payload",
  "title": "Invalid Request Parameters",
  "status": 400,
  "code": "INVALID_COORDINATES",
  "detail": "O ponto de origem informado [lat: -95.0, lng: -46.6] possui latitude fora do intervalo geodésico válido [-90.0, 90.0].",
  "instance": "/api/v1/routes/calculate",
  "requestId": "req_01j7b9k6g7e1x8m4n2p9q0r1st",
  "invalidParams": [
    {
      "name": "origin.lat",
      "reason": "Value must be greater than or equal to -90.0",
      "received": -95.0
    }
  ]
}

curl -X POST "https://api.geodagio.com/api/v1/routes/calculate" \
  -H "Authorization: Bearer gdg_live_8f7b2c1e9a0d3f4b5c6e7a8b9c0d1e2f" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: c9b8a7d6-e5f4-4a3b-8c2d-1e0f9a8b7c6d" \
  -H "X-Client-System: SAP-S4HANA-v2023" \
  -d '{
    "origin": { "lat": -23.55052, "lng": -46.633308 },
    "destination": { "lat": -22.906847, "lng": -43.172896 },
    "vehicle": {
      "category": "TRUCK_5AXIS",
      "axles": 5,
      "suspendedAxles": 0
    },
    "options": {
      "avoidUnpaved": true,
      "calculateTolls": true,
      "includeAnttMinFreight": true
    }
  }'

import axios, { AxiosError } from 'axios';
import { randomUUID } from 'crypto';

interface RouteRequest {
  origin: { lat: number; lng: number };
  destination: { lat: number; lng: number };
  vehicle: { category: string; axles: number };
}

interface GeodagioRouteResponse {
  routeId: string;
  distanceKm: number;
  durationMinutes: number;
  tolls: {
    total: number;
    plazasCount: number;
    coverageStatus: string;
  };
}

const GEODAGIO_API_URL = 'https://api.geodagio.com/api/v1';
const API_KEY = process.env.GEODAGIO_API_KEY!;

export async function calculateRouteWithResilience(
  payload: RouteRequest,
  maxRetries = 3
): Promise {
  const idempotencyKey = randomUUID(); // Chave única para a transação

  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await axios.post<GeodagioRouteResponse>(
        `${GEODAGIO_API_URL}/routes/calculate`,
        payload,
        {
          headers: {
            'Authorization': `Bearer ${API_KEY}`,
            'Content-Type': 'application/json',
            'Idempotency-Key': idempotencyKey,
            'User-Agent': 'TMS-Enterprise-Client/2.4'
          },
          timeout: 8000 // 8 segundos de timeout estrito
        }
      );
      return response.data;
    } catch (err) {
      const error = err as AxiosError;
      const status = error.response?.status;

      // Não repetir em caso de erros de validação do cliente (4xx)
      if (status && status >= 400 && status < 500 && status !== 429) {
        throw new Error(`Erro de validação (${status}): ${JSON.stringify(error.response?.data)}`);
      }

      // Se for a última tentativa, falhar
      if (attempt === maxRetries) {
        throw new Error(`Falha definitiva após ${maxRetries} tentativas: ${error.message}`);
      }

      // Backoff exponencial com jitter (aleatoriedade para evitar efeito manada)
      const baseDelay = Math.pow(2, attempt) * 500;
      const jitter = Math.random() * 200;
      const delayMs = baseDelay + jitter;

      console.warn(`Tentativa ${attempt} falhou. Aguardando ${Math.round(delayMs)}ms antes do retry...`);
      await new Promise((resolve) => setTimeout(resolve, delayMs));
    }
  }

  throw new Error('Falha inesperada no fluxo de retentativas.');
}

import hmac
import hashlib
import json
from flask import Flask, request, jsonify, abort

app = Flask(__name__)
WEBHOOK_SECRET = "whsec_9d8c7b6a5e4f3d2c1b0a9f8e7d6c5b4a"

def verify_geodagio_signature(raw_body: bytes, received_signature: str, secret: str) -> bool:
    """Valida o HMAC SHA-256 em tempo constante contra ataques de timing."""
    if not received_signature:
        return False
    
    expected_signature = hmac.new(
        key=secret.encode('utf-8'),
        msg=raw_body,
        digestmod=hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(f"sha256={expected_signature}", received_signature)

@app.route('/api/webhooks/geodagio', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-Geodagio-Signature')
    raw_payload = request.get_data()

    if not verify_geodagio_signature(raw_payload, signature, WEBHOOK_SECRET):
        abort(401, description="Assinatura HMAC de webhook inválida.")

    event_data = json.loads(raw_payload)
    event_type = event_data.get('event')

    if event_type == 'batch.routes.completed':
        batch_id = event_data['data']['batchId']
        download_url = event_data['data']['downloadUrl']
        print(f"Lote {batch_id} concluído com sucesso. Processando download: {download_url}")
        # Dispara job de conciliação fiscal no ERP

    return jsonify({"status": "received"}), 200

if __name__ == '__main__':
    app.run(port=8080)