Como Usar APIs do eBay: Guia Completo

TL;DR

As APIs do eBay permitem que você gerencie estoque, anúncios, pedidos e pagamentos no maior marketplace do mundo. Você se autentica com OAuth 2.0, chama os endpoints api.ebay.com/sell e gerencia os limites de taxa com cuidado. Para testes, use o Apidog para validar cargas de listagem, testar o processamento de pedidos e garantir que sua integração lida com os limites da API de forma graciosa.

Introdução

O eBay conecta compradores e vendedores globalmente. A API permite que os vendedores automatizem o gerenciamento de estoque, criem anúncios em massa, processem pedidos, lidem com o envio e gerenciem devoluções. Seja você um pequeno vendedor ou uma empresa, a API escala.

As principais áreas da API:

Inventory API - Gerenciar estoque de produtos
Listing API - Criar e gerenciar anúncios de itens
Order API - Processar pedidos e envios
Fulfillment API - Lidar com envio e rastreamento
Analytics API - Puxar relatórios de vendas

💡

Se você está construindo integrações com o eBay, o Apidog ajuda a testar a criação de listagens, validar respostas de pedidos e garantir que sua integração lida com limites de taxa e erros corretamente.

button

Teste as APIs do eBay com Apidog - grátis

Ao final deste guia, você será capaz de:

Autenticar-se com eBay OAuth 2.0
Criar e gerenciar estoque
Publicar anúncios
Processar pedidos e envios
Lidar com devoluções e reembolsos
Testar com Apidog

Autenticação com OAuth 2.0

O eBay usa OAuth 2.0 para autenticação de API. Você precisará criar um aplicativo no Programa de Desenvolvedores do eBay.

Captura de tela de onde encontrar as credenciais do aplicativo no Centro de Desenvolvedores do eBay.

Criar um aplicativo

Vá para developers.ebay.com
Cadastre-se para uma conta de desenvolvedor
Crie um aplicativo no Developer Console
Obtenha seu App ID (ID do cliente) e Cert ID (segredo do cliente)

Fluxo OAuth

Passo 1: Autorização do usuário

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

Passo 2: Obter código de autorização

O usuário autoriza, você obtém um código em sua URI de redirecionamento.

Passo 3: Trocar 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()

Escopos necessários

https://api.ebay.com/oauth/api_scope/sell.inventory - Gerenciamento de estoque
https://api.ebay.com/oauth/api_scope/sell.listings - Anúncios
https://api.ebay.com/oauth/api_scope/sell.orders - Pedidos
https://api.ebay.com/oauth/api_scope/sell.fulfillment - Cumprimento de pedidos
https://api.ebay.com/oauth/api_scope/sell.account - Gerenciamento de conta

Gerenciamento de estoque

Estoque representa os produtos que você vende.

Criar local de estoque

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

Criar um item de estoque

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

Atualizar estoque

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

Obter item de estoque

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

Anunciando itens

Criar uma 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 chave:

sku - Seu SKU de estoque
marketplaceId - EBAY_US, EBAY_UK, EBAY_DE, etc.
format - FIXED_PRICE ou AUCTION
listingDuration - Duração (GTC = bom até cancelar)
price - Seu preço de venda

Publicar a oferta

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

Retirar um anúncio

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

Gerenciamento de pedidos

Obter 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 data:

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"

Obter detalhes do pedido

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

Resposta do 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"
      }
    }
  ]
}

Envio e cumprimento de pedidos

Criar etiqueta de envio

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

Transportadoras:

USPS
UPS
FedEx
DHL

Gerenciamento de devoluções

Obter detalhes da devolução

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

Processar uma devolução

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 taxa e tratamento

O eBay limita as chamadas de API para evitar abusos. Verifique os cabeçalhos:

X-RateLimit-Limit - Máximo de requisições permitidas
X-RateLimit-Remaining - Requisições restantes na janela
X-RateLimit-Reset - Timestamp Unix quando o limite é redefinido

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

Testando com Apidog

As APIs do eBay são críticas para a produção. Teste minuciosamente antes de fazer alterações ao vivo.

Captura de tela do Apidog mostrando um ambiente de teste de API do eBay configurado.

1. Configuração do ambiente

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. Validar cargas de listagem

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. Testar processamento 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')
})

Teste as APIs do eBay com Apidog - grátis

Erros comuns e correções

401 Não autorizado

Causa: Token expirado ou inválido.

Correção: Use o token de atualização para obter um novo token de acesso:

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: Erro da API - Token de acesso inválido

Causa: Token de acesso expirado.

Correção: Atualize o token imediatamente.

21916684: Item não existe

Causa: Tentando atualizar um SKU que não foi criado.

Correção: Crie o item de estoque primeiro e depois crie a oferta.

10003: SKU inválido

Causa: Formato do SKU inválido.

Correção: SKUs devem ser únicos em seu estoque e podem conter apenas caracteres alfanuméricos, hífens e sublinhados.

Limite de taxa (429)

Causa: Muitas requisições.

Correção: Implemente um backoff. Os limites do eBay variam por API e endpoint.

Alternativas e comparações

Característica	eBay	Amazon SP-API	Etsy
API de Estoque	✓	✓	Limitado
API de Anúncios	✓	✓	✓
API de Pedidos	✓	✓	✓
API de Cumprimento	✓	✓	Limitado
Nível gratuito	Programa de Desenvolvedores	Limitado	Limitado
Complexidade da API	Média	Alta	Baixa

A API do eBay é mais acessível que a da Amazon, mas menos rica em recursos. A Etsy é a mais simples, mas limitada para grandes vendedores.

Casos de uso no mundo real

Venda multi-canal. Um vendedor anuncia no eBay, Amazon e em seu próprio site. O estoque é sincronizado entre as plataformas. Quando vendido em um canal, a quantidade diminui em todos os lugares.

Reprecificação automatizada. Um vendedor monitora concorrentes e ajusta os preços via API. Quando um concorrente baixa os preços, os preços do vendedor ajustam-se automaticamente para manter a competitividade.

Listagem em massa. Um vendedor com 10.000 itens cria anúncios em massa. A API aceita uploads de CSV, criando milhares de anúncios automaticamente.

Conclusão

Aqui está o que você aprendeu:

Autenticar com OAuth 2.0 usando credenciais de aplicativo
Gerenciar estoque com SKUs
Criar e publicar anúncios
Processar pedidos e envios
Lidar com devoluções
Testar com Apidog antes de entrar em produção

Seus próximos passos:

Inscreva-se no Programa de Desenvolvedores do eBay
Crie um aplicativo e obtenha credenciais
Implemente o fluxo OAuth
Crie seu primeiro item de estoque
Publique um anúncio de teste

Teste as APIs do eBay com Apidog - grátis

button

FAQ

Preciso de uma conta comercial para usar APIs?Sim. As APIs do eBay são para vendedores verificados. Cadastre-se para uma conta de vendedor e complete a verificação.

Qual a diferença entre estoque e ofertas?Estoque armazena informações do produto (título, descrição, imagens). Ofertas vinculam o estoque a um marketplace com informações de preço e cumprimento. Múltiplas ofertas podem referenciar o mesmo estoque.

Por quanto tempo os anúncios permanecem ativos?Anúncios com GTC (bom até cancelar) permanecem ativos até que você os retire ou o item se esgote.

Posso vender internacionalmente via API?Sim. Defina o marketplaceId para diferentes valores (EBAY_US, EBAY_UK, EBAY_DE, etc.). Você precisará cumprir os requisitos de cada marketplace.

Qual é o limite de taxa da API?Os limites variam por endpoint e seu nível de conta. Verifique os cabeçalhos de resposta para seus limites atuais.

Como consigo etiquetas de envio?O eBay fornece etiquetas de envio com desconto através da API de Cumprimento. Você cria o envio e o eBay gera uma etiqueta.