CarHunt Synchronisation API

openapi: 3.2.0
info:
  title: CarHunt Pro Synchronisation API
  description: 'API de sourcing automobile CarHunt Pro : recherche multi-critères dans

    plus d’un million d''annonces actives agrégées depuis 6

    sources. Un cycle complet d''actualisation du catalogue est lancé toutes les

    4 heures. Chaque annonce dispose d''un score de

    sous-cote et de médianes de marché. Les critères des watchlists sont évalués toutes les

    10 minutes sur le catalogue déjà collecté, puis les

    webhooks sont notifiés après détection. ### Authentification

    Créez une clé API dans votre espace app.carhunt.fr

    (Réglages → API, offre Business ou API Analyste attribuée), puis transmettez-la sur chaque requête :


    Authorization: Bearer chp_live_…


    ### Quotas

    Le plan Business inclut un quota mensuel de **véhicules**. L''offre API Analyste,

    attribuée individuellement, inclut 1 000 **analyses** et 5 000 **véhicules**

    par mois calendaire UTC. `GET /v1/usage` expose les deux soldes. Chaque véhicule renvoyé par la recherche ou livré par webhook est décompté

    une fois. `POST /v1/estimate` et `GET /v1/listings/{listing_id}/analysis`

    consomment chacun une analyse si une réponse exploitable est produite ; les

    trois comparables inclus ne débitent pas de véhicules. Une cohorte de moins

    de cinq annonces rend 422 sans débit. Les crédits d''analyse prépayés prennent

    le relais après le quota mensuel et n''expirent pas. Pour proposer 3 à 5 alternatives, appelez `GET /v1/listings/search` avec

    `page_size=3` à `5`, budget (`price_max`) et critères du client ; le nombre

    de véhicules effectivement renvoyés est débité. Aucun classement personnalisé

    ni garantie de disponibilité chez l''annonceur n''est implicite. Rate-limit : 60 req/min par clé. ### Synchronisation des annonces importées

    `GET /v1/listings/changes` accepte jusqu''à 100 identifiants CarHunt dans `ids`. La recherche fournit `sync_until` pour initialiser le suivi sans nouvel import. Sans date, le flux peut réinitialiser un lot (véhicules décomptés). Transmettez

    `updated_since` avec le `sync_until` du dernier lot traité : seuls les véhicules

    réellement modifiés sont renvoyés et décomptés. Une réponse vide ne consomme rien. Chaque élément expose `last_modified_at`, `status` et la fiche `listing`. Les statuts `inactive` et `deleted` permettent de retirer les annonces du catalogue

    client ; `deleted` a une fiche nulle et ne signifie pas vendu. `unknown_ids` ne

    prouve pas un retrait. Revisites et recalculs de score ne déclenchent pas d''édition. Le suivi commence à `tracking_started_at` : une date antérieure rend 409 et exige

    une réinitialisation sans date. Un lot dépassant le solde rend 429 sans décompte. Le paramètre `since` de la recherche continue à servir aux **nouvelles** annonces. ### Estimation et historique

    `POST /v1/estimate` accepte marque, modèle, année, kilométrage et des filtres

    facultatifs (énergie, boîte, motorisation, finition), sans annonce à résoudre. Les quartiles et la médiane portent sur les **prix demandés** d''annonces actives

    comparables, pas sur les transactions. La cohorte est échantillonnée à 2 000

    annonces récentes au maximum ; `sample_truncated` le signale. Les repères de

    négociation sont statistiques : ils ne tiennent pas compte de l''état réel. L''historique et la volatilité de `GET /v1/listings/{listing_id}/analysis`

    concernent **cette annonce**, pas l''ensemble du marché. L''historique peut être vide. `history_status` distingue `unavailable` (aucune observation sur la période demandée),

    `no_change_recorded` (aucune variation enregistrée depuis la première observation)

    et `price_changed`. `source_url` et `current_price` concernent l''annonce analysée. La collecte d''historique ayant débuté en juin 2026, une absence de variation

    enregistrée ne permet pas de conclure sur les prix antérieurs. Exemple d''estimation (prix en euros, kilométrage en km) :


    ```json

    {"make":"RENAULT","model":"CLIO","year":2020,"mileage":50000,"energy":"Essence","asking_price":13500}

    ```


    ### Couverture

    Le catalogue cible les annonces automobiles d''occasion en France.'
  contact:
    name: CarHunt Pro
    url: https://app.carhunt.fr/
    email: contact@carhunt.fr
  version: 1.0.0
servers:
- url: /public-api
- url: https://api-pro.carhunt.fr
  description: Production
- url: https://api-pro-stage.carhunt.fr
  description: Staging
tags:
- name: Synchronisation
paths:
  /v1/listings/changes:
    get:
      tags:
      - Synchronisation
      summary: Synchroniser les annonces importées sans renvoyer les inchangées
      description: 'Jusqu''à 100 identifiants CarHunt (`id`, pas l''identifiant source). `updated_since` filtre les changements de prix, caractéristiques, photo, lien et activité. Une revisite ou un recalcul du score n''est pas une modification. Sans date : état initial ; avec date : uniquement les changements. Chaque résultat, même inactif ou supprimé, consomme un véhicule. Les inchangés/inconnus ne consomment rien ; les répétitions sont décomptées. Date antérieure au suivi : 409, refaire l''état initial. `unknown_ids` ne prouve pas un retrait. `deleted` signifie supprimé du catalogue, pas vendu. Les retraits dépendent de leur détection par les collecteurs. Conservez `sync_until` après traitement réussi. Chaque lot garde son checkpoint.'
      operationId: listing_changes_v1_listings_changes_get
      parameters:
      - name: ids
        in: query
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 3699
          description: 1 à 100 UUID CarHunt séparés par des virgules
          title: Ids
        description: 1 à 100 UUID CarHunt séparés par des virgules
      - name: updated_since
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: Modifications strictement après ce timestamp ISO avec fuseau ; omettre pour initialiser
          title: Updated Since
        description: Modifications strictement après ce timestamp ISO avec fuseau ; omettre pour initialiser
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChangesResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ChangesResponse:
      properties:
        changes:
          items:
            $ref: '#/components/schemas/ListingChangeOut'
          type: array
          title: Changes
        unknown_ids:
          items:
            type: string
          type: array
          title: Unknown Ids
        sync_until:
          type: string
          format: date-time
          title: Sync Until
        tracking_started_at:
          type: string
          format: date-time
          title: Tracking Started At
        vehicle_units_charged:
          type: integer
          title: Vehicle Units Charged
      type: object
      required:
      - changes
      - unknown_ids
      - sync_until
      - tracking_started_at
      - vehicle_units_charged
      title: ChangesResponse
    ListingChangeOut:
      properties:
        id:
          type: string
          title: Id
        last_modified_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Last Modified At
        status:
          type: string
          enum:
          - active
          - inactive
          - deleted
          title: Status
        listing:
          anyOf:
          - $ref: '#/components/schemas/ListingOut'
          - type: 'null'
      type: object
      required:
      - id
      - last_modified_at
      - status
      - listing
      title: ListingChangeOut
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ListingOut:
      properties:
        id:
          type: string
          title: Id
        make:
          anyOf:
          - type: string
          - type: 'null'
          title: Make
        model:
          anyOf:
          - type: string
          - type: 'null'
          title: Model
        version:
          anyOf:
          - type: string
          - type: 'null'
          title: Version
          description: Libellé de version brut de l'annonce
        finition:
          anyOf:
          - type: string
          - type: 'null'
          title: Finition
          description: Finition normalisée (ex. « R-Line ») — disponible sur ~2/3 des annonces
        year:
          anyOf:
          - type: integer
          - type: 'null'
          title: Year
        mileage:
          anyOf:
          - type: integer
          - type: 'null'
          title: Mileage
        price:
          anyOf:
          - type: integer
          - type: 'null'
          title: Price
        energy:
          anyOf:
          - type: string
          - type: 'null'
          title: Energy
        gearbox:
          anyOf:
          - type: string
          - type: 'null'
          title: Gearbox
        horsepower:
          anyOf:
          - type: integer
          - type: 'null'
          title: Horsepower
        seller_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Seller Type
          description: '''pro'' | ''private'' | null (inconnu) — capturé depuis le 2026-07-17, couverture croissante au fil des re-scrapes'
        department:
          anyOf:
          - type: string
          - type: 'null'
          title: Department
        city:
          anyOf:
          - type: string
          - type: 'null'
          title: City
        deal_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Deal Score
          description: Score de sous-cote 0-100 (50 = prix médian marché, plus haut = meilleure affaire)
        photo_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Photo Url
        source:
          anyOf:
          - type: string
          - type: 'null'
          title: Source
          description: Site annonceur d'origine
        source_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Url
          description: Lien direct vers l'annonce d'origine
        first_seen:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: First Seen
          description: Découverte de l'annonce par CarHunt (base du paramètre `since`)
        updated_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Updated At
      type: object
      required:
      - id
      title: ListingOut
      description: Une annonce. `source_url` pointe vers l'annonce chez l'annonceur d'origine.