xpeditis2.0/CARRIER_API_RESEARCH.md

Carrier API Research Documentation

Research conducted on: 2025-10-23

Summary

Research findings for 4 new consolidation carriers to determine API availability for booking integration.

Carrier	API Available	Status	Integration Type
SSC Consolidation	❌ No	No public API found	CSV Only
ECU Line (ECU Worldwide)	✅ Yes	Public developer portal	CSV + API
TCC Logistics	❌ No	No public API found	CSV Only
NVO Consolidation	❌ No	No public API found	CSV Only

---

1. SSC Consolidation

Research Findings

Website: https://www.sscconsolidation.com/

API Availability: ❌ NOT AVAILABLE

Search Conducted:

• Searched: "SSC Consolidation API documentation booking"
• Checked official website for developer resources
• No public API developer portal found
• No API documentation available publicly

Notes:

• Company exists but does not provide public API access
• May offer EDI or private integration for large partners (requires direct contact)
• The Scheduling Standards Consortium (SSC) found in search is NOT the same company

Recommendation: CSV_ONLY - Use CSV-based rate system exclusively

Integration Strategy:

• CSV files for rate quotes
• Manual/email booking process
• No real-time API connector needed

---

2. ECU Line (ECU Worldwide)

Research Findings

Website: https://www.ecuworldwide.com/

API Portal: ✅ https://api-portal.ecuworldwide.com/

API Availability: ✅ AVAILABLE - Public developer portal with REST APIs

API Capabilities:

• ✅ Rate quotes (door-to-door and port-to-port)
• ✅ Shipment booking (create/update/cancel)
• ✅ Tracking and visibility
• ✅ Shipping instructions management
• ✅ Historical data access

Authentication: API Keys (obtained after registration)

Environments:

• Sandbox: Test environment (exact replica, no live operations)
• Production: Live API after testing approval

Integration Process:

1. Sign up at api-portal.ecuworldwide.com
2. Activate account via email
3. Subscribe to API products (sandbox first)
4. Receive API keys after configuration approval
5. Test in sandbox environment
6. Request production keys after implementation tests

API Architecture: REST API with JSON responses

Documentation Quality: ✅ Professional developer portal with getting started guide

Recommendation: CSV_AND_API - Create API connector + CSV fallback

Integration Strategy:

• Create infrastructure/carriers/ecu-worldwide/ connector
• Implement rate search and booking APIs
• Use CSV as fallback for routes not covered by API
• Circuit breaker with 5s timeout
• Cache responses (15min TTL)

API Products Available (from portal):

• Quote API
• Booking API
• Tracking API
• Document API

---

3. TCC Logistics

Research Findings

Websites Found:

• https://tcclogistics.com/ (TCC International)
• https://tcclogistics.org/ (TCC Logistics LLC)

API Availability: ❌ NOT AVAILABLE

Search Conducted:

• Searched: "TCC Logistics API freight booking documentation"
• Multiple companies found with "TCC Logistics" name
• No public API documentation or developer portal found
• General company websites without API resources

Companies Identified:

1. TCC Logistics LLC (Houston, Texas) - Trucking and warehousing
2. TCC Logistics Limited - 20+ year company with AEO Customs, freight forwarding
3. TCC International - Part of MSL Group, iCargo network member

Notes:

• No publicly accessible API documentation
• May require direct partnership/contact for integration
• Company focuses on traditional freight forwarding services

Recommendation: CSV_ONLY - Use CSV-based rate system exclusively

Integration Strategy:

• CSV files for rate quotes
• Manual/email booking process
• Contact company directly if API access needed in future

---

4. NVO Consolidation

Research Findings

Website: https://www.nvoconsolidation.com/

API Availability: ❌ NOT AVAILABLE

Search Conducted:

• Searched: "NVO Consolidation freight forwarder API booking system"
• Checked company website and industry platforms
• No public API or developer portal found

Company Profile:

• Founded: 2011
• Location: Barendrecht, Netherlands
• Type: Neutral NVOCC (Non-Vessel Operating Common Carrier)
• Services: LCL import/export, rail freight, distribution across Europe

Third-Party Integrations:

• ✅ Integrated with project44 for tracking and ETA visibility
• ✅ May have access via NVO2NVO platform (industry booking exchange)

Notes:

• No proprietary API available publicly
• Uses third-party platforms (project44) for tracking
• NVO2NVO platform offers booking exchange but not direct API

Recommendation: CSV_ONLY - Use CSV-based rate system exclusively

Integration Strategy:

• CSV files for rate quotes
• Manual booking process
• Future: Consider project44 integration if needed for tracking (separate from booking)

---

Implementation Plan

Carriers with API Integration (1)

1. ECU Worldwide ✅
   • Priority: HIGH
   • Create connector: infrastructure/carriers/ecu-worldwide/
   • Files needed:
     • ecu-worldwide.connector.ts - Implements CarrierConnectorPort
     • ecu-worldwide.mapper.ts - Request/response mapping
     • ecu-worldwide.types.ts - TypeScript interfaces
     • ecu-worldwide.config.ts - API configuration
     • ecu-worldwide.connector.spec.ts - Integration tests
   • Environment variables:
     • ECU_WORLDWIDE_API_URL
     • ECU_WORLDWIDE_API_KEY
     • ECU_WORLDWIDE_ENVIRONMENT (sandbox/production)
   • Fallback: CSV rates if API unavailable

Carriers with CSV Only (3)

1. SSC Consolidation - CSV only
2. TCC Logistics - CSV only
3. NVO Consolidation - CSV only

CSV Files to Create:

• apps/backend/infrastructure/storage/csv-storage/rates/ssc-consolidation.csv
• apps/backend/infrastructure/storage/csv-storage/rates/ecu-worldwide.csv (fallback)
• apps/backend/infrastructure/storage/csv-storage/rates/tcc-logistics.csv
• apps/backend/infrastructure/storage/csv-storage/rates/nvo-consolidation.csv

---

Technical Configuration

Carrier Config in Database

// csv_rate_configs table
[
  {
    companyName: "SSC Consolidation",
    csvFilePath: "rates/ssc-consolidation.csv",
    type: "CSV_ONLY",
    hasApi: false,
    isActive: true
  },
  {
    companyName: "ECU Worldwide",
    csvFilePath: "rates/ecu-worldwide.csv", // Fallback
    type: "CSV_AND_API",
    hasApi: true,
    apiConnector: "ecu-worldwide",
    isActive: true
  },
  {
    companyName: "TCC Logistics",
    csvFilePath: "rates/tcc-logistics.csv",
    type: "CSV_ONLY",
    hasApi: false,
    isActive: true
  },
  {
    companyName: "NVO Consolidation",
    csvFilePath: "rates/nvo-consolidation.csv",
    type: "CSV_ONLY",
    hasApi: false,
    isActive: true
  }
]

---

Rate Search Flow

For ECU Worldwide (API + CSV)

1. Check if route is available via API
2. If API available: Call API connector with circuit breaker (5s timeout)
3. If API fails/timeout: Fall back to CSV rates
4. Cache result in Redis (15min TTL)

For Others (CSV Only)

1. Load rates from CSV file
2. Filter by origin/destination/volume/weight
3. Calculate price based on CBM/weight
4. Cache result in Redis (15min TTL)

---

Future API Opportunities

Potential Future Integrations

1. NVO2NVO Platform - Industry-wide booking exchange

   • May provide standardized API for multiple NVOCCs
   • Worth investigating for multi-carrier integration

2. Direct Partnerships

   • SSC Consolidation, TCC Logistics, NVO Consolidation
   • Contact companies directly for private API access
   • May require volume commitments or partnership agreements

3. Aggregator APIs

   • Flexport API (multi-carrier aggregator)
   • FreightHub API
   • ConsolHub API (mentioned in search results)

---

Recommendations

Immediate Actions

1. ✅ Implement ECU Worldwide API connector (high priority)
2. ✅ Create CSV system for all 4 carriers
3. ✅ Add CSV fallback for ECU Worldwide
4. ⏭️ Register for ECU Worldwide sandbox environment
5. ⏭️ Test ECU API in sandbox before production

Long-term Strategy

1. Monitor API availability from SSC, TCC, NVO
2. Consider aggregator APIs for broader coverage
3. Maintain CSV system as reliable fallback
4. Build hybrid approach (API primary, CSV fallback)

---

Contact Information for Future API Requests

Carrier	Contact Method	Notes
SSC Consolidation	https://www.sscconsolidation.com/contact	Request private API access
ECU Worldwide	api-portal.ecuworldwide.com	Public registration available
TCC Logistics	https://tcclogistics.com/contact	Multiple entities, clarify which one
NVO Consolidation	https://www.nvoconsolidation.com/contact	Ask about API roadmap

---

Conclusion

API Integration: 1 out of 4 carriers (25%)

• ✅ ECU Worldwide: Full REST API available

CSV Integration: 4 out of 4 carriers (100%)

• All carriers will have CSV-based rates
• ECU Worldwide: CSV as fallback

Recommended Architecture:

• Hybrid system: API connectors where available, CSV fallback for all
• Unified rate search service that queries both sources
• Cache all results in Redis (15min TTL)
• Display source (CSV vs API) in frontend results

Next Steps: Proceed with implementation following the hybrid model.