xpeditis2.0/docs/carrier-portal/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

```typescript
// 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.