{
  "openapi": "3.1.0",
  "info": {
    "title": "EuroCollis Public API",
    "version": "2.1.0",
    "description": "Read-only logistics data for supported Europe ↔ Africa shipping routes. Bookings are completed on https://www.eurocollis.com.",
    "contact": {
      "email": "support@eurocollis.com",
      "url": "https://www.eurocollis.com/developers"
    }
  },
  "servers": [
    {
      "url": "https://api.eurocollis.com/v1"
    }
  ],
  "components": {
    "securitySchemes": {
      "EuroCollisKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-EuroCollis-Key"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "field": {
                "type": "string"
              }
            }
          }
        }
      },
      "QuoteRequest": {
        "type": "object",
        "required": [
          "origin",
          "destination"
        ],
        "properties": {
          "origin": {
            "type": "object",
            "required": [
              "country",
              "city"
            ],
            "properties": {
              "country": {
                "type": "string"
              },
              "city": {
                "type": "string"
              }
            }
          },
          "destination": {
            "type": "object",
            "required": [
              "country",
              "city"
            ],
            "properties": {
              "country": {
                "type": "string"
              },
              "city": {
                "type": "string"
              }
            }
          },
          "weight_kg": {
            "type": "number"
          },
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "item_id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "quantity": {
                  "type": "number"
                }
              }
            }
          },
          "pickup_date": {
            "type": "string",
            "format": "date"
          },
          "flex_days": {
            "type": "integer"
          }
        }
      },
      "QuoteResponse": {
        "type": "object",
        "properties": {
          "quote_id": {
            "type": "string",
            "nullable": true
          },
          "corridor": {
            "type": "string"
          },
          "offers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Offer"
            }
          },
          "cheapest": {
            "$ref": "#/components/schemas/Offer"
          },
          "valid_until": {
            "type": "string",
            "format": "date-time"
          },
          "booking_url": {
            "type": "string"
          }
        }
      },
      "Offer": {
        "type": "object",
        "properties": {
          "trip_id": {
            "type": "string"
          },
          "courier": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "alias": {
                "type": "string"
              },
              "rating": {
                "type": "number",
                "nullable": true
              }
            }
          },
          "price": {
            "type": "object",
            "description": "Public pricing contract: final total price for the shipment and its currency. EuroCollis does not publish fees, deposits or payment splits over this API.",
            "properties": {
              "currency": {
                "type": "string"
              },
              "total": {
                "type": "number"
              }
            },
            "additionalProperties": false
          },
          "pickup_window": {
            "type": "object",
            "properties": {
              "from": {
                "type": "string",
                "format": "date"
              },
              "to": {
                "type": "string",
                "format": "date"
              }
            }
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Platform",
      "description": "Service metadata, health and the machine-readable contract."
    },
    {
      "name": "Reference",
      "description": "Corridors, countries, cities, item catalogue and prohibited goods."
    },
    {
      "name": "Pricing",
      "description": "Authoritative quotes. The public contract is the final total and its currency."
    },
    {
      "name": "Couriers",
      "description": "Verified couriers and their published storefronts."
    },
    {
      "name": "Shipments",
      "description": "Public tracking and indicative customs estimates."
    }
  ],
  "security": [
    {
      "EuroCollisKey": []
    }
  ],
  "paths": {
    "/v1/health": {
      "get": {
        "tags": [
          "Platform"
        ],
        "summary": "Health probe",
        "security": [],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/openapi.json": {
      "get": {
        "tags": [
          "Platform"
        ],
        "summary": "This specification",
        "security": [],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/info": {
      "get": {
        "tags": [
          "Platform"
        ],
        "summary": "Platform overview, corridors, currency, booking model",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/countries": {
      "get": {
        "tags": [
          "Reference"
        ],
        "summary": "Supported marketplace countries returned by live corridor data",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/routes": {
      "get": {
        "tags": [
          "Reference"
        ],
        "summary": "All supported corridors",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/cities": {
      "get": {
        "tags": [
          "Reference"
        ],
        "summary": "Supported pickup/delivery cities for one country",
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ISO-3166 alpha-2"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "400": {
            "description": "Invalid country"
          }
        }
      }
    },
    "/v1/services": {
      "get": {
        "tags": [
          "Reference"
        ],
        "summary": "Shippable item catalogue with pricing units",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/prohibited-items": {
      "get": {
        "tags": [
          "Reference"
        ],
        "summary": "Prohibited items",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/quote": {
      "post": {
        "tags": [
          "Pricing"
        ],
        "summary": "Authoritative quote (same pricing engine as the website)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QuoteRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Quote",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QuoteResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Corridor not supported",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/couriers": {
      "get": {
        "tags": [
          "Couriers"
        ],
        "summary": "Live verified couriers with upcoming trips (demo/expired excluded)",
        "parameters": [
          {
            "name": "origin_country",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "destination_country",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from_date",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/couriers/{slug}": {
      "get": {
        "tags": [
          "Couriers"
        ],
        "summary": "Public courier profile (slug or id). No PII.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "404": {
            "description": "Not found"
          }
        }
      }
    },
    "/v1/storefronts": {
      "get": {
        "tags": [
          "Couriers"
        ],
        "summary": "Published courier storefronts",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/storefronts/{slug}": {
      "get": {
        "tags": [
          "Couriers"
        ],
        "summary": "One storefront with canonical URL and corridor pages",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "404": {
            "description": "Not found"
          }
        }
      }
    },
    "/v1/customs/estimate": {
      "post": {
        "tags": [
          "Shipments"
        ],
        "summary": "Indicative duty + VAT estimate (non-authoritative, disclaimer required)",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/track/{reference}": {
      "get": {
        "tags": [
          "Shipments"
        ],
        "summary": "Public tracking. Requires ?delivery_city= as a second factor.",
        "parameters": [
          {
            "name": "reference",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "delivery_city",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "400": {
            "description": "Missing delivery_city"
          },
          "404": {
            "description": "Not found"
          }
        }
      }
    }
  }
}