¿Cómo Usar las APIs de eBay?

TL;DR

Las API de eBay te permiten gestionar inventario, listados, pedidos y pagos en el mercado más grande del mundo. Te autenticas con OAuth 2.0, llamas a los endpoints de api.ebay.com/sell y manejas los límites de tasa con cuidado. Para las pruebas, usa Apidog para validar las cargas útiles de los listados, probar el procesamiento de pedidos y asegurar que tu integración maneje los límites de la API de manera adecuada.

Introducción

eBay conecta a compradores y vendedores a nivel mundial. La API permite a los vendedores automatizar la gestión de inventario, crear listados en masa, procesar pedidos, gestionar envíos y manejar devoluciones. Ya seas un pequeño vendedor o una empresa, la API se escala.

Las principales áreas de la API:

API de Inventario - Gestiona el inventario de productos
API de Listado - Crea y gestiona los 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 estás desarrollando integraciones con eBay, Apidog te ayuda a probar la creación de listados, validar las respuestas de los pedidos y asegurar que tu integración maneje correctamente los límites de tasa y los errores.

botón

Prueba las API de eBay con Apidog - gratis

Al final de esta guía, podrás:

Autenticarte con eBay OAuth 2.0
Crear y gestionar inventario
Publicar listados
Procesar pedidos y envíos
Manejar devoluciones y reembolsos
Probar con Apidog

Autenticación con OAuth 2.0

eBay utiliza OAuth 2.0 para la autenticación de la API. Deberás crear una aplicación en el Programa de Desarrolladores de eBay.

Crear una aplicación

Ve a developers.ebay.com
Regístrate para obtener una cuenta de desarrollador
Crea una aplicación en la Consola de Desarrolladores
Obtén tu ID de Aplicación (ID de cliente) y ID de Certificado (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

Paso 2: Obtener código de autorización

El usuario autoriza, obtienes un código en tu URI de redireccionamiento.

Paso 3: Intercambiar 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()

Ámbitos requeridos

https://api.ebay.com/oauth/api_scope/sell.inventory - Gestión de 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 - Gestión de cuenta

Gestión de inventario

El inventario representa los productos que vendes.

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"
    }
  }'

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
      }
    }
  }'

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
      }
    }
  }'

Obtener artículo de inventario

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

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"
    }
  }'

Campos clave:

sku - Tu SKU de inventario
marketplaceId - EBAY_US, EBAY_UK, EBAY_DE, etc.
format - FIXED_PRICE o AUCTION
listingDuration - Cuánto tiempo (GTC = good til canceled / válido hasta la cancelación)
price - Tu 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"

Retirar un listado

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

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"

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"

Obtener detalles del pedido

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

Respuesta del pedido:

{
  "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"
      }
    }
  ]
}

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"
  }'

Transportistas:

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"

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"
    }
  }'

Límites de tasa y manejo

eBay limita las llamadas a la API para evitar abusos. Comprueba los encabezados:

X-RateLimit-Limit - Máximo de solicitudes permitidas
X-RateLimit-Remaining - Solicitudes restantes en la ventana
X-RateLimit-Reset - Marca de tiempo Unix cuando se restablece el límite

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')
}

Pruebas con Apidog

Las API de eBay son críticas para la producción. Realiza pruebas exhaustivas antes de realizar cambios en vivo.

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

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)
})

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')
})

Prueba las API de eBay con Apidog - gratis

Errores comunes y soluciones

401 No autorizado

Causa: Token caducado o no válido.

Solución: Utiliza el token de actualización para obtener un nuevo token de acceso:

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: Error de API - Token de acceso no válido

Causa: Token de acceso caducado.

Solución: Actualiza el token inmediatamente.

21916684: El artículo no existe

Causa: Intentando actualizar un SKU que no fue creado.

Solución: Primero crea el artículo de inventario, luego crea la oferta.

10003: SKU no válido

Causa: Formato de SKU no válido.

Solución: Los SKUs deben ser únicos dentro de tu inventario y solo pueden contener caracteres alfanuméricos, guiones y guiones bajos.

Límite de tasa (429)

Causa: Demasiadas solicitudes.

Solución: Implementa un retroceso exponencial. Los límites de eBay varían según la API y el endpoint.

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. Un vendedor lista en eBay, Amazon y su propio sitio. El inventario se sincroniza en todas las plataformas. Cuando se vende en un canal, la cantidad disminuye en todas partes.

Reajuste automático de precios. Un vendedor monitorea a la competencia y ajusta los precios a través de la API. Cuando un competidor baja los precios, los precios del vendedor se ajustan automáticamente para seguir siendo competitivos.

Listado masivo. Un vendedor con 10,000 artículos crea listados en masa. La API acepta cargas de CSV, creando miles de listados automáticamente.

Conclusión

Esto es lo que has aprendido:

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

Tus próximos pasos:

Solicitar el Programa de Desarrolladores de eBay
Crear una aplicación y obtener credenciales
Implementar el flujo de OAuth
Crear tu primer artículo de inventario
Publicar un listado de prueba

Prueba las API de eBay con Apidog - gratis

botón

Preguntas frecuentes

¿Necesito una cuenta comercial para usar las API?Sí. Las API de eBay son para vendedores verificados. Regístrate para obtener una cuenta de vendedor y completa la verificación.

¿Cuál es la diferencia entre inventario y ofertas?El inventario almacena información del producto (título, descripción, imágenes). Las ofertas vinculan el inventario a un mercado con información de precios y cumplimiento. Múltiples ofertas pueden hacer referencia al mismo inventario.

¿Cuánto tiempo permanecen activos los listados?Los listados con GTC (good til canceled / válido hasta la cancelación) permanecen activos hasta que los retiras o el artículo se agota.

¿Puedo vender internacionalmente a través de la API?Sí. Establece marketplaceId con diferentes valores (EBAY_US, EBAY_UK, EBAY_DE, etc.). Deberás cumplir con los requisitos de cada mercado.

¿Cuál es el límite de tasa de la API?Los límites varían según el endpoint y el nivel de tu cuenta. Consulta los encabezados de respuesta para conocer tus límites actuales.

¿Cómo obtengo etiquetas de envío?eBay proporciona etiquetas de envío con descuento a través de la API de Cumplimiento. Tú creas el envío y eBay genera una etiqueta.