openapi: 3.1.0
info:
  title: ImmatSIV Partner API
  version: 1.1.1
  description: |
    API serveur à serveur multi-partenaires (assureurs, loueurs, plateformes,
    garages, SaaS et intégrations white-label). Les tarifs sont pilotés par
    ImmatSIV / DSG AUTO et ne sont jamais modifiables par un partenaire.
    Toute réponse JSON inclut un request_id stable, également renvoyé dans
    l'en-tête X-Request-ID. Toute erreur suit { ok:false, code, error, request_id }.
servers:
  - url: https://immatsiv.fr/api/partenaires/v1
security:
  - partnerBearer: []
components:
  securitySchemes:
    partnerBearer:
      type: http
      scheme: bearer
      bearerFormat: ImmatSIV partner API key
  schemas:
    Error:
      type: object
      required: [ok, code, error, request_id]
      properties:
        ok: { type: boolean, const: false }
        code: { type: string }
        error: { type: string }
        request_id: { type: string }
    WorkflowStep:
      type: object
      properties:
        key: { type: string, enum: [documents, csa, tarification, siv, archivage] }
        label: { type: string }
        state: { type: string, enum: [done, action_required, processing, blocked, locked] }
        color: { type: string, enum: [green, amber, red, gray] }
    Dossier:
      type: object
      properties:
        id: { type: string, format: uuid }
        reference: { type: string }
        external_reference: { type: string }
        organisation_id: { type: string, format: uuid }
        demarche:
          type: string
          enum: [titulaire, titulaire_pro, achat, cession, ww, etranger, quitus, import_complet, deuxroues, duplicata, adresse, fiche_id, csa, w_garage]
          x-enum-labels:
            - Changement de titulaire
            - Changement de titulaire (VO) — Vente par un professionnel
            - Déclaration d'achat
            - Déclaration de cession
            - WW ou CPI
            - Véhicule importé de l'étranger
            - Deux-roues, scooter ou moto
            - Duplicata de carte grise
            - Changement d'adresse
            - Fiche d'identification
            - Certificat de situation administrative
            - W garage
        libelle: { type: string }
        statut: { type: string }
        immatriculation: { type: [string, "null"] }
        vin: { type: [string, "null"] }
        client_nom: { type: string }
        client_email: { type: string, format: email }
        honoraires_cts: { type: integer }
        honoraires_reference_cts: { type: integer }
        remise_pro_bp: { type: integer }
        pack_utilise: { type: boolean }
        workflow:
          type: object
          properties:
            active: { type: string }
            blocked: { type: boolean }
            steps:
              type: array
              items: { $ref: "#/components/schemas/WorkflowStep" }
    UploadPreparation:
      type: object
      properties:
        ok: { type: boolean }
        piece_id: { type: string, format: uuid }
        piece_cle: { type: string }
        ordre: { type: integer }
        upload_url: { type: string, format: uri }
        upload_method: { type: string, const: PUT }

paths:
  /connection:
    get:
      summary: Tester la clé et lire les capacités du partenaire
      responses:
        "200": { description: Connexion valide }
        "401": { description: Clé absente ou invalide }
    post:
      summary: Tester la connexion et facultativement l’état d’un compte lié
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                organisation_id: { type: string, format: uuid }
                siret: { type: string, pattern: "^[0-9]{14}$" }
                garage_reference: { type: string }
                external_organisation_reference: { type: string }
      responses:
        "200": { description: Connexion valide }

  /ping:
    get:
      summary: Ping authentifié
      responses:
        "200": { description: Clé valide }
    post:
      summary: Ping authentifié compatible POST
      responses:
        "200": { description: Clé valide }

  /inscriptions-pro:
    get:
      summary: Lire une inscription professionnelle
      parameters:
        - in: query
          name: external_reference
          required: true
          schema: { type: string, maxLength: 120 }
      responses:
        "200": { description: Inscription trouvée }
        "404": { description: Introuvable }
    post:
      summary: Créer une inscription professionnelle ou renouveler son lien
      responses:
        "201": { description: Inscription créée }
        "200": { description: Retry idempotent }
        "409": { description: Conflit métier }

  /dossiers:
    get:
      summary: Lire un dossier ou lister les dossiers du partenaire
      parameters:
        - in: query
          name: external_reference
          schema: { type: string, maxLength: 120 }
        - in: query
          name: statut
          schema: { type: string }
        - in: query
          name: demarche
          schema: { type: string }
        - in: query
          name: organisation_id
          schema: { type: string, format: uuid }
        - in: query
          name: external_organisation_reference
          schema: { type: string }
        - in: query
          name: limit
          schema: { type: integer, minimum: 1, maximum: 100, default: 50 }
        - in: query
          name: offset
          schema: { type: integer, minimum: 0, default: 0 }
      responses:
        "200":
          description: Dossier ou liste paginée
    patch:
      summary: Modifier les données autorisées d’un dossier
      description: Les prix, remises, taxes et états financiers sont immuables côté partenaire.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [external_reference]
              properties:
                external_reference: { type: string }
                client_nom: { type: string }
                client_email: { type: string, format: email }
                client_tel: { type: string }
                departement: { type: string }
                date_premiere_immatriculation: { type: string, format: date }
                date_certificat_immatriculation: { type: string, format: date }
                titulaire_carte_grise: { type: string }
                raison_sociale_carte_grise: { type: string }
                siren_titulaire: { type: string }
                numero_formule: { type: string }
      responses:
        "200": { description: Dossier modifié }
        "403": { description: Champ tarifaire interdit }
        "409": { description: Dossier déjà entré en contrôle }
    post:
      summary: Créer, soumettre, supprimer ou renouveler le lien d’un dossier
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  required: [external_reference, demarche, client_nom, client_email]
                  properties:
                    external_reference: { type: string }
                    organisation_id: { type: string, format: uuid }
                    siret: { type: string }
                    external_organisation_reference: { type: string }
                    demarche: { type: string }
                    client_nom: { type: string }
                    client_email: { type: string, format: email }
                    client_tel: { type: string }
                    immatriculation: { type: string }
                    vin: { type: string }
                    departement: { type: string }
                    envoyer_email: { type: boolean }
                - type: object
                  required: [action, external_reference]
                  properties:
                    action: { type: string, enum: [finaliser, renouveler_lien] }
                    external_reference: { type: string }
                - type: object
                  required: [action, external_reference, confirmation]
                  properties:
                    action: { const: supprimer }
                    external_reference: { type: string }
                    confirmation: { const: SUPPRIMER }
      responses:
        "201": { description: Dossier créé }
        "200": { description: Action réussie ou retry idempotent }
        "403": { description: Scope insuffisant }
        "409": { description: Action incompatible avec l’état métier }

  /documents:
    get:
      summary: Lire les pièces et documents générés d’un dossier
      parameters:
        - in: query
          name: external_reference
          required: true
          schema: { type: string }
        - in: query
          name: include_urls
          description: Retourne des URLs de lecture signées valables 5 minutes.
          schema: { type: boolean, default: false }
      responses:
        "200": { description: Pièces et documents générés }
    post:
      summary: Préparer ou confirmer un dépôt documentaire white-label
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  required: [action, external_reference, piece_cle, nom_fichier, mime, taille]
                  properties:
                    action: { const: preparer_upload }
                    external_reference: { type: string }
                    piece_cle: { type: string }
                    ordre: { type: integer, minimum: 1, maximum: 6 }
                    nom_fichier: { type: string }
                    mime: { type: string }
                    taille: { type: integer, maximum: 10485760 }
                - type: object
                  required: [action, external_reference, piece_cle]
                  properties:
                    action: { const: confirmer_upload }
                    external_reference: { type: string }
                    piece_cle: { type: string }
                    ordre: { type: integer, minimum: 1, maximum: 6 }
                    sha256: { type: string }
      responses:
        "200": { description: Upload confirmé }
        "201": { description: Réservé }
        "415": { description: Format binaire interdit }

  /evenements:
    get:
      summary: Lire la timeline métier d’un dossier
      parameters:
        - in: query
          name: external_reference
          required: true
          schema: { type: string }
      responses:
        "200": { description: Timeline avec couleurs métier }

  /tarification:
    get:
      summary: Lire le barème applicable
      description: Réponse autoritative non cacheable, non modifiable par le partenaire. Tarifs effectifs HT/TTC des actes et packs après remise. Les packs da_dc couvrent achat et cession avec un compteur commun et une validité de six mois.
      parameters:
        - in: query
          name: organisation_id
          schema: { type: string, format: uuid }
        - in: query
          name: siret
          schema: { type: string }
        - in: query
          name: external_organisation_reference
          schema: { type: string }
      responses:
        "200": { description: Barème des actes et catalogue des packs HT/TTC applicables }
    post:
      summary: Demander ou annuler une étude de remise volume
      responses:
        "201": { description: Demande créée }
        "200": { description: Demande existante ou annulée }
        "400": { description: Volume inférieur à 50 ou requête invalide }

  /audit:
    get:
      summary: Lire le journal technique API du partenaire
      parameters:
        - in: query
          name: external_reference
          schema: { type: string }
        - in: query
          name: limit
          schema: { type: integer, minimum: 1, maximum: 200, default: 100 }
      responses:
        "200": { description: Journal API }

  /plaques:
    get:
      summary: Lire le catalogue ou une commande de plaques
      description: "Scope requis : plaques:read"
      responses:
        "200": { description: Catalogue ou commande }
    post:
      summary: Créer une commande de plaques
      description: "Scope requis : plaques:write"
      responses:
        "201": { description: Commande créée }
        "200": { description: Retry idempotent }