Introduction

Vous trouverez ci-dessous la documentation de l'API Bidtween.

L'API permet de créer des ventes et lots depuis un logiciel tiers, pour le compte d'un commissaire priseur.

Format des payloads

L'API supporte les formats XML et JSON en entrée et sortie. Par défaut, JSON est utilisé.

La sélection d'un format est faite en utilisant les entêtes HTTP suivantes:

Content-Type: application/xml pour uploader des données encodées en XML
Accept: application/xml pour recevoir des données encodées en XML

Authentification

L'API Bidtween utilise un OAuth Bearer Token pour l'authentification des requêtes HTTP.

Chacune des requêtes à l'API doit comporter l'entête HTTP suivante:

Authorization: Bearer OAUTH_BEARER_TOKEN

Connexion

curl -X "POST" "https://bidtween.com/oauth/token" \
     -H "Accept: application/xml" \
     -H "X-Requested-With: XMLHttpRequest" \
     -H "Content-Type: application/xml" \
     -d $'<data>
            <username>cp0@bidtween.com</username>
            <client_id>1</client_id>
            <password>********</password>
            <client_secret>wZmAafqjXn4DvoKgxvkoNKWyQdiTnIOB42Dtn9Nf</client_secret>
            <grant_type>password</grant_type>
        </data>'

La commande ci-dessus retourne une réponse XML formattée ainsi:

<data>
  <token_type>Bearer</token_type>
  <expires_in>1296000</expires_in>
  <access_token>eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6IjI0YjA...-yofQ7XAYP4vV0</access_token>
  <refresh_token>JPp1XZ7yfSgOapXeN8LIo8xtuJtYtMT+HGvkDwNJCk3sWXPGxE7aO...o8mAwCw=</refresh_token>
</data>

Cette API retourne un Bearer Token.

HTTP Request

POST https://bidtween.com/oauth/token

Parameters

Parameter	Optional	Description
username	false	L'email du commissaire priseur
password	false	Le mot de passe Bidtween du commissaire priseur
client_id	false	Votre ID de clé d'API
client_secret	false	Votre secret de clé d'API
grant_type	false	Laisser à ‘password’

Vous devez remplacer client_id et client_secret avec votre clé d'API.

Ventes

Créer une vente

curl -X "POST" "https://bidtween.com/api/auctions" \
     -H "X-Requested-With: XMLHttpRequest" \
     -H "Authorization: Bearer eyJ0eXAi....Zd2fLRt3pJawqOud4he47Po2qAUM_np1JHxxyNUYQ1E" \
     -H "Content-Type: application/xml" \
     -H "Accept: application/xml" \
     -d $'<data>
            <legende>Ma vente</legende>
            <description>Description de ma vente</description>
        </data>'

La commande ci-dessus retourne une réponse XML formattée ainsi:

<data>
  <data>
    <title>Vente 2017-03-16 06:10:42</title>
    <description>Description de ma vente</description>
    <b_draft>1</b_draft>
    <user_id>8</user_id>
    <slug>vente-2017-03-16-06-10-42</slug>
    <updated_at>2017-03-16 06:10:42</updated_at>
    <created_at>2017-03-16 06:10:42</created_at>
    <id>30</id>
  </data>
</data>

Cette API crée une vente pour le commissaire priseur courant.

HTTP Request

POST https://bidtween.com/api/auctions

Parameters

Parameter	Optional	Description
legend	true	Titre de la vente (clé à définir)
description	true	Description de la vente (clé à définir)

Récupérer les détails et résultats d'une vente

curl -X "GET" "https://bidtween.dev/api/auctions/30" \
     -H "X-Requested-With: XMLHttpRequest" \
     -H "Authorization: Bearer eyJ0eXAi....Zd2fLRt3pJawqOud4he47Po2qAUM_np1JHxxyNUYQ1E" \
     -H "Content-Type: application/xml" \
     -H "Accept: application/xml"

La commande ci-dessus retourne une réponse XML formattée ainsi:

<data>
  <data>
    <legende>Adipisci sit dolores totam mollitia eius occaecati. Ut qui consequuntur quo iusto ipsam. Fugiat non est enim iste quisquam delectus omnis.</legende>
    <description>Queen, the royal children, and make THEIR eyes bright and eager with many a strange tale, perhaps even with the distant sobs of the legs of the crowd below, and there was no use their putting their heads down and make </description>
    <lots>
      <item0/>
        <id>59</id>
        <legende>Soviet Raketa perpetual calendar men's wristwatch 1980's in mint condition ,never worn</legende>
        <description>Stunning   Soviet Raketa hand wind wrist watch</description>
        <enchere>408</enchere>
        <repris/>
        <images>
          <item0>
            <id>59</id>
            <url>images/lots/59/sLRJ7Oa4qmCCHNPKqtWEIku14TQFUkdj.jpg</url>
            <original_width>394</original_width>
            <original_height>700</original_height>
            <created_at>2017-04-07 06:16:26</created_at>
            <updated_at>2017-04-07 06:16:26</updated_at>
            <lot_id>59</lot_id>
            <title/>
          </item0>
        </images>
        <acheteur>
          <nom>4</nom>
          <prenom>User</prenom>
          <adresse/>
          <ville/>
          <cp/>
          <pays/>
          <tel/>
          <email>user4@bidtween.website</email>
          <id>5</id>
        </acheteur>
      </item0>
      <item1>
        <id>60</id>
        <legende>So&amp;Co Yacht Timer Multifunctional – men's watch – 2017.</legende>
        <description>Brand: So&amp;Co. Collection: Yacht Timer Multifunctional. Case material: metal.</description>
        <enchere>468</enchere>
        <repris>1</repris>
        <images>
          <item0>
            <id>60</id>
            <url>images/lots/60/3P48u5fnPDwX5gVn8wZ2aknV2Rok0PIW.jpg</url>
            <original_width>700</original_width>
            <original_height>525</original_height>
            <created_at>2017-04-07 06:16:26</created_at>
            <updated_at>2017-04-07 06:16:26</updated_at>
            <lot_id>60</lot_id>
            <title/>
          </item0>
        </images>
      </item1>
    </lots>
  </data>
</data>

Cette API retourne l'état d'une vente et ses lots, ainsi que les résultats de vente. Si les champs enchere et repris ne sont pas présents, alors la vente est toujours en cours.

HTTP Request

GET https://bidtween.com/api/auctions/<ID>

URL Parameters

Parameter	Description
ID	L'ID de la vente

Lots

Créer un lot

curl -X "POST" "https://bidtween.com/api/auctions/9/lots" \
     -H "X-Requested-With: XMLHttpRequest" \
     -H "Authorization: Bearer eyJ0eXAi....Zd2fLRt3pJawqOud4he47Po2qAUM_np1JHxxyNUYQ1E" \
     -H "Content-Type: application/xml" \
     -H "Accept: application/xml" \
     -d $'<data>
            <identifiant>03-75009-201302131602476803-0501</identifiant>
            <numero-ordre>
                <numero>501</numero>
                <bis></bis>
            </numero-ordre>
            <id-categorie>0</id-categorie>
            <description>Rare oushebti portant une inscription à l'encre noire au nom d'UIret-Hor-Erou. Un panier dorsal stylisé est incisé au dos.
            Cire.
            Egypte, Basse-Epoque, début de la XXVIe dynastie, 664-525 av. J.-C.
            H : 6.9 cm.</description>
            <estimation-basse>450</estimation-basse>
            <estimation-haute>500</estimation-haute>
            <lot-phare>0</lot-phare>
            <reference-etude></reference-etude>
            <largeur></largeur>
            <longueur></longueur>
            <profondeur></profondeur>
            <frais-HT></frais-HT>
            <frais-TTC></frais-TTC>
            <lien-externe></lien-externe>
            <rang>00</rang>
            <legende>Rare oushebti portant une inscription à l'encre</legende>
        </data>'

La commande ci-dessus retourne une réponse XML formattée ainsi:

<data>
  <data>
    <legende>Rare oushebti portant une inscription à l'encre</legende>
    <description>Rare oushebti portant une inscription à l'encre noire au nom d'UIret-Hor-Erou. Un panier dorsal stylisé est incisé au dos.
                             Cire.
                             Egypte, Basse-Epoque, début de la XXVIe dynastie, 664-525 av. J.-C.
                             H : 6.9 cm.</description>
    <b_draft>1</b_draft>
    <user_id>8</user_id>
    <slug>vente-2017-03-16-06-10-42</slug>
    <updated_at>2017-03-16 06:10:42</updated_at>
    <created_at>2017-03-16 06:10:42</created_at>
    <id>30</id>
  </data>
</data>

Cette API crée un lot pour une certaine vente.

HTTP Request

POST https://bidtween.com/api/auctions/<ID>/lots

URL Parameters

Parameter	Optional	Description
ID	L'ID de la vente

Images

Uploader une image pour un lot

curl -X "POST" "https://bidtween.com/api/auctions/9/lots/30/images" \
     -H "X-Requested-With: XMLHttpRequest" \
     -H "Authorization: Bearer eyJ0eXAi....Zd2fLRt3pJawqOud4he47Po2qAUM_np1JHxxyNUYQ1E" \
     -H "Accept: application/xml" \
     -F file=@image.jpg

La commande ci-dessus retourne une réponse XML formattée ainsi:

<data>
  <data>
    <url>images/lots/74/dBfyc32iRRN6UQCpNn57xPzE4zxJRenP.jpeg</url>
    <title>file upload from Cheops</title>
    <original_width>500</original_width>
    <original_height>400</original_height>
    <lot_id>74</lot_id>
    <updated_at>2017-04-11 00:26:20</updated_at>
    <created_at>2017-04-11 00:26:20</created_at>
    <id>77</id>
  </data>
</data>

Cette API uploade une image pour un certain lot.

HTTP Request

POST https://bidtween.com/api/auctions/<AUCTION_ID>/lots/<LOT_ID>/images

URL Parameters

Parameter	Optional	Description
AUCTION_ID	false	L'ID de la vente
LOT_ID	false	L'ID du lot

Erreurs

Vous devriez toujours vérifier le HTTP status code avant de décoder le body de la réponse HTTP

Vérifiez toujours que les entêtes Content-type et Accept sont initialisées à application/xml. Sinon votre parseur XML échouera ou l'API ne retournera pas de réponse.

L'API Bitween produit les codes de statut HTTP suivants:

Error Code	Meaning
400	Bad Request – Requête malformée
401	Unauthorized – Votre clé d'API n'est pas valide
403	Forbidden – Le commissaire priseur courant n'a pas accès à cette ressource
404	Not Found
405	Method Not Allowed
422	Too Many Requests – Requête malformée
429	Too Many Requests – Rate limiting
500	Internal Server Error – Erreur interne. Vérifiez les headers de `content negotiation`
503	Service Unavailable