API Reference

Integrate YACHT Logistics into your ERP, TMS, or custom application.

Overview

The YACHT Logistics API gives you programmatic access to freight quotes, bookings, and live tracking. Perfect for integrating into your ERP, TMS, or custom application.

All API responses are JSON. All timestamps are in ISO 8601 format (UTC).

Authentication

YACHT supports two authentication methods:

1. API Key (recommended for server-to-server)

Copycurl https://yacht-logistics.de/api/quote \
  -H "X-Api-Key: yk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"origin": "Shanghai, CN", "destination": "Hamburg, DE", "cargo_type": "FCL"}'

Generate API keys in your developer dashboard.

2. JWT Bearer Token (for user sessions)

Copycurl https://yacht-logistics.de/api/quote \
  -H "Authorization: Bearer your_jwt_token" \
  -H "Content-Type: application/json"

Get Freight Quote

POST/api/quote

Returns 3 carrier options with prices, transit times, and market comparison.

Request Parameters

Parameter	Type	Required	Description
origin	string	required	Origin city/port (e.g. "Shanghai, CN")
destination	string	required	Destination (e.g. "Hamburg, DE")
cargo_type	string	required	FCL, LCL, or AIR
container_size	string	optional	20ft, 40ft, 40ftHC (FCL only)
weight_kg	number	optional	Cargo weight in kg
volume_cbm	number	optional	Volume in CBM (LCL/AIR)
ready_date	string	optional	ISO date: "2026-03-15"
commodity	string	optional	Cargo description

Example Request

Copy{
  "origin": "Shanghai, CN",
  "destination": "Hamburg, DE",
  "cargo_type": "FCL",
  "container_size": "20ft",
  "weight_kg": 18000,
  "ready_date": "2026-03-15"
}

Example Response

Copy{
  "quote_id": "QT-20260315-AB12CD",
  "valid_until": "2026-03-22T23:59:59Z",
  "options": [
    {
      "id": "opt_1",
      "carrier": "COSCO Shipping",
      "service": "Economy FCL",
      "price_eur": 2650,
      "savings_vs_market_pct": 18,
      "market_avg_eur": 2800,
      "transit_days": 30,
      "etd": "2026-03-17",
      "eta": "2026-04-16",
      "co2_estimate": { "co2_tons": 8.4, "distance_km": 21000 }
    }
  ],
  "market_intelligence": {
    "disruptions": [
      { "title": "Red Sea Security Advisories", "severity": "high" }
    ]
  }
}

Create Booking

POST/api/booking

Request Parameters

Parameter	Type		Description
quote_id	string	required	Quote ID from /api/quote
option_id	string	required	Selected option (opt_1, opt_2, opt_3)
customer.name	string	required	Contact person name
customer.email	string	required	Contact email
customer.company	string	optional	Company name

Example Response

Copy{
  "booking_id": "BK-20260315-XY789Z",
  "booking_reference": "YAC-2026-042",
  "tracking_number": "CSLU1234567890",
  "status": "confirmed",
  "carrier": "COSCO Shipping",
  "etd": "2026-03-17",
  "eta": "2026-04-16"
}

Get Tracking Status

GET/api/tracking/:booking_id

Copycurl https://yacht-logistics.de/api/tracking/BK-20260315-XY789Z \
  -H "X-Api-Key: yk_live_..."

Example Response

Copy{
  "booking_id": "BK-20260315-XY789Z",
  "status": "in_transit",
  "carrier": "COSCO Shipping",
  "etd": "2026-03-17",
  "eta": "2026-04-16",
  "events": [
    {
      "timestamp": "2026-03-17T08:30:00Z",
      "location": "Shanghai, CN",
      "status": "departed",
      "description": "Container departed Shanghai port"
    }
  ]
}

Webhooks

Subscribe to real-time events. YACHT signs all webhook payloads with HMAC-SHA256.

Supported Events

Event	Description
booking.created	New booking confirmed
booking.status_changed	Carrier updated booking status
tracking.updated	New tracking event
incident.reported	Customer reported an incident

Signature Verification

Copyconst crypto = require('crypto');

function verifyWebhook(secret, body, signature) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Error Codes

Code	Meaning
400	Bad Request — missing required fields
401	Unauthorized — invalid or missing API key / token
403	Forbidden — insufficient permissions
429	Rate Limited — slow down requests
500	Server Error — contact support

Rate Limits

API Keys

Manage your API keys in the developer dashboard. Keys are prefixed with yk_live_ (production) or yk_test_ (sandbox).

Team Management

Business and Enterprise plans support multiple team members. Manage team access via the team dashboard. Each member can have a booker or admin role.

Reports

Enterprise customers can download monthly PDF reports via:

CopyGET /api/reports/monthly?month=2026-03
Authorization: Bearer your_jwt_token

Returns a signed URL to download the PDF report, valid for 1 hour.