xpeditis2.0/docs/features/rate-search.md

Recherche de tarifs

---

Deux types de recherche

Type	Description	Endpoint
FCL (Full Container Load)	Tarifs via connecteurs carriers (Maersk, MSC, etc.)	POST /api/v1/rates/search
CSV / LCL	Tarifs chargés depuis des fichiers CSV	POST /api/v1/rates/csv-search

---

Recherche FCL — Carriers API

Endpoint

POST /api/v1/rates/search
Authorization: Bearer <token>

{
  "origin": "NLRTM",
  "destination": "CNSHA",
  "containerType": "40HC",
  "mode": "FCL",
  "departureDate": "2026-06-01",
  "hazmat": false
}

Réponse

{
  "results": [
    {
      "id": "uuid",
      "carrier": { "name": "Maersk", "code": "MAERSK", "logoUrl": "..." },
      "origin": { "code": "NLRTM", "name": "Rotterdam" },
      "destination": { "code": "CNSHA", "name": "Shanghai" },
      "baseFreight": 1850.00,
      "surcharges": [
        { "type": "BAF", "amount": 250.00, "currency": "USD" }
      ],
      "totalAmount": 2100.00,
      "currency": "USD",
      "transitDays": 28,
      "etd": "2026-06-01T00:00:00Z",
      "eta": "2026-06-29T00:00:00Z",
      "availability": 50,
      "validUntil": "2026-05-13T10:15:00Z"
    }
  ],
  "total": 5,
  "page": 1,
  "pageSize": 20
}

Cache Redis

• Clé : rate:{origin}:{destination}:{containerType}
• TTL : 15 minutes
• Les cotations expirent automatiquement après 15min (valid_until)

Carriers intégrés

Carrier	Code	SCAC
Maersk	MAERSK	MAEU
MSC	MSC	MSCU
CMA CGM	CMACGM	CMDU
Hapag-Lloyd	HAPAG	HLCU
ONE	ONE	ONEY

Chaque carrier a son connecteur dans apps/backend/src/infrastructure/carriers/. Circuit breaker via opossum : timeout 5s, bascule sur fallback si indisponible.

---

Recherche CSV

Endpoint

POST /api/v1/rates/csv-search
Authorization: Bearer <token>

{
  "origin": "NLRTM",
  "destination": "USNYC",
  "volumeCBM": 25.5,
  "weightKG": 3500,
  "palletCount": 10,
  "filters": {
    "companies": ["SSC Consolidation"],
    "minPrice": 1000,
    "maxPrice": 3000,
    "currency": "USD"
  }
}

Carriers CSV disponibles

Company	Type	API
SSC Consolidation	CSV_ONLY	Non
ECU Worldwide	CSV_AND_API	Oui
TCC Logistics	CSV_ONLY	Non
NVO Consolidation	CSV_ONLY	Non

Les fichiers CSV sont dans apps/backend/src/infrastructure/storage/csv-storage/rates/.

Calcul de prix CSV

// Freight class : prendre le max de volume-based ou weight-based
const volumePrice = volumeCBM * pricePerCBM;
const weightPrice = weightKG * pricePerKG;
const freightPrice = Math.max(volumePrice, weightPrice);
const totalPrice = freightPrice + surchargeBAF + surchargeCAF;

---

Recherche de ports

Autocomplete avec recherche floue (pg_trgm) :

GET /api/v1/ports/search?q=rotterdam&limit=10

~10 000 ports UN/LOCODE seedés en base.

---

Export des résultats

Les résultats peuvent être exportés en PDF ou Excel depuis le frontend. Voir apps/frontend/src/utils/ pour les utilitaires d'export.