☰
Partner Documentation

Partner API

Allez au chapitre...

Partner API

API HTTP JSON décrite via OpenAPI.

Routes actuellement déployées :

Route Méthode Description
/catalog POST Mise à jour des lots du catalogue
/lots GET/POST Récupérer les lots d’une vente
/delete-lot POST Supprimer un lot spécifique
/bidder/list GET/POST Lister les enchérisseurs inscrits
/bidder/update POST Mettre à jour le statut d’inscription d’un enchérisseur
/absenteebid/list GET/POST Lister les ordres d’achat
/absenteebid/update POST Mettre à jour le statut d’un ordre d’achat
/adj/list POST Lister les adjudications
/results POST Mettre à jour les résultats de la vente
/sale/list POST Lister les ventes à venir
/sale/add-sourceId POST Ajouter un ID source à une vente existante

La spécification OpenAPI est disponible sur https://api.zonesecure.org/openapi.json

Vous pouvez la consulter avec Swagger UI.

Méthodes d’authentification

Nous proposons deux méthodes d’authentification distinctes pour accéder à nos services.

Méthode 1 : Jeton JWT (Recommandée)

Utilisez un JSON Web Token (JWT) dans l’en-tête Authorization :

Authorization: Bearer <votre-jeton-jwt>

Comment obtenir un jeton JWT : Vous trouverez votre jeton JWT dans notre portail Back-office sur Focus Back-office. Une fois connecté, visitez la page “Ma maison de ventes” où vous trouverez une section dédiée à l’intégration API.

Méthode 2 : Identifiants de compte (Obsolète)

Incluez account_id et account_key dans le corps de la requête. Cette méthode est obsolète et n’est supportée que pour les intégrations existantes.

{
  "account_id": "votre_account_id",
  "account_key": "votre_account_key",
  ...
}

Vente / Catalogue

Le terme « vente » correspond au catalogue détaillé qui répertorie tous les lots disponibles. La vente comprend des descriptions, des photographies et les estimations de prix.

source_id

Le paramètre source_id correspond à l’identifiant externe (de votre côté) d’une vente et doit être défini dans la page de modification de vente de notre backoffice Focus (‘ID Passerelle’) avant d’utiliser l’API.

img.png

Référence des routes

POST /catalog

Mise à jour du catalogue d’une vente à venir.

Corps de la requête :

{
  "source_id": "votre_source_id_vente",
  "ignore_images": false,
  "fname_as_hash": true,
  "mode": "DIFF",
  "ftp": {
    "url": "ftp.example.com:21",
    "login": "utilisateur",
    "pw": "motdepasse"
  },
  "lots": [
    {
      "id": "id_externe_lot",
      "num": "1",
      "sous": "a",
      "low_estim": 100,
      "high_estim": 200,
      "starting_price": 50,
      "description": "Description originale",
      "desc_fr": "Description en français",
      "desc_en": "English description",
      "images": ["https://example.com/image1.jpg", "chemin/vers/image2.jpg"],
      "props": {
        "2": "Renault",
        "6": "45000"
      },
      "height": 30,
      "width": 40,
      "depth": 10,
      "weight": 500,
      "is_pro": false,
      "isPhare": true
    }
  ]
}
Champ Type Requis Description
source_id string Oui ID externe de la vente (défini dans le backoffice Focus)
ignore_images boolean Non Ignorer le traitement des images (défaut : false)
fname_as_hash boolean Non Utiliser le nom de fichier comme hash pour des mises à jour plus rapides (défaut : true)
mode string Non DIFF (ajout/mise à jour/suppression) ou ADD (ajout/mise à jour uniquement). Défaut : ADD
ftp object Non Configuration FTP pour le transfert d’images
lots array Oui Tableau d’objets lot

Champs de l’objet Lot :

Champ Type Requis Description
id string Oui Votre identifiant unique de lot
num string Non Numéro du lot
sous string Non Suffixe du lot (ex : “bis”, “ter”, “A”, “B”, “1”, “2”)
low_estim integer Non Estimation basse
high_estim integer Non Estimation haute
starting_price integer Non Prix de départ (obligatoire pour les ventes online)
description string Non Description originale (max 5000 caractères)
desc_fr string Non Description en français
desc_en string Non Description en anglais
desc_de string Non Description en allemand
desc_it string Non Description en italien
desc_es string Non Description en espagnol
desc_zh string Non Description en chinois
images array Non URLs d’images ou chemins FTP
props object Non Paires clé-valeur de propriétés (voir propriétés)
height integer Non Hauteur en cm
width integer Non Largeur en cm
depth integer Non Profondeur en cm
weight integer Non Poids en grammes
is_pro boolean Non Réservé aux acheteurs professionnels
isPhare boolean Non Lot phare/mis en avant

Réponse :

{
  "id": 12345
}

GET/POST /lots

Récupérer la liste des lots d’une vente donnée.

Corps de la requête :

{
  "source_id": "votre_source_id_vente"
}

Réponse :

{
  "lots": [
    {
      "id": "123456",
      "num": 1,
      "sous": "",
      "idExtra": "id_externe_lot",
      "weblinkFr": "https://drouot.com/fr/l/123456-description",
      "weblinkEn": "https://drouot.com/en/l/123456-description"
    }
  ],
  "saleIdExtra": "votre_source_id_vente",
  "saleId": 12345
}

POST /delete-lot

Supprimer un lot spécifique d’une vente.

Corps de la requête :

{
  "sale_source_id": "votre_source_id_vente",
  "lot_source_id": "id_externe_lot"
}

Réponse : 200 OK avec "ok"

Note : La suppression de lot est interdite pour les ventes qui ont déjà été publiées (MEL).

GET/POST /bidder/list

Récupérer la liste des enchérisseurs inscrits à une vente.

Corps de la requête :

{
  "source_id": "votre_source_id_vente"
}

Réponse :

{
  "bidders": [
    {
      "id": 12345,
      "mail": "jean.dupont@example.com",
      "firstname": "Jean",
      "lastname": "Dupont",
      "country": "France",
      "countryCode": "FR",
      "zipcode": "75009",
      "city": "Paris",
      "address": "1 Rue Exemple",
      "tel": "+33123456789",
      "company": "Dupont & Fils",
      "tva_intra": "FR 32 123456789",
      "siret": "123 568 941 00056",
      "lang": "fr",
      "paddle": "8002",
      "status": "ACCEPTED"
    }
  ]
}

Valeurs de statut des enchérisseurs :

Statut Description
ACCEPTED Inscription approuvée
REFUSED Inscription refusée
INCOMPLETE En attente de vérification
BLACKLISTED Utilisateur sur liste noire

POST /bidder/update

Mettre à jour le statut d’inscription d’un enchérisseur.

Corps de la requête :

{
  "source_id": "votre_source_id_vente",
  "id": 12345,
  "status": "ACCEPTED"
}
Champ Type Requis Valeurs
source_id string Oui ID source de la vente
id integer Oui ID de l’enchérisseur
status string Oui ACCEPTED ou REFUSED

Réponse : 200 OK avec "ok"

GET/POST /absenteebid/list

Récupérer la liste des ordres d’achat d’une vente.

Corps de la requête :

{
  "source_id": "votre_source_id_vente"
}

Réponse :

{
  "bids": [
    {
      "id": 1234,
      "lot_num": "1",
      "lot_sous": "a",
      "lot_id": 123455,
      "lot_source_id": "id_externe_lot",
      "value": 500,
      "status": "PENDING",
      "bidder": {
        "id": 12345,
        "mail": "jean.dupont@example.com",
        "firstname": "Jean",
        "lastname": "Dupont",
        "paddle": "8002",
        "status": "ACCEPTED"
      }
    }
  ]
}

Valeurs de statut des ordres : PENDING, ACCEPTED, REFUSED

POST /absenteebid/update

Mettre à jour le statut d’un ordre d’achat.

Corps de la requête :

{
  "id": 1234,
  "status": "ACCEPTED"
}
Champ Type Requis Valeurs
id integer Oui ID de l’ordre d’achat
status string Oui ACCEPTED ou REFUSED

Réponse : 200 OK avec "ok"

Note : Un email de notification est envoyé à l’enchérisseur après la mise à jour du statut.

POST /adj/list

Récupérer la liste des adjudications (enchères gagnantes) d’une vente.

Corps de la requête :

{
  "source_id": "votre_source_id_vente"
}

Réponse :

{
  "adjudications": [
    {
      "lot_num": "1",
      "lot_sous": "",
      "lot_id": 123455,
      "lot_source_id": "id_externe_lot",
      "value": 1500,
      "paddle": "8002",
      "bidder": {
        "id": 12345,
        "mail": "gagnant@example.com",
        "firstname": "Marie",
        "lastname": "Gagnante"
      }
    }
  ]
}

POST /results

Mettre à jour les résultats de la vente (prix marteau).

Corps de la requête :

{
  "source_id": "votre_source_id_vente",
  "results": [
    {
      "source_id": "id_externe_lot",
      "value": 1500.00
    }
  ]
}

Réponse :

{
  "source_id": "votre_source_id_vente",
  "update_count": 5
}

POST /sale/list

Récupérer la liste des ventes à venir.

Corps de la requête :

{}

Réponse :

{
  "sales": [
    {
      "source_id": "id_externe_vente",
      "internal_id": 12345,
      "title": "Vente d'Art Moderne",
      "date": "2025-01-15 14:00:00",
      "time_zone": "Europe/Paris"
    }
  ]
}

POST /sale/add-sourceId

Ajouter un ID source à une vente existante qui n’en a pas encore.

Corps de la requête :

{
  "internal_id": 12345,
  "source_id": "nouveau_source_id"
}
Champ Type Requis Description
internal_id integer Oui ID interne Drouot de la vente
source_id string Oui Votre ID externe de vente

Réponse : 200 OK

Note : Ceci ne fonctionne que pour les ventes à venir qui n’ont pas encore d’ID source défini.

Transfert d’images

Toutes les images doivent être des JPEG de moins de 1 Mo.

Transfert par URL publique (Recommandé)

Aucun traitement préalable requis. Les images sont référencées directement par leur URL publique :

"images": ["https://example.com/image1.jpg", "https://example.com/image2.jpg"]

Transfert via FTP

Ajoutez la configuration FTP et référencez les images par leur chemin relatif :

{
  "ftp": {
    "url": "ftp-gateway.zonesecure.org:21",
    "login": "votre_login",
    "pw": "votre_motdepasse"
  },
  "lots": [{
    "images": ["chemin/vers/image1.jpg", "chemin/vers/image2.jpg"]
  }]
}

Serveur FTP Drouot : ftp-gateway.zonesecure.org:21

Option fname_as_hash

Lorsque fname_as_hash: true, les images avec le même nom de fichier sont considérées comme inchangées, ce qui accélère la synchronisation. Attention, les images modifiées mais non renommées ne seront pas mises à jour.

Réponses d’erreur

Toutes les routes retournent les erreurs dans le format suivant :

{
  "message": "Description de l'erreur"
}

Codes de statut HTTP courants :

Code Description
200 Succès
400 Requête invalide (paramètres incorrects)
401 Non autorisé (identifiants invalides)
403 Interdit (pas d’accès à la ressource)
500 Erreur serveur interne