Forem

Cover image for ¿Cómo Usar las APIs de eBay?
Roobia
Roobia

Posted on • Originally published at apidog.com

¿Cómo Usar las APIs de eBay?

TL;DR

Las API de eBay permiten gestionar inventario, listados, pedidos y pagos en el marketplace más grande del mundo. La autenticación es vía OAuth 2.0, los endpoints principales son api.ebay.com/sell y los límites de tasa deben manejarse cuidadosamente. Para pruebas, utiliza Apidog para validar cargas útiles de listados, simular pedidos y asegurar que tu integración maneje correctamente los límites de la API.

Prueba Apidog hoy

Introducción

eBay conecta a compradores y vendedores globalmente. Su API permite a los vendedores automatizar la gestión de inventario, crear listados en masa, procesar pedidos, gestionar envíos y manejar devoluciones. Es escalable tanto para pequeños vendedores como para empresas.

Áreas clave de la API:

  • API de Inventario – Gestiona el inventario de productos
  • API de Listado – Crea y gestiona listados de artículos
  • API de Pedidos – Procesa pedidos y envíos
  • API de Cumplimiento – Gestiona envíos y seguimiento
  • API de Análisis – Extrae informes de ventas

💡 Si desarrollas integraciones con eBay, Apidog te ayuda a probar la creación de listados, validar respuestas de pedidos y asegurar un manejo correcto de límites de tasa y errores.

Prueba las API de eBay con Apidog - gratis.

Al finalizar esta guía podrás:

  • Autenticación con eBay OAuth 2.0
  • Crear y gestionar inventario
  • Publicar listados
  • Procesar pedidos y envíos
  • Manejar devoluciones y reembolsos
  • Probar flujos con Apidog

Autenticación con OAuth 2.0

eBay usa OAuth 2.0 para acceder a la API. Debes crear una aplicación en el Programa de Desarrolladores de eBay.

Crear una aplicación de eBay

Crear una aplicación

  1. Accede a developers.ebay.com
  2. Regístrate para obtener una cuenta de desarrollador.
  3. Crea una aplicación en la Consola de Desarrolladores.
  4. Obtén tu App ID (ID de cliente) y Cert ID (secreto de cliente).

Flujo de OAuth

Paso 1: Autorización del usuario

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
Enter fullscreen mode Exit fullscreen mode

Paso 2: Obtener código de autorización

El usuario autoriza, y recibes un código en tu URI de redirección.

Paso 3: Intercambiar código por tokens

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()
Enter fullscreen mode Exit fullscreen mode

Ámbitos requeridos

  • https://api.ebay.com/oauth/api_scope/sell.inventory – Inventario
  • https://api.ebay.com/oauth/api_scope/sell.listings – Listados
  • https://api.ebay.com/oauth/api_scope/sell.orders – Pedidos
  • https://api.ebay.com/oauth/api_scope/sell.fulfillment – Cumplimiento
  • https://api.ebay.com/oauth/api_scope/sell.account – Cuenta

Gestión de inventario

El inventario representa tus productos a la venta.

Crear ubicación de inventario 

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"
    }
  }'
Enter fullscreen mode Exit fullscreen mode

Crear un artículo de inventario 

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
      }
    }
  }'
Enter fullscreen mode Exit fullscreen mode

Actualizar inventario 

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
      }
    }
  }'
Enter fullscreen mode Exit fullscreen mode

Obtener artículo de inventario 

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

Listado de artículos

Crear una oferta 

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"
    }
  }'
Enter fullscreen mode Exit fullscreen mode

Campos clave:

  • sku: tu SKU de inventario
  • marketplaceId: EBAY_US, EBAY_UK, EBAY_DE, etc.
  • format: FIXED_PRICE o AUCTION
  • listingDuration: "GTC" (good til canceled)
  • price: precio de venta

Publicar la oferta 

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

Retirar un listado 

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

Gestión de pedidos

Obtener pedidos 

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

Filtrar por fecha:

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"
Enter fullscreen mode Exit fullscreen mode

Obtener detalles del pedido 

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

Respuesta de ejemplo:

{
  "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"
      }
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Envío y cumplimiento

Crear etiqueta de envío 

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"
  }'
Enter fullscreen mode Exit fullscreen mode

Transportistas soportados: USPS, UPS, FedEx, DHL

Gestión de devoluciones

Obtener detalles de devolución 

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

Procesar una devolución 

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"
    }
  }'
Enter fullscreen mode Exit fullscreen mode

Límites de tasa y manejo

eBay limita la cantidad de llamadas a la API para evitar abusos. Verifica los siguientes encabezados:

  • X-RateLimit-Limit: máximo de solicitudes permitidas
  • X-RateLimit-Remaining: solicitudes restantes
  • X-RateLimit-Reset: timestamp Unix de reinicio

Implementa manejo de límites:

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')
}
Enter fullscreen mode Exit fullscreen mode

Pruebas con Apidog

Las API de eBay son críticas en producción. Realiza pruebas exhaustivas antes de cambios reales.

Pruebas con Apidog para eBay

1. Configuración del entorno 

EBAY_APP_ID: tu_id_de_aplicacion
EBAY_CERT_ID: tu_id_de_certificado
EBAY_ACCESS_TOKEN: token_almacenado
EBAY_REFRESH_TOKEN: refresh_almacenado
EBAY_MARKETPLACE_ID: EBAY_US
BASE_URL: https://api.ebay.com
Enter fullscreen mode Exit fullscreen mode

2. Validar las cargas útiles de los listados 

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)
})
Enter fullscreen mode Exit fullscreen mode

3. Probar el procesamiento de pedidos 

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')
})
Enter fullscreen mode Exit fullscreen mode

Prueba las API de eBay con Apidog - gratis.

Errores comunes y soluciones

401 No autorizado

Causa: Token caducado o inválido.

Solución: Usa el refresh token para obtener un nuevo access token:

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
  })
})
Enter fullscreen mode Exit fullscreen mode

10002: Error de API - Token de acceso no válido

Causa: Token caducado.

Solución: Actualiza el token inmediatamente.

21916684: El artículo no existe

Causa: Intentas actualizar un SKU no creado.

Solución: Crea primero el artículo de inventario, luego la oferta.

10003: SKU no válido

Causa: Formato de SKU incorrecto.

Solución: Usa SKUs únicos, solo con caracteres alfanuméricos, guiones y guiones bajos.

Límite de tasa (429)

Causa: Exceso de solicitudes.

Solución: Implementa retroceso exponencial. Los límites varían por endpoint y nivel de cuenta.

Alternativas y comparaciones

Característica eBay Amazon SP-API Etsy
API de Inventario ✓ ✓ Limitada
API de Listado ✓ ✓ ✓
API de Pedidos ✓ ✓ ✓
API de Cumplimiento ✓ ✓ Limitada
Nivel gratuito Programa de desarrolladores Limitado Limitado
Complejidad de la API Media Alta Baja

La API de eBay es más accesible que la de Amazon, pero con menos funciones. Etsy es la más simple pero limitada para vendedores grandes.

Casos de uso en el mundo real

  • Venta multicanal: Sincroniza inventario entre eBay, Amazon y tu propio sitio. Cuando se vende en un canal, la cantidad se ajusta en todos.
  • Reajuste automático de precios: Monitoriza la competencia y ajusta precios vía API automáticamente.
  • Listado masivo: Carga y crea miles de listados automáticamente usando archivos CSV y la API.

Conclusión

Has aprendido a:

  • Autenticación con OAuth 2.0 usando credenciales
  • Gestionar inventario con SKUs
  • Crear y publicar listados
  • Procesar pedidos y envíos
  • Manejar devoluciones
  • Probar todo con Apidog antes de pasar a producción

Próximos pasos:

  1. Solicita acceso al Programa de Desarrolladores de eBay
  2. Crea una aplicación y obtén credenciales
  3. Implementa el flujo OAuth
  4. Crea tu primer artículo de inventario
  5. Publica un listado de prueba

Prueba las API de eBay con Apidog - gratis.

Preguntas frecuentes

¿Necesito una cuenta comercial para usar las API?

Sí. Las API de eBay son para vendedores verificados. Regístrate como vendedor y completa la verificación.

¿Diferencia entre inventario y ofertas?

El inventario almacena datos del producto. Las ofertas vinculan inventario a un marketplace con precios y políticas. Una oferta apunta a un inventario.

¿Cuánto tiempo permanecen activos los listados?

Los listados GTC (good til canceled) permanecen activos hasta que los retiras o el artículo se agota.

¿Puedo vender internacionalmente vía API?

Sí. Cambia marketplaceId (EBAY_US, EBAY_UK, EBAY_DE, etc.). Cumple los requisitos de cada mercado.

¿Cuál es el límite de tasa de la API?

Varía según endpoint y cuenta. Consulta los encabezados de respuesta.

¿Cómo obtengo etiquetas de envío?

eBay genera etiquetas de envío con descuento vía la API de Cumplimiento. Crea el envío y eBay provee la etiqueta.

Top comments (0)