{
  "openapi": "3.1.0",
  "info": {
    "title": "Driveos API",
    "version": "1.0.0",
    "description": "Server-to-server API tvrtke: vožnje, vozači, vozila, cjenik, statistika i webhookovi. Ključ pripada jednoj tvrtki; `tenantId` se nikad ne šalje u zahtjevu. Svaki zahtjev je ograničen na 120 u minuti po ključu.",
    "contact": {
      "name": "Driveos",
      "url": "https://driveos.eu"
    }
  },
  "servers": [
    {
      "url": "https://driveos.eu/api",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    },
    {
      "apiKeyAuth": []
    }
  ],
  "tags": [
    {
      "name": "Company",
      "description": "Identitet tvrtke i katalog usluga"
    },
    {
      "name": "Rides",
      "description": "Vožnje, detalj, naručivanje i otkazivanje"
    },
    {
      "name": "Fleet",
      "description": "Vozači i vozila"
    },
    {
      "name": "Pricing",
      "description": "Procjena cijene"
    },
    {
      "name": "Stats",
      "description": "Dnevni sažetak"
    },
    {
      "name": "Webhooks",
      "description": "Zdravlje webhookova"
    }
  ],
  "paths": {
    "/v1": {
      "get": {
        "tags": [
          "Company"
        ],
        "summary": "API index and capability discovery",
        "security": [],
        "responses": {
          "200": {
            "description": "API metadata and endpoint list"
          }
        }
      }
    },
    "/v1/openapi.json": {
      "get": {
        "tags": [
          "Company"
        ],
        "summary": "This OpenAPI document",
        "security": [],
        "responses": {
          "200": {
            "description": "OpenAPI 3.1 document"
          }
        }
      }
    },
    "/v1/whoami": {
      "get": {
        "tags": [
          "Company"
        ],
        "summary": "Validate the key: company and scopes",
        "responses": {
          "200": {
            "description": "Tenant, key and API limits"
          },
          "400": {
            "description": "API add-on disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or expired key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Scope or IP not allowed"
          }
        }
      }
    },
    "/v1/company": {
      "get": {
        "tags": [
          "Company"
        ],
        "summary": "Company profile and branding",
        "responses": {
          "200": {
            "description": "Company profile"
          }
        }
      }
    },
    "/v1/service-types": {
      "get": {
        "tags": [
          "Company"
        ],
        "summary": "Active service types, payment methods and optional price list",
        "description": "Cjenik se vraća samo kad ključ ima opseg `pricing`.",
        "responses": {
          "200": {
            "description": "Service types"
          }
        }
      }
    },
    "/v1/vehicles": {
      "get": {
        "tags": [
          "Fleet"
        ],
        "summary": "Vehicles of the company",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "pageSize",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "active",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Vehicles with page metadata"
          }
        }
      }
    },
    "/v1/drivers": {
      "get": {
        "tags": [
          "Fleet"
        ],
        "summary": "Drivers of the company",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "pageSize",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "active",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Drivers with page metadata"
          }
        }
      }
    },
    "/v1/rides": {
      "get": {
        "tags": [
          "Rides"
        ],
        "summary": "List rides with filters and pagination",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "pageSize",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Comma separated statuses"
          },
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "updatedSince",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Incremental sync"
          },
          {
            "name": "serviceTypeId",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "driverId",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "externalId",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 80
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Rides with page metadata",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "rides": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/RideSummary"
                      }
                    },
                    "page": {
                      "$ref": "#/components/schemas/Page"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Rides"
        ],
        "summary": "Create a ride (idempotent with externalId)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateRide"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Ride created or replayed"
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Scope `book` missing"
          }
        }
      }
    },
    "/v1/rides/{number}": {
      "get": {
        "tags": [
          "Rides"
        ],
        "summary": "Ride detail with stops and status timeline",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Ride detail"
          },
          "404": {
            "description": "Ride not found in this company",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/rides/{number}/cancel": {
      "post": {
        "tags": [
          "Rides"
        ],
        "summary": "Cancel a ride",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "reason": {
                    "type": "string",
                    "maxLength": 200
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Ride cancelled"
          },
          "409": {
            "description": "Ride already finished"
          }
        }
      }
    },
    "/v1/quote": {
      "post": {
        "tags": [
          "Pricing"
        ],
        "summary": "Price estimate before booking",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QuoteRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Quote with breakdown"
          }
        }
      }
    },
    "/v1/stats/daily": {
      "get": {
        "tags": [
          "Stats"
        ],
        "summary": "Daily rides and revenue (max 92 days)",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "YYYY-MM-DD in company time zone"
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "YYYY-MM-DD in company time zone"
          }
        ],
        "responses": {
          "200": {
            "description": "Daily series and totals"
          }
        }
      }
    },
    "/v1/webhooks": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Webhook endpoints, delivery counts and last delivery",
        "responses": {
          "200": {
            "description": "Webhook health"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key as Bearer token"
      },
      "apiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "statusCode",
          "message"
        ],
        "properties": {
          "statusCode": {
            "type": "integer",
            "example": 400
          },
          "message": {
            "type": "string",
            "example": "Ovaj modul nije uključen za tvrtku."
          },
          "key": {
            "type": "string",
            "example": "errors.moduleDisabled",
            "description": "Stabilan strojni kod greške."
          },
          "locale": {
            "type": "string",
            "example": "hr"
          }
        }
      },
      "Page": {
        "type": "object",
        "properties": {
          "page": {
            "type": "integer"
          },
          "pageSize": {
            "type": "integer"
          },
          "total": {
            "type": "integer"
          },
          "pages": {
            "type": "integer"
          },
          "hasMore": {
            "type": "boolean"
          }
        }
      },
      "RideSummary": {
        "type": "object",
        "properties": {
          "number": {
            "type": "string",
            "example": "R-2026-000123"
          },
          "status": {
            "type": "string",
            "enum": [
              "REQUESTED",
              "OFFERED",
              "ASSIGNED",
              "ACCEPTED",
              "ARRIVING",
              "ARRIVED",
              "IN_PROGRESS",
              "COMPLETED",
              "CANCELLED",
              "NO_SHOW",
              "FAILED"
            ]
          },
          "channel": {
            "type": "string",
            "example": "API"
          },
          "requestedAt": {
            "type": "string",
            "format": "date-time"
          },
          "scheduledAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "completedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "cancelledAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "pickupAddress": {
            "type": "string"
          },
          "dropoffAddress": {
            "type": [
              "string",
              "null"
            ]
          },
          "estimatedPrice": {
            "type": [
              "number",
              "null"
            ]
          },
          "finalPrice": {
            "type": [
              "number",
              "null"
            ]
          },
          "currencyCode": {
            "type": "string",
            "example": "EUR"
          },
          "externalId": {
            "type": [
              "string",
              "null"
            ]
          },
          "serviceType": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "name": {
                "type": "string"
              }
            }
          },
          "driver": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "name": {
                "type": "string"
              }
            }
          }
        }
      },
      "CreateRide": {
        "type": "object",
        "required": [
          "serviceTypeId",
          "pickupAddress",
          "pickupLatitude",
          "pickupLongitude"
        ],
        "properties": {
          "externalId": {
            "type": "string",
            "description": "Idempotency key unique per company",
            "example": "erp-2026-0001"
          },
          "serviceTypeId": {
            "type": "string",
            "format": "uuid"
          },
          "vehicleClassId": {
            "type": "string",
            "format": "uuid"
          },
          "paymentMethod": {
            "type": "string",
            "enum": [
              "CASH",
              "CARD",
              "TERMINAL",
              "WALLET",
              "CORPORATE_ACCOUNT",
              "INVOICE"
            ]
          },
          "passengerName": {
            "type": "string",
            "maxLength": 160
          },
          "passengerPhone": {
            "type": "string",
            "maxLength": 40
          },
          "pickupAddress": {
            "type": "string",
            "maxLength": 300
          },
          "pickupLatitude": {
            "type": "number",
            "minimum": -90,
            "maximum": 90
          },
          "pickupLongitude": {
            "type": "number",
            "minimum": -180,
            "maximum": 180
          },
          "dropoffAddress": {
            "type": "string",
            "maxLength": 300
          },
          "dropoffLatitude": {
            "type": "number",
            "minimum": -90,
            "maximum": 90
          },
          "dropoffLongitude": {
            "type": "number",
            "minimum": -180,
            "maximum": 180
          },
          "distanceKm": {
            "type": "number",
            "description": "Optional; computed from coordinates when omitted"
          },
          "durationMinutes": {
            "type": "integer",
            "description": "Optional; computed from coordinates when omitted"
          },
          "averageSpeedKmh": {
            "type": "number"
          },
          "scheduledAt": {
            "type": "string",
            "format": "date-time"
          },
          "notes": {
            "type": "string",
            "maxLength": 1000
          },
          "couponCode": {
            "type": "string",
            "maxLength": 40
          },
          "corporateAccountId": {
            "type": "string",
            "format": "uuid"
          },
          "costCenterId": {
            "type": "string",
            "format": "uuid"
          },
          "stops": {
            "type": "array",
            "maxItems": 16,
            "items": {
              "type": "object",
              "required": [
                "address",
                "latitude",
                "longitude"
              ],
              "properties": {
                "address": {
                  "type": "string"
                },
                "latitude": {
                  "type": "number"
                },
                "longitude": {
                  "type": "number"
                }
              }
            }
          }
        }
      },
      "QuoteRequest": {
        "type": "object",
        "required": [
          "serviceTypeId"
        ],
        "properties": {
          "serviceTypeId": {
            "type": "string",
            "format": "uuid"
          },
          "fromZoneId": {
            "type": "string",
            "format": "uuid"
          },
          "toZoneId": {
            "type": "string",
            "format": "uuid"
          },
          "pickupLatitude": {
            "type": "number"
          },
          "pickupLongitude": {
            "type": "number"
          },
          "dropoffLatitude": {
            "type": "number"
          },
          "dropoffLongitude": {
            "type": "number"
          },
          "distanceKm": {
            "type": "number"
          },
          "durationMinutes": {
            "type": "integer"
          },
          "averageSpeedKmh": {
            "type": "number"
          },
          "at": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    }
  }
}
