API Catawiki : lots, prix de réserve et ventes closes en JSON

Sur Catawiki, une enchère se lit en plusieurs morceaux : la mise en cours, l'existence d'un prix de réserve et le fait qu'il soit atteint ou non, les frais de protection acheteur, le port vers votre pays, puis, une fois la vente close, le lot adjugé ou resté invendu. Cette API rassemble ces éléments en JSON, tels qu'un visiteur sans compte peut les consulter ; avec `"language": "fr"`, titres, descriptions et caractéristiques arrivent dans la version française du site, et les montants sont en euros par défaut. Elle ne dépose aucun lot et ne place aucune enchère : c'est un outil de lecture côté acheteur, qui ne remplace en rien les outils que Catawiki met à disposition de ses vendeurs.

Exemple qui fonctionne

« Visions horizontales : Chefs-d'œuvre XXL », une vente de peintures close le 25 octobre 2026 : `auction/lots` en renvoie 89 lots. 66 ont été adjugés, 37 sans prix de réserve et 29 dont la réserve a été atteinte ; 23 sont restés invendus faute d'avoir atteint leur réserve, alors que chacun avait reçu des enchères. Le montant de cette réserve n'apparaît nulle part, Catawiki publiant seulement son existence et le fait qu'elle soit atteinte. Pour les lots invendus, `current_bid` donne la dernière mise (100 € pour « Le Cavalier Rose ») : ce n'est pas un prix de vente. Seul `sold_price` en est un.

curl -X POST https://api.reefapi.com/catawiki/v1/auction/lots \
  -H "x-api-key: VOTRE_CLE" \
  -H "content-type: application/json" \
  -d '{"auction_id": 1280000, "language": "fr", "per_page": 100}'

{
  "ok": true,
  "data": {
    "auction": {
      "auction_id": 1280000,
      "title": "Visions horizontales : Chefs-d’œuvre XXL",
      "url": "https://www.catawiki.com/fr/a/1280000-visions-horizontales-chefs-d-oeuvre-xxl",
      "status": "closed",
      "close_time": "2026-10-25T19:00:00Z",
      "closed_at": "2026-10-25T20:35:05Z",
      "lot_count": 90,
      "themed": true
    },
    "lots": [
      {
        "lot_id": 107579573,
        "title": "… - Le Cavalier Rose ↑120 →140 cm",
        "subtitle": "Peinture à l’huile - Signé à la main - 2026",
        "currency": "EUR",
        "current_bid": 100,
        "has_bids": true,
        "status": "closed",
        "is_sold": false,
        "sold_price": null,
        "reserve_price_set": true,
        "reserve_price_met": false,
        "end_time": "2026-10-25T19:01:00Z",
        "favorite_count": 27
      },
      {
        "lot_id": 107043054,
        "title": "… - Lost in stripes XXL",
        "subtitle": "Peinture acrylique - Signé(e) - 2026",
        "currency": "EUR",
        "current_bid": 175,
        "has_bids": true,
        "status": "closed",
        "is_sold": true,
        "sold_price": 175,
        "reserve_price_set": false,
        "reserve_price_met": null,
        "end_time": "2026-10-25T19:03:54Z"
      },
      {
        "lot_id": 107575342,
        "title": "… - Cielo Velado XXL",
        "subtitle": "Peinture acrylique - Signé à la main - 2026",
        "currency": "EUR",
        "current_bid": 180,
        "is_sold": true,
        "sold_price": 180,
        "reserve_price_set": true,
        "reserve_price_met": true
      },
      ...
    ],
    "count": 89,
    "total_results": 89,
    "has_more": false,
    "language": "fr",
    "currency": "EUR"
  },
  "meta": { "record_count": 89, "bid_state": "ok", "cache_hit": false, "mode": "live" }
}

Limites et remarques honnêtes

• Ce service n'émane pas de Catawiki : c'est une lecture indépendante de ses pages publiques, non officielle, sans partenariat ni accord commercial avec la maison de ventes.
• Le montant du prix de réserve n'est jamais publié, seulement sa présence (`reserve_price_set`) et son franchissement (`reserve_price_met`, null quand le lot n'a pas de réserve).
• Pas de recherche par mot-clé dans les ventes terminées : Catawiki ignore ce filtre. Les résultats passés se lisent vente par vente avec `auction/lots`, à partir de l'`auction_id` que porte chaque lot, ou lot par lot avec `product/detail`.
• La mise n'est pas le prix payé. Pour l'album « Astérix chez les Helvètes » en EO de 1970, une mise de 30 € devenait 45,20 € une fois ajoutés les frais de protection acheteur (9 % + 3 €, soit 5,70 €) et 9,50 € d'envoi vers la France. Ce total (`total_if_won_now`) n'est calculé que pour un lot ouvert et avec `shipping_country`.
• Dans l'exemple, la vente annonçait 90 lots (`lot_count`) et la liste en contenait 89 : pour vos statistiques, comptez les lignes renvoyées.
• Les lots anciens sont archivés et répondent NOT_FOUND (identifiants 90000000 et 100000000 lors de nos mesures) ; un identifiant de vente inexistant aussi, comme 1279000 le 27 octobre 2026.
• `lot/bids` donne les pseudonymes publics des enchérisseurs et leur pays, comme la page ; `product/detail` contient en plus le nom public du vendeur. Dans l'exemple ci-dessus, le nom de l'artiste placé en tête de chaque titre a été remplacé par « … ».
• Chaque appel coûte 1 crédit, quelle que soit l'action, y compris la fiche complète d'un lot.