Comment utiliser les APIs eBay ?

En bref

Les API eBay vous permettent de gérer l'inventaire, les annonces, les commandes et les paiements sur la plus grande place de marché mondiale. Vous vous authentifiez avec OAuth 2.0, appelez les points de terminaison api.ebay.com/sell et gérez attentivement les limites de débit. Pour les tests, utilisez Apidog pour valider les charges utiles des annonces, tester le traitement des commandes et vous assurer que votre intégration gère les limites d'API avec souplesse.

Introduction

eBay connecte acheteurs et vendeurs à l'échelle mondiale. L'API permet aux vendeurs d'automatiser la gestion des stocks, de créer des annonces en masse, de traiter les commandes, de gérer les expéditions et les retours. Que vous soyez un petit vendeur ou une entreprise, l'API est évolutive.

Les principaux domaines de l'API :

API d'inventaire - Gérer l'inventaire des produits
API d'annonces - Créer et gérer les annonces d'articles
API de commande - Traiter les commandes et les expéditions
API d'exécution (Fulfillment) - Gérer l'expédition et le suivi
API d'analyse - Extraire les rapports de vente

💡

Si vous développez des intégrations eBay, Apidog vous aide à tester la création d'annonces, à valider les réponses des commandes et à garantir que votre intégration gère correctement les limites de débit et les erreurs.

bouton

Testez les API eBay avec Apidog - gratuit

À la fin de ce guide, vous serez capable de :

Vous authentifier avec eBay OAuth 2.0
Créer et gérer l'inventaire
Publier des annonces
Traiter les commandes et les expéditions
Gérer les retours et les remboursements
Tester avec Apidog

Authentification avec OAuth 2.0

eBay utilise OAuth 2.0 pour l'authentification API. Vous devrez créer une application dans le programme eBay Developers.

Créer une application

Allez sur developers.ebay.com
Inscrivez-vous pour un compte développeur
Créez une application dans la console développeur
Obtenez votre ID d'application (client ID) et votre ID de certificat (client secret)

Flux OAuth

Étape 1 : Autorisation de l'utilisateur

https://auth.ebay.com/oauth2/authorize?
  client_id=YOUR_APP_ID&
  response_type=code&
  redirect_uri=YOUR_SIGNIN_REDIRECT_URI&
  scope=https://api.ebay.com/oauth/api_scope/sell.inventory

Étape 2 : Obtenir le code d'autorisation

L'utilisateur autorise, vous obtenez un code à votre URI de redirection.

Étape 3 : Échanger contre des jetons

const response = await fetch('https://api.ebay.com/identity/v1/oauth2/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'Authorization': 'Basic ' + Buffer.from(APP_ID + ':' + CERT_ID).toString('base64')
  },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    code: AUTHORIZATION_CODE,
    redirect_uri: 'YOUR_SIGNIN_REDIRECT_URI'
  })
})

const { access_token, refresh_token, expires_in } = await response.json()

Portées requises

https://api.ebay.com/oauth/api_scope/sell.inventory - Gestion des stocks
https://api.ebay.com/oauth/api_scope/sell.listings - Annonces
https://api.ebay.com/oauth/api_scope/sell.orders - Commandes
https://api.ebay.com/oauth/api_scope/sell.fulfillment - Exécution (Fulfillment)
https://api.ebay.com/oauth/api_scope/sell.account - Gestion de compte

Gestion des stocks

L'inventaire représente les produits que vous vendez.

Créer un lieu d'inventaire

curl -X POST "https://api.ebay.com/sell/inventory/v1/location_inventory_location" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "locationId": "WAREHOUSE_1",
    "name": "Main Warehouse",
    "address": {
      "addressLine1": "123 Main St",
      "city": "San Jose",
      "stateOrProvince": "CA",
      "postalCode": "95101",
      "countryCode": "US"
    }
  }'

Créer un article d'inventaire

curl -X POST "https://api.ebay.com/sell/inventory/v1/inventory_item" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product": {
      "title": "Vintage Leather Messenger Bag",
      "description": "Genuine leather messenger bag, perfect for work or school.",
      "aspects": {
        "Brand": ["Vintage"],
        "Material": ["Leather"],
        "Color": ["Brown"]
      },
      "imageUrls": [
        "https://example.com/images/bag1.jpg",
        "https://example.com/images/bag2.jpg"
      ]
    },
    "condition": "USED_GOOD",
    "conditionNotes": "Minor wear on corners",
    "availability": {
      "shipToLocationAvailability": {
        "quantity": 25
      }
    }
  }'

Mettre à jour l'inventaire

curl -X PUT "https://api.ebay.com/sell/inventory/v1/inventory_item/SKU123" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "availability": {
      "shipToLocationAvailability": {
        "quantity": 30
      }
    }
  }'

Obtenir un article d'inventaire

curl -X GET "https://api.ebay.com/sell/inventory/v1/inventory_item/SKU123" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Mettre des articles en vente

Créer une offre

curl -X POST "https://api.ebay.com/sell/inventory/v1/offer" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "SKU123",
    "marketplaceId": "EBAY_US",
    "format": "FIXED_PRICE",
    "product": {
      "title": "Vintage Leather Messenger Bag"
    },
    "pricingSummary": {
      "price": {
        "currency": "USD",
        "value": "89.99"
      }
    },
    "listing": {
      "listingDuration": "GTC",
      "listingType": "CLASSIC"
    },
    " fulfillment": {
      "shippingProfileId": "SHIPPING_PROFILE_ID",
      " fulfillmentPolicyId": "FULFILLMENT_POLICY_ID",
      "paymentPolicyId": "PAYMENT_POLICY_ID"
    }
  }'

Champs clés :

sku - Votre UGS d'inventaire
marketplaceId - EBAY_US, EBAY_UK, EBAY_DE, etc.
format - FIXED_PRICE ou AUCTION
listingDuration - Durée (GTC = bon jusqu'à annulation)
price - Votre prix demandé

Publier l'offre

curl -X POST "https://api.ebay.com/sell/inventory/v1/offer/OFFER_ID/publish" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Retirer une annonce

curl -X POST "https://api.ebay.com/sell/inventory/v1/offer/OFFER_ID/withdraw" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Gestion des commandes

Obtenir les commandes

curl -X GET "https://api.ebay.com/sell/fulfillment/v1/order?orderIds=ORDER_ID_1,ORDER_ID_2" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Filtrer par date :

curl -X GET "https://api.ebay.com/sell/fulfillment/v1/order?filter=creation_date_range:from:2026-01-01T00:00:00Z,to:2026-03-24T00:00:00Z" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Obtenir les détails de la commande

curl -X GET "https://api.ebay.com/sell/fulfillment/v1/order/ORDER_ID" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Réponse de la commande :

{
  "orderId": "12-34567-89012",
  "orderPaymentStatus": "PAID",
  "pricingSummary": {
    "total": {
      "currency": "USD",
      "value": "94.99"
    }
  },
  "fulfillmentStartInstructions": [
    {
      "shippingStep": {
        "shipTo": {
          "fullName": "John Doe",
          "contactAddress": {
            "addressLine1": "123 Main St",
            "city": "Anytown",
            "stateOrProvince": "CA",
            "postalCode": "12345",
            "countryCode": "US"
          }
        }
      }
    }
  ],
  "lineItems": [
    {
      "lineItemId": "LINE_ITEM_ID",
      "sku": "SKU123",
      "quantity": 1,
      "title": "Vintage Leather Messenger Bag",
      "lineItemCost": {
        "currency": "USD",
        "value": "89.99"
      }
    }
  ]
}

Expédition et exécution (Fulfillment)

Créer une étiquette d'expédition

curl -X POST "https://api.ebay.com/sell/fulfillment/v1/order/ORDER_ID/shipping_fulfillment" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "lineItems": [
      {
        "lineItemId": "LINE_ITEM_ID",
        "quantity": 1
      }
    ],
    "shippingStep": {
      "shipFrom": {
        "fullName": "Your Name",
        "companyName": "Your Company",
        "contactAddress": {
          "addressLine1": "456 Warehouse Rd",
          "city": "San Jose",
          "stateOrProvince": "CA",
          "postalCode": "95101",
          "countryCode": "US"
        }
      }
    },
    "shippingCarrierCode": "USPS",
    "shippingMethodCode": "PRIORITY_MAIL",
    "trackingNumber": "9400111899223056789012"
  }'

Transporteurs :

USPS
UPS
FedEx
DHL

Gestion des retours

Obtenir les détails du retour

curl -X GET "https://api.ebay.com/sell/fulfillment/v1/return/RETURN_ID" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Traiter un retour

curl -X POST "https://api.ebay.com/sell/fulfillment/v1/return/RETURN_ID/decide" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "ACCEPT",
    "shipment": {
      "carrierId": "CARRIER_ID",
      "trackingNumber": "TRACKING_NUMBER"
    }
  }'

Limites de débit et gestion

eBay limite les appels API pour prévenir les abus. Vérifiez les en-têtes :

X-RateLimit-Limit - Nombre maximal de requêtes autorisées
X-RateLimit-Remaining - Requêtes restantes dans la fenêtre
X-RateLimit-Reset - Horodatage Unix lorsque la limite est réinitialisée

async function makeEbayRequest(url, options, retries = 3) {
  for (let i = 0; i < retries; i++) {
    const response = await fetch(url, options)
    
    const remaining = response.headers.get('X-RateLimit-Remaining')
    if (remaining && parseInt(remaining) < 10) {
      console.warn('Rate limit low:', remaining)
    }
    
    if (response.status === 429) {
      const resetTime = response.headers.get('X-RateLimit-Reset')
      const waitTime = (parseInt(resetTime) - Date.now() / 1000) * 1000
      await sleep(waitTime)
      continue
    }
    
    return response
  }
  throw new Error('Rate limited')
}

Tester avec Apidog

Les API eBay sont critiques pour la production. Testez minutieusement avant d'apporter des modifications en direct.

1. Configuration de l'environnement

EBAY_APP_ID: your_app_id
EBAY_CERT_ID: your_cert_id
EBAY_ACCESS_TOKEN: stored_token
EBAY_REFRESH_TOKEN: stored_refresh
EBAY_MARKETPLACE_ID: EBAY_US
BASE_URL: https://api.ebay.com

2. Valider les charges utiles des annonces

pm.test('Listing has required fields', () => {
  const requestBody = JSON.parse(pm.request.body.raw)
  pm.expect(requestBody).to.have.property('sku')
  pm.expect(requestBody).to.have.property('marketplaceId')
  pm.expect(requestBody.pricingSummary).to.have.property('price')
})

pm.test('Price is valid', () => {
  const requestBody = JSON.parse(pm.request.body.raw)
  const price = parseFloat(requestBody.pricingSummary.price.value)
  pm.expect(price).to.be.above(0)
})

3. Tester le traitement des commandes

pm.test('Order response is valid', () => {
  const response = pm.response.json()
  pm.expect(response).to.have.property('orderId')
  pm.expect(response.orderPaymentStatus).to.eql('PAID')
  pm.expect(response.lineItems).to.be.an('array')
})

Testez les API eBay avec Apidog - gratuit

Erreurs courantes et correctifs

401 Non autorisé

Cause : Jeton expiré ou invalide.

Correction : Utilisez le jeton de rafraîchissement pour obtenir un nouveau jeton d'accès :

const response = await fetch('https://api.ebay.com/identity/v1/oauth2/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'Authorization': 'Basic ' + Buffer.from(APP_ID + ':' + CERT_ID).toString('base64')
  },
  body: new URLSearchParams({
    grant_type: 'refresh_token',
    refresh_token: storedRefreshToken
  })
})

10002 : Erreur API - Jeton d'accès invalide

Cause : Jeton d'accès expiré.

Correction : Rafraîchissez le jeton immédiatement.

21916684 : L'article n'existe pas

Cause : Tentative de mise à jour d'une UGS qui n'a pas été créée.

Correction : Créez d'abord l'article d'inventaire, puis créez l'offre.

10003 : UGS invalide

Cause : Format de l'UGS invalide.

Correction : Les UGS doivent être uniques dans votre inventaire et ne peuvent contenir que des caractères alphanumériques, des tirets et des underscores.

Limite de débit (429)

Cause : Trop de requêtes.

Correction : Mettez en œuvre un mécanisme de temporisation (backoff). Les limites d'eBay varient selon l'API et le point de terminaison.

Alternatives et comparaisons

Fonctionnalité	eBay	Amazon SP-API	Etsy
API d'inventaire	✓	✓	Limité
API d'annonces	✓	✓	✓
API de commande	✓	✓	✓
API d'exécution (Fulfillment)	✓	✓	Limité
Niveau gratuit	Programme développeur	Limité	Limité
Complexité API	Moyenne	Élevée	Faible

L'API d'eBay est plus accessible que celle d'Amazon mais moins riche en fonctionnalités. Etsy est la plus simple mais limitée pour les grands vendeurs.

Cas d'utilisation réels

Vente multicanal. Un vendeur publie des annonces sur eBay, Amazon et son propre site. L'inventaire est synchronisé sur toutes les plateformes. Lorsqu'un article est vendu sur un canal, la quantité est décrémentée partout.

Repricing automatisé. Un vendeur surveille ses concurrents et ajuste les prix via l'API. Lorsqu'un concurrent baisse ses prix, les prix du vendeur s'ajustent automatiquement pour rester compétitif.

Annonces en masse. Un vendeur avec 10 000 articles crée des annonces en masse. L'API accepte les téléchargements CSV, créant des milliers d'annonces automatiquement.

Conclusion

Voici ce que vous avez appris :

Vous authentifier avec OAuth 2.0 en utilisant les identifiants de l'application
Gérer l'inventaire avec les UGS
Créer et publier des annonces
Traiter les commandes et les expéditions
Gérer les retours
Tester avec Apidog avant de passer en production

Vos prochaines étapes :

Postuler au programme eBay Developers
Créer une application et obtenir les identifiants
Mettre en œuvre le flux OAuth
Créer votre premier article d'inventaire
Publier une annonce test

Testez les API eBay avec Apidog - gratuit

bouton

FAQ

Ai-je besoin d'un compte professionnel pour utiliser les API ?Oui. Les API eBay sont destinées aux vendeurs vérifiés. Inscrivez-vous pour un compte vendeur et complétez la vérification.

Quelle est la différence entre l'inventaire et les offres ?L'inventaire stocke les informations sur les produits (titre, description, images). Les offres lient l'inventaire à une place de marché avec des informations sur les prix et l'exécution. Plusieurs offres peuvent faire référence au même inventaire.

Combien de temps les annonces restent-elles actives ?Les annonces avec GTC (bon jusqu'à annulation) restent actives jusqu'à ce que vous les retiriez ou que l'article soit épuisé.

Puis-je vendre à l'international via l'API ?Oui. Définissez marketplaceId sur différentes valeurs (EBAY_US, EBAY_UK, EBAY_DE, etc.). Vous devrez vous conformer aux exigences de chaque place de marché.

Quelle est la limite de débit de l'API ?Les limites varient selon le point de terminaison et votre niveau de compte. Vérifiez les en-têtes de réponse pour connaître vos limites actuelles.

Comment obtenir des étiquettes d'expédition ?eBay fournit des étiquettes d'expédition à prix réduit via l'API Fulfillment. Vous créez l'expédition et eBay génère une étiquette.