{
 "openapi": "3.0.3",
 "info": {
  "title": "TachoArchive API",
  "version": "1.0.0",
  "description": "Upload and list tachograph files (.ddd) of driver cards and vehicle units."
 },
 "servers": [
  {
   "url": "https://app.tacho.lnf.polbyte.app/api/v1"
  }
 ],
 "security": [
  {
   "bearer": []
  }
 ],
 "components": {
  "securitySchemes": {
   "bearer": {
    "type": "http",
    "scheme": "bearer",
    "description": "API key from Settings & API (ta_\u2026)"
   }
  },
  "schemas": {
   "File": {
    "type": "object",
    "properties": {
     "id": {
      "type": "integer"
     },
     "kind": {
      "type": "string",
      "enum": [
       "driver_card",
       "vehicle_unit",
       "unknown"
      ]
     },
     "generation": {
      "type": "string",
      "nullable": true,
      "enum": [
       "1",
       "2",
       "2.2",
       null
      ]
     },
     "original_name": {
      "type": "string"
     },
     "size": {
      "type": "integer"
     },
     "sha256": {
      "type": "string"
     },
     "downloaded_at": {
      "type": "string",
      "format": "date-time",
      "nullable": true
     },
     "period_start": {
      "type": "string",
      "format": "date",
      "nullable": true
     },
     "period_end": {
      "type": "string",
      "format": "date",
      "nullable": true
     },
     "driver": {
      "type": "object",
      "nullable": true,
      "properties": {
       "id": {
        "type": "integer"
       },
       "card_number": {
        "type": "string"
       },
       "surname": {
        "type": "string",
        "nullable": true
       },
       "first_names": {
        "type": "string",
        "nullable": true
       }
      }
     },
     "vehicle": {
      "type": "object",
      "nullable": true,
      "properties": {
       "id": {
        "type": "integer"
       },
       "vin": {
        "type": "string"
       },
       "vrn": {
        "type": "string",
        "nullable": true
       }
      }
     },
     "source": {
      "type": "string",
      "enum": [
       "panel",
       "api"
      ]
     },
     "uploaded_at": {
      "type": "string",
      "format": "date-time"
     }
    }
   },
   "UploadResult": {
    "allOf": [
     {
      "$ref": "#/components/schemas/File"
     },
     {
      "type": "object",
      "properties": {
       "duplicate": {
        "type": "boolean"
       }
      }
     }
    ]
   },
   "Driver": {
    "type": "object",
    "properties": {
     "id": {
      "type": "integer"
     },
     "card_number": {
      "type": "string"
     },
     "card_nation": {
      "type": "string",
      "nullable": true
     },
     "surname": {
      "type": "string",
      "nullable": true
     },
     "first_names": {
      "type": "string",
      "nullable": true
     },
     "card_expiry": {
      "type": "string",
      "format": "date",
      "nullable": true
     },
     "next_download_due": {
      "type": "string",
      "format": "date-time",
      "nullable": true
     },
     "status": {
      "type": "string",
      "enum": [
       "ok",
       "soon",
       "overdue",
       "never"
      ]
     },
     "last_download_at": {
      "type": "string",
      "format": "date-time",
      "nullable": true
     }
    }
   },
   "Vehicle": {
    "type": "object",
    "properties": {
     "id": {
      "type": "integer"
     },
     "vin": {
      "type": "string"
     },
     "vrn": {
      "type": "string",
      "nullable": true
     },
     "vrn_nation": {
      "type": "string",
      "nullable": true
     },
     "next_download_due": {
      "type": "string",
      "format": "date-time",
      "nullable": true
     },
     "status": {
      "type": "string",
      "enum": [
       "ok",
       "soon",
       "overdue",
       "never"
      ]
     },
     "last_download_at": {
      "type": "string",
      "format": "date-time",
      "nullable": true
     }
    }
   },
   "Error": {
    "type": "object",
    "properties": {
     "error": {
      "type": "string"
     },
     "message": {
      "type": "string"
     }
    }
   }
  }
 },
 "paths": {
  "/ping": {
   "get": {
    "summary": "Test the API key",
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/files": {
   "post": {
    "summary": "Upload one or more files",
    "parameters": [
     {
      "name": "X-Filename",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "File name when sending the raw body"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "multipart/form-data": {
       "schema": {
        "type": "object",
        "properties": {
         "file": {
          "type": "string",
          "format": "binary"
         },
         "files[]": {
          "type": "array",
          "maxItems": 50,
          "items": {
           "type": "string",
           "format": "binary"
          }
         }
        }
       }
      },
      "application/octet-stream": {
       "schema": {
        "type": "string",
        "format": "binary"
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Stored",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/UploadResult"
        }
       }
      }
     },
     "200": {
      "description": "Already in the archive (duplicate: true)",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/UploadResult"
        }
       }
      }
     },
     "207": {
      "description": "Several files, some rejected",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "files": {
           "type": "array",
           "items": {
            "type": "object"
           }
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "422": {
      "description": "Rejected",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Too many requests",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   },
   "get": {
    "summary": "List files",
    "parameters": [
     {
      "name": "kind",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "enum": [
        "driver_card",
        "vehicle_unit",
        "unknown"
       ]
      }
     },
     {
      "name": "driver",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "vehicle",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "from",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "format": "date"
      }
     },
     {
      "name": "to",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "format": "date"
      }
     },
     {
      "name": "q",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "page",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "per_page",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer",
       "maximum": 200
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/File"
           }
          },
          "meta": {
           "type": "object",
           "properties": {
            "page": {
             "type": "integer"
            },
            "per_page": {
             "type": "integer"
            },
            "total": {
             "type": "integer"
            },
            "last_page": {
             "type": "integer"
            }
           }
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/files/{id}": {
   "get": {
    "summary": "One file",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/File"
        }
       }
      }
     },
     "404": {
      "description": "Not found",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/files/{id}/download": {
   "get": {
    "summary": "Download the original file",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "File",
      "content": {
       "application/octet-stream": {
        "schema": {
         "type": "string",
         "format": "binary"
        }
       }
      }
     },
     "404": {
      "description": "Not found",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/drivers": {
   "get": {
    "summary": "Driver cards with download deadlines",
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/Driver"
           }
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/vehicles": {
   "get": {
    "summary": "Vehicles with download deadlines",
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/Vehicle"
           }
          }
         }
        }
       }
      }
     }
    }
   }
  }
 }
}