Véhicules et référentiels

Résoudre les référentiels (marque, modèle, type, catégorie, énergie, usage, genre, ville), créer et retrouver les véhicules qui alimentent vehicleIds.

Deux temps

Référentiels : récupérer (ou créer pour marque et modèle) les identifiants attendus.
Véhicule : créer le véhicule avec ces identifiants, ou le retrouver s'il existe déjà. Son id alimente vehicleIds de la proposition.

La création de contrat ne crée plus de véhicule en ligne : chaque véhicule doit exister en base.

Référentiels

Tous les référentiels sont paginés (page, size) et ne renvoient que les entrées actives.

Endpoint	Identifiant à utiliser	Champs notables
`GET /provider/vehicles/brands`	`brandId`	`brandCode` (ex. `SUBARU`), `brandLabel`, `countryOfOrigin` ; filtre `filter[brandLabel]`
`GET /provider/vehicles/models`	`modelId`	`modelCode`, `modelLabel`, `brandId`, `startYear`, `endYear` ; filtres `filter[brand.id]`, `filter[modelLabel]`
`GET /provider/vehicles/types`	`vehicleTypeId`	`typeCode` (ex. `TV03`), `typeLabel`, `maxSeats`
`GET /provider/vehicles/categories`	`vehicleCategoryId`	`categoryCode` (ex. `01`), `categoryLabel`, `numberOfWheels`
`GET /provider/vehicles/energies`	`energyId`	`energyCode` (`SEDI`, `SEEL`, `SEES`, `SEHY`), `energyLabel`
`GET /provider/vehicles/usages`	`usageId`	`usageCode` (ex. `UV05`), `usageLabel`, `description`
`GET /provider/vehicles/genders`	`genderId`	`genderCode` (ex. `GV04` voiture 4 roues), `genderLabel`
`GET /provider/vehicles/circulation-cities`	`circulationCityId`	`cityCode` (ex. `ABJ`), `cityLabel`, `region`, `zone` (zone tarifaire : `zoneCode`, `zoneLabel`, `coefficient`)

Enrichir marques et modèles

Si une marque ou un modèle manque au catalogue, créez-le avant le véhicule :

curl -s -X POST $API/provider/vehicles/brands \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "brandCode": "TVS", "brandLabel": "TVS Motor" }'

curl -s -X POST $API/provider/vehicles/models \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "modelCode": "STAR", "modelLabel": "Star City", "brandId": "uuid-marque" }'

Réponse 201 avec l'objet créé. Un code déjà pris renvoie REF_VEHICLE_BRAND_ALREADY_EXISTS ou REF_VEHICLE_MODEL_ALREADY_EXISTS : réutilisez l'entrée existante.

Créer un véhicule — `POST /provider/vehicles`

curl -s -X POST $API/provider/vehicles \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "registrationNumber": "2546ZR64",
    "chassisNumber": "3XDWSNVZS3AHSX6JS",
    "brandId": "uuid-marque",
    "modelId": "uuid-modele",
    "vehicleTypeId": "uuid-type",
    "vehicleCategoryId": "uuid-categorie",
    "energyId": "uuid-energie",
    "usageId": "uuid-usage",
    "genderId": "uuid-genre",
    "circulationCityId": "uuid-ville",
    "numberOfSeats": 5,
    "horsepower": 10,
    "engineDisplacementCc": 2000,
    "firstRegistrationDate": "2019-03-20",
    "manufactureYear": 2018,
    "marketValue": 22620000
  }'

Champ	Type	Obligatoire	Description
`registrationNumber`	string	non	Immatriculation
`chassisNumber`	string	non	N° de châssis / VIN, 10 à 17 caractères alphanumériques sans I, O ni Q
`brandId`	string	oui	Marque
`modelId`	string	non	Modèle référencé ; sinon `modelText` en texte libre
`modelText`	string	non	Modèle en texte libre
`vehicleTypeId`	string	oui	Type eAtCI
`vehicleCategoryId`	string	oui	Catégorie
`energyId`	string	oui	Énergie
`usageId`	string	oui	Usage
`genderId`	string	oui	Genre
`circulationCityId`	string	oui	Ville de circulation (détermine la zone tarifaire)
`zoneId`	string	non	Zone tarifaire forcée
`numberOfSeats`	int	oui	Nombre de places, > 0 : pilote la tarification TPV
`horsepower`, `engineDisplacementCc`	int	non	Puissance fiscale, cylindrée
`emptyWeightTons`, `payloadTons`, `grossVehicleWeightTons`	number	non	Poids (t)
`firstRegistrationDate`	date	non	1ʳᵉ mise en circulation
`manufactureYear`	int	non	Année de fabrication
`newValue`, `marketValue`	number	non	Valeur à neuf, valeur vénale
`hasGps`, `hasTrailer`, `hasRoadTractor`	boolean	non	Équipements

Réponse 200 : ActionResponse<Vehicle>. L'identifiant du véhicule est data.id. Le véhicule est rattaché à la compagnie et au courtier du compte appelant.

Retrouver un véhicule

Endpoint	Usage
`GET /provider/vehicles?filter[registrationNumber]=2546ZR64`	Liste paginée, recherche « contient »
`GET /provider/vehicles/registration-number/{registrationNumber}`	Par immatriculation exacte
`GET /provider/vehicles/chassis-number/{chassisNumber}`	Par n° de châssis exact
`GET /provider/vehicles/{id}`	Détail

Réponse : objet Vehicle avec les référentiels développés (brand, model, vehicleType, vehicleCategory, energy, usage, vehicleGender, circulationCity, zone) et les caractéristiques techniques.

Mettre à jour, activer, désactiver

PUT /provider/vehicles/{id} — même corps que la création. Refusé si le véhicule a déjà été rattaché à un contrat actif (ou suspendu, résilié, expiré).
PATCH /provider/vehicles/{id}/enable et PATCH /provider/vehicles/{id}/disable — activent ou désactivent le véhicule (isActive).

Un véhicule déjà couvert par un contrat en cours ne peut pas être re-souscrit (VEHICLE_ALREADY_INSURED). Un véhicule présent dans une autre proposition en attente de paiement bloque aussi la création (PENDING_PAYMENT_LINK_ON_SHARED_VEHICLE).