{
  "openapi": "3.1.0",
  "info": {
    "title": "IST Digital Freight Forwarder Suite API",
    "version": "1.0.0",
    "description": "Application-level APIs and webhooks for the IST digital freight-forwarder suite. This contract covers normalized search, booking, tracking, tenant provisioning, and IST TMS synchronization."
  },
  "servers": [
    {
      "url": "https://www.istinfosystech.com"
    }
  ],
  "paths": {
    "/api/digital-forwarder/rates/search": {
      "post": {
        "summary": "Search normalized sell rates",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RateSearchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Normalized sell-rate basket",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "rates": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/RateOption"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/digital-forwarder/schedules/search": {
      "post": {
        "summary": "Search schedules",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RateSearchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Normalized schedule options",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "schedules": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ScheduleOption"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/digital-forwarder/bookings": {
      "post": {
        "summary": "Create a booking request",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BookingRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Booking record created and synchronized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BookingRecord"
                }
              }
            }
          }
        }
      }
    },
    "/api/digital-forwarder/sync/ist-tms/quote": {
      "post": {
        "summary": "Synchronize a digital quote into IST TMS",
        "responses": {
          "200": {
            "description": "Quote synchronization result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SyncEvent"
                }
              }
            }
          }
        }
      }
    },
    "/api/digital-forwarder/sync/ist-tms/shipment": {
      "post": {
        "summary": "Synchronize booking and shipment state into IST TMS",
        "responses": {
          "200": {
            "description": "Shipment synchronization result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SyncEvent"
                }
              }
            }
          }
        }
      }
    },
    "/api/digital-forwarder/shipments/{shipmentId}/tracking": {
      "get": {
        "summary": "Retrieve normalized shipment milestones",
        "parameters": [
          {
            "name": "shipmentId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Tracking timeline",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "shipmentId": {
                      "type": "string"
                    },
                    "milestones": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/TrackingMilestone"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/digital-forwarder/portal/tenants": {
      "post": {
        "summary": "Provision a white-label portal tenant",
        "responses": {
          "200": {
            "description": "Tenant provisioned",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PortalTenant"
                }
              }
            }
          }
        }
      }
    },
    "/api/digital-forwarder/webhooks/provider-events": {
      "post": {
        "summary": "Receive provider events and normalize them",
        "responses": {
          "200": {
            "description": "Webhook accepted"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "RateSearchRequest": {
        "type": "object",
        "required": ["mode", "origin", "destination", "incoterm", "pieces", "weightKg", "readyDate"],
        "properties": {
          "mode": {
            "type": "string",
            "enum": ["ocean", "air", "land"]
          },
          "origin": {
            "type": "string"
          },
          "destination": {
            "type": "string"
          },
          "incoterm": {
            "type": "string"
          },
          "pieces": {
            "type": "integer"
          },
          "weightKg": {
            "type": "number"
          },
          "readyDate": {
            "type": "string",
            "format": "date"
          }
        }
      },
      "RateOption": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "provider": { "type": "string" },
          "carrier": { "type": "string" },
          "mode": { "type": "string" },
          "serviceLevel": { "type": "string" },
          "departureDate": { "type": "string", "format": "date" },
          "arrivalDate": { "type": "string", "format": "date" },
          "transitDays": { "type": "integer" },
          "equipmentOrService": { "type": "string" },
          "buyingRateUsd": { "type": "number" },
          "sellRateUsd": { "type": "number" },
          "marginUsd": { "type": "number" }
        }
      },
      "ScheduleOption": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "provider": { "type": "string" },
          "carrier": { "type": "string" },
          "service": { "type": "string" },
          "voyageOrFlight": { "type": "string" },
          "etd": { "type": "string", "format": "date" },
          "eta": { "type": "string", "format": "date" },
          "transitDays": { "type": "integer" }
        }
      },
      "BookingRequest": {
        "type": "object",
        "required": ["rateId", "customerName", "customerReference", "commodity"],
        "properties": {
          "rateId": { "type": "string" },
          "customerName": { "type": "string" },
          "customerReference": { "type": "string" },
          "commodity": { "type": "string" }
        }
      },
      "BookingRecord": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "provider": { "type": "string" },
          "carrier": { "type": "string" },
          "status": { "type": "string" },
          "confirmationNumber": { "type": "string" },
          "tmsQuoteId": { "type": "string" },
          "tmsJobNumber": { "type": "string" },
          "sellRateUsd": { "type": "number" },
          "marginUsd": { "type": "number" }
        }
      },
      "TrackingMilestone": {
        "type": "object",
        "properties": {
          "label": { "type": "string" },
          "timestamp": { "type": "string", "format": "date-time" },
          "location": { "type": "string" },
          "status": { "type": "string" },
          "source": { "type": "string" },
          "detail": { "type": "string" }
        }
      },
      "PortalTenant": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "domain": { "type": "string" },
          "launchState": { "type": "string" },
          "brandColor": { "type": "string" }
        }
      },
      "SyncEvent": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "system": { "type": "string" },
          "direction": { "type": "string" },
          "object": { "type": "string" },
          "status": { "type": "string" },
          "detail": { "type": "string" },
          "timestamp": { "type": "string", "format": "date-time" }
        }
      }
    }
  }
}