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 XMLAccept: 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’ |
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&Co Yacht Timer Multifunctional – men's watch – 2017.</legende>
<description>Brand: So&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
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 |