{
  "openapi": "3.1.0",
  "info": {
    "title": "Qasqad — API",
    "version": "2.0",
    "description": "Synchronisation de flotte, vérification de clé et webhooks de Qasqad. Écrit à la main d'après webapp-fps-backend, branche feature/v2-backend (5d2b3e53), le 05/11/2026 ; à terme, généré par le back.",
    "contact": {
      "email": "support@qasqad.com"
    }
  },
  "servers": [
    {
      "url": "https://api.qasqad.com"
    }
  ],
  "security": [
    {
      "apiKey": [],
      "timestamp": [],
      "signature": []
    }
  ],
  "paths": {
    "/api/auth/verify": {
      "post": {
        "operationId": "verify-key",
        "summary": "Vérifier la clé et la signature",
        "description": "Ne fait rien d'autre que contrôler l'authentification : c'est le premier appel à réussir. Envoyez {} comme corps, et signez ce {}.",
        "responses": {
          "201": {
            "description": "Clé, horodatage et signature valides. Corps : {\"status\":\"valid\"}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "const": "valid"
                    }
                  }
                },
                "example": {
                  "status": "valid"
                }
              }
            }
          },
          "401": {
            "description": "Authentification refusée ; error.message dit pourquoi quand il est fourni.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "tags": [
          "Authentification"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "description": "Un objet vide, {}, signé comme tout corps."
              },
              "example": {}
            }
          }
        }
      }
    },
    "/api/fleet": {
      "post": {
        "operationId": "sync-fleet",
        "summary": "Synchroniser les affectations de la flotte",
        "description": "Crée ou met à jour chaque affectation envoyée, identifiée par le triplet plaque + e-mail du conducteur + date de début. Rien n'est supprimé : une affectation absente de l'envoi reste en place. L'ancienne adresse POST /api/fleet/sync-fleet reste servie et fait la même chose.",
        "parameters": [
          {
            "name": "dryRun",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "true : la requête est authentifiée et validée, les lignes sont écrites dans une table de test. Votre flotte et vos FPS ne sont pas touchés."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SyncFleetRequest"
              },
              "example": {
                "vehicleAssignments": [
                  {
                    "licencePlate": "AB-123-CD",
                    "startDate": "2025-02-17T00:00:00+01:00",
                    "driverEmail": "conducteur@entreprise.fr",
                    "driverName": "Martin",
                    "driverFirstName": "Julie",
                    "driverCivility": "MME",
                    "driverBirthDate": "1988-04-12",
                    "driverBirthPlace": "RENNES",
                    "driverStreetNumber": "12bis",
                    "driverStreet": "rue des Lilas",
                    "driverPostalCode": "75015",
                    "driverCity": "PARIS",
                    "driverCountry": "FRA",
                    "licenceNumber": "120375201234",
                    "licenceCountry": "FRA"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Lot accepté. Le corps de la réponse est vide."
          },
          "400": {
            "description": "Le corps ne respecte pas le schéma. Seule la première erreur est renvoyée, et rien n'est enregistré.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentification refusée : en-tête manquant, horodatage hors fenêtre, clé invalide ou expirée, adresse IP non autorisée, signature fausse.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "499": {
            "description": "Un companySiret ne correspond à aucune société de votre organisation. Rien n'est enregistré.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "tags": [
          "Flotte"
        ]
      }
    },
    "/api/fleet/vehicles": {
      "post": {
        "operationId": "sync-fleet-vehicles",
        "summary": "Déclarer les entrées et sorties de flotte",
        "description": "Crée ou met à jour chaque véhicule envoyé, identifié par la plaque et son pays. Rien n'est supprimé : un véhicule absent de l'envoi garde ce qui était enregistré. Ces dates servent à déclarer votre flotte à l'ANTAI (contraventions) et à compter les véhicules de l'abonnement. Elles sont indépendantes des affectations : la fin d'une affectation n'est pas une sortie de flotte, et un véhicule peut être en flotte sans conducteur.",
        "parameters": [
          {
            "name": "dryRun",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "true : la requête est authentifiée et validée, rien n'est enregistré."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SyncFleetVehiclesRequest"
              },
              "example": {
                "vehicles": [
                  {
                    "licencePlate": "AB-123-CD",
                    "companySiret": "12345678900012",
                    "fleetEntryDate": "2026-12-01"
                  },
                  {
                    "licencePlate": "EF-456-GH",
                    "companySiret": "12345678900012",
                    "fleetEntryDate": "2025-03-15",
                    "fleetExitDate": "2027-01-31"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Lot accepté. Le corps de la réponse est vide."
          },
          "400": {
            "description": "Le corps ne respecte pas le schéma, une sortie précède l'entrée, ou la sortie déjà enregistrée précède la nouvelle entrée (renvoyez alors fleetExitDate, null si le véhicule revient). Rien n'est enregistré.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentification refusée : en-tête manquant, horodatage hors fenêtre, clé invalide ou expirée, adresse IP non autorisée, signature fausse.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "499": {
            "description": "Un companySiret ne correspond à aucune société de votre organisation. Rien n'est enregistré.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "tags": [
          "Flotte"
        ]
      }
    }
  },
  "webhooks": {
    "batch.processed": {
      "post": {
        "summary": "Lot traité",
        "description": "Tous les FPS du lot sont traités sans erreur : conducteurs identifiés, justificatifs produits.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BatchEvent"
              },
              "example": {
                "eventType": "batch.processed",
                "data": {
                  "uuid": "9f1c2e4a-6b0d-4c55-9a1e-2f7d3c8b5e10",
                  "status": "processed",
                  "type": "identify",
                  "isFromAntaiApi": true,
                  "organisationId": 42,
                  "createdAt": "2026-11-03T07:12:09.000Z",
                  "processedAt": "2026-11-03T07:14:52.000Z",
                  "parkingTickets": [
                    {
                      "uuid": "c03b7d18-2a4f-4e8b-b1c6-7d9e0f1a2b3c",
                      "paymentNotice": "12345678901234567890",
                      "paymentKey": "AB12",
                      "licencePlate": "AB-123-CD",
                      "offenceDate": "2026-10-28T14:05:00.000Z",
                      "amount": 35,
                      "minoredAmount": null,
                      "collectivityName": "Ville de Lyon",
                      "address": {
                        "line1": "12 rue de la République",
                        "postCodeCity": "69002 Lyon",
                        "latLong": "45.7640,4.8357"
                      },
                      "parkingTicketSentAt": "2026-10-30",
                      "manualInputReason": null,
                      "paymentNoticePath": "https://…/justificatif.pdf?X-Amz-Expires=518400",
                      "createdAt": "2026-11-03T07:12:09.000Z"
                    }
                  ]
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Répondez 200, et seulement 200, sous 15 secondes."
          }
        },
        "tags": [
          "Webhooks"
        ],
        "operationId": "batch-processed"
      }
    },
    "batch.requires_input": {
      "post": {
        "summary": "Lot en erreur",
        "description": "Au moins un FPS du lot demande une intervention (conducteur introuvable, données illisibles…) ; manualInputReason dit lequel et pourquoi.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BatchEvent"
              },
              "example": {
                "eventType": "batch.requires_input",
                "data": {
                  "uuid": "9f1c2e4a-6b0d-4c55-9a1e-2f7d3c8b5e10",
                  "status": "has_error",
                  "type": "identify",
                  "isFromAntaiApi": true,
                  "organisationId": 42,
                  "createdAt": "2026-11-03T07:12:09.000Z",
                  "processedAt": null,
                  "parkingTickets": [
                    {
                      "uuid": "c03b7d18-2a4f-4e8b-b1c6-7d9e0f1a2b3c",
                      "paymentNotice": "12345678901234567890",
                      "paymentKey": "AB12",
                      "licencePlate": "AB-123-CD",
                      "offenceDate": "2026-10-28T14:05:00.000Z",
                      "amount": 35,
                      "minoredAmount": null,
                      "collectivityName": "Ville de Lyon",
                      "address": {
                        "line1": "12 rue de la République",
                        "postCodeCity": "69002 Lyon",
                        "latLong": "45.7640,4.8357"
                      },
                      "parkingTicketSentAt": "2026-10-30",
                      "manualInputReason": "driver_not_found",
                      "paymentNoticePath": null,
                      "createdAt": "2026-11-03T07:12:09.000Z"
                    }
                  ]
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Répondez 200, et seulement 200, sous 15 secondes."
          }
        },
        "tags": [
          "Webhooks"
        ],
        "operationId": "batch-requires-input"
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key"
      },
      "timestamp": {
        "type": "apiKey",
        "in": "header",
        "name": "x-timestamp"
      },
      "signature": {
        "type": "apiKey",
        "in": "header",
        "name": "x-signature"
      }
    },
    "schemas": {
      "SyncFleetRequest": {
        "type": "object",
        "required": [
          "vehicleAssignments"
        ],
        "additionalProperties": false,
        "properties": {
          "vehicleAssignments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/VehicleAssignment"
            },
            "description": "Les affectations à créer ou mettre à jour."
          }
        }
      },
      "VehicleAssignment": {
        "type": "object",
        "required": [
          "licencePlate",
          "startDate",
          "driverEmail"
        ],
        "additionalProperties": false,
        "properties": {
          "licencePlate": {
            "type": "string",
            "pattern": "^[A-Z]{2}-\\d{3}-[A-Z]{2}$",
            "examples": [
              "AB-123-CD"
            ],
            "description": "Plaque au format SIV, en majuscules, avec les tirets."
          },
          "startDate": {
            "type": "string",
            "format": "date-time",
            "examples": [
              "2025-02-17T00:00:00+01:00"
            ],
            "description": "Début de l'affectation, ISO 8601."
          },
          "endDate": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "examples": [
              "2025-03-17T00:00:00+01:00"
            ],
            "description": "Fin de l'affectation, ISO 8601. Absente : la fin déjà enregistrée ne change pas. null : l'affectation est rouverte."
          },
          "driverEmail": {
            "type": "string",
            "format": "email",
            "examples": [
              "conducteur@entreprise.fr"
            ],
            "description": "E-mail du conducteur. C'est à lui que l'avis est adressé."
          },
          "additionalEmail1": {
            "type": "string",
            "format": "email",
            "description": "Destinataire en copie, par exemple le manager. Chaîne vide acceptée."
          },
          "additionalEmail2": {
            "type": "string",
            "format": "email",
            "description": "Second destinataire en copie. Chaîne vide acceptée."
          },
          "driverName": {
            "type": "string",
            "description": "Nom de famille du conducteur, ou raison sociale si SOCIETE. Pour désigner aux contraventions : obligatoire, 40 caractères au plus, séparé du prénom."
          },
          "driverFirstName": {
            "type": "string",
            "description": "Prénom du conducteur. Pour désigner une personne aux contraventions : obligatoire, 40 caractères au plus. Vide pour une société."
          },
          "driverReference": {
            "type": "string",
            "description": "Votre identifiant interne (matricule)."
          },
          "companySiret": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^\\d{14}$",
            "description": "SIRET de la société de votre groupe qui détient le véhicule. Absent : la société déjà enregistrée ne change pas. Vide ou null : l'organisation elle-même."
          },
          "extraField1": {
            "type": "string",
            "description": "Champ libre, repris dans vos exports. De même extraField2 à extraField7."
          },
          "extraField2": {
            "type": "string"
          },
          "extraField3": {
            "type": "string"
          },
          "extraField4": {
            "type": "string"
          },
          "extraField5": {
            "type": "string"
          },
          "extraField6": {
            "type": "string"
          },
          "extraField7": {
            "type": "string"
          },
          "driverCivility": {
            "type": "string",
            "enum": [
              "M.",
              "MME",
              "SOCIETE",
              ""
            ],
            "description": "Contraventions : civilité du conducteur. M. ou MME pour une personne ; SOCIETE quand le véhicule est confié à une entreprise, désignée à la place d'une personne."
          },
          "driverSiret": {
            "type": "string",
            "pattern": "^\\d{14}$",
            "description": "Contraventions : SIRET du conducteur société. Avec driverCivility SOCIETE seulement : refusé sur une personne."
          },
          "driverBirthDate": {
            "type": "string",
            "format": "date",
            "examples": [
              "1988-04-12"
            ],
            "description": "Contraventions : date de naissance, AAAA-MM-JJ. Le conducteur a entre 14 et 120 ans."
          },
          "driverBirthPlace": {
            "type": "string",
            "maxLength": 40,
            "description": "Contraventions : lieu de naissance."
          },
          "driverStreetNumber": {
            "type": "string",
            "maxLength": 10,
            "description": "Contraventions : numéro de voie (12bis accepté)."
          },
          "driverStreet": {
            "type": "string",
            "maxLength": 80,
            "description": "Contraventions : voie, sans le numéro."
          },
          "driverAddressComplement": {
            "type": "string",
            "maxLength": 255,
            "description": "Contraventions : bâtiment, étage, boîte postale."
          },
          "driverPostalCode": {
            "type": "string",
            "maxLength": 15,
            "description": "Contraventions : code postal ; exactement 5 chiffres en France."
          },
          "driverCity": {
            "type": "string",
            "maxLength": 40,
            "description": "Contraventions : ville."
          },
          "driverCountry": {
            "type": "string",
            "pattern": "^[A-Z]{3}$",
            "examples": [
              "FRA"
            ],
            "description": "Contraventions : pays de l'adresse, ISO 3166-1 alpha-3."
          },
          "licenceNumber": {
            "type": "string",
            "maxLength": 20,
            "description": "Contraventions : numéro du permis de conduire."
          },
          "licenceCountry": {
            "type": "string",
            "pattern": "^[A-Z]{3}$",
            "examples": [
              "FRA"
            ],
            "description": "Contraventions : pays du permis, ISO 3166-1 alpha-3."
          },
          "licenceIssueDate": {
            "type": "string",
            "format": "date",
            "description": "Contraventions, facultatif : date de délivrance du permis, AAAA-MM-JJ, au moins 14 ans après la naissance."
          },
          "licenceIssuePlace": {
            "type": "string",
            "maxLength": 40,
            "description": "Contraventions, facultatif : lieu de délivrance du permis."
          }
        },
        "description": "Une affectation. Les champs d'identité (driverCivility à licenceIssuePlace) remplissent la fiche du conducteur, utilisée pour le désigner à l'ANTAI ; ils sont facultatifs. Une ligne sans aucun d'eux ne modifie pas la fiche. Dans la fiche, un champ absent garde sa valeur et une chaîne vide l'efface. Une personne (M. ou MME) se désigne avec : civilité, nom, prénom, date et lieu de naissance, voie, code postal, ville, pays, numéro et pays du permis. Une société (SOCIETE) avec : raison sociale (driverName), driverSiret et l'adresse ; un prénom, une naissance ou un permis sont alors refusés, et ce que la fiche en gardait est effacé."
      },
      "BatchEvent": {
        "type": "object",
        "properties": {
          "eventType": {
            "type": "string",
            "description": "batch.processed ou batch.requires_input ; repris dans l'en-tête X-Webhook-Event."
          },
          "data": {
            "$ref": "#/components/schemas/Batch"
          }
        },
        "required": [
          "eventType",
          "data"
        ]
      },
      "Batch": {
        "type": "object",
        "properties": {
          "uuid": {
            "type": "string",
            "description": "Identifiant du lot."
          },
          "status": {
            "type": "string",
            "description": "processed, has_error…"
          },
          "type": {
            "type": "string",
            "description": "identify, pay_to_state ou identify_and_pay_to_state."
          },
          "isFromAntaiApi": {
            "type": "boolean",
            "description": "true si les avis sont arrivés directement de l'ANTAI."
          },
          "organisationId": {
            "type": "integer"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "processedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "parkingTickets": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ParkingTicket"
            },
            "description": "Les FPS du lot."
          }
        }
      },
      "ParkingTicket": {
        "type": "object",
        "properties": {
          "uuid": {
            "type": "string",
            "description": "Identifiant du FPS."
          },
          "paymentNotice": {
            "type": [
              "string",
              "null"
            ],
            "description": "Numéro de l'avis."
          },
          "paymentKey": {
            "type": [
              "string",
              "null"
            ],
            "description": "Clé de paiement de l'avis."
          },
          "licencePlate": {
            "type": [
              "string",
              "null"
            ]
          },
          "offenceDate": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Date et heure de l'infraction."
          },
          "amount": {
            "type": [
              "number",
              "null"
            ],
            "description": "Montant de l'avis, en euros."
          },
          "minoredAmount": {
            "type": [
              "number",
              "null"
            ],
            "description": "Montant minoré, en euros, quand il existe."
          },
          "collectivityName": {
            "type": [
              "string",
              "null"
            ],
            "description": "Collectivité émettrice."
          },
          "address": {
            "type": [
              "object",
              "null"
            ],
            "description": "Lieu de l'infraction : line1, postCodeCity, latLong."
          },
          "parkingTicketSentAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Date d'envoi de l'avis."
          },
          "manualInputReason": {
            "type": [
              "string",
              "null"
            ],
            "description": "Pourquoi le FPS attend une intervention : driver_not_found, several_drivers_found, invalid_data, duplicate_payment_notice, too_old, payment_error… null s'il est traité."
          },
          "paymentNoticePath": {
            "type": [
              "string",
              "null"
            ],
            "description": "Lien de téléchargement du justificatif de traitement, valable 6 jours. Malgré son nom, ce n'est pas l'avis."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "errorCode": {
            "type": [
              "integer",
              "string"
            ],
            "description": "Code de l'erreur ; identique à error.code."
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "path": {
            "type": "string",
            "description": "Chemin appelé."
          },
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": [
                  "integer",
                  "string"
                ]
              },
              "message": {
                "type": "string",
                "description": "Détail lisible, quand il est fourni."
              }
            }
          }
        }
      },
      "FleetVehicle": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "licencePlate",
          "companySiret",
          "fleetEntryDate"
        ],
        "properties": {
          "licencePlate": {
            "type": "string",
            "examples": [
              "AB-123-CD"
            ],
            "description": "Plaque. Au format SIV (majuscules, tirets) si le pays est FRA ; sinon lettres, chiffres, espaces et tirets, 20 caractères au plus."
          },
          "plateCountry": {
            "type": "string",
            "pattern": "^[A-Z]{3}$",
            "default": "FRA",
            "description": "Pays d'immatriculation, ISO 3166-1 alpha-3. À renseigner seulement pour une plaque étrangère."
          },
          "companySiret": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^\\d{14}$",
            "description": "SIRET de la société de votre groupe qui détient le véhicule. Vide ou null : l'organisation elle-même."
          },
          "fleetEntryDate": {
            "type": "string",
            "format": "date",
            "examples": [
              "2026-12-01"
            ],
            "description": "Entrée dans la flotte, AAAA-MM-JJ."
          },
          "fleetExitDate": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "examples": [
              "2027-01-31"
            ],
            "description": "Sortie de la flotte, AAAA-MM-JJ, jour inclus. Absente : la sortie enregistrée ne change pas. null : le véhicule revient dans la flotte."
          }
        }
      },
      "SyncFleetVehiclesRequest": {
        "type": "object",
        "required": [
          "vehicles"
        ],
        "additionalProperties": false,
        "properties": {
          "vehicles": {
            "type": "array",
            "minItems": 1,
            "maxItems": 5000,
            "items": {
              "$ref": "#/components/schemas/FleetVehicle"
            },
            "description": "Les véhicules entrés ou sortis."
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Authentification",
      "description": "Vérifier une clé et sa signature."
    },
    {
      "name": "Flotte",
      "description": "Affectations véhicule → conducteur."
    },
    {
      "name": "Webhooks",
      "description": "Événements que Qasqad envoie à votre SI."
    }
  ]
}
