Cómo Usar APIs de BigCommerce: Guía para Desarrolladores en Integración E-commerce

En resumen

Las APIs de BigCommerce te permiten gestionar productos, pedidos, clientes y operaciones de la tienda de forma programática. Te autenticas con tokens de API (para el lado del servidor) o OAuth (para aplicaciones), llamas a los endpoints REST en `api.bigcommerce.com` y gestionas webhooks para actualizaciones en tiempo real. Para probar, usa Apidog para guardar tus llamadas a la API, validar respuestas y compartir colecciones con tu equipo.

Introducción

BigCommerce impulsa más de 60,000 tiendas online. Cada una necesita integraciones personalizadas: sincronización de inventario, procesamiento de pedidos, gestión de clientes, manejo de pagos. Ahí es donde entran las APIs.

La plataforma ofrece tres tipos de API: Storefront API (comercio sin interfaz), Management API (operaciones de backend) y Payments API (transacciones). La mayoría de los desarrolladores trabajan con la Management API. Esta gestiona productos, pedidos, clientes y todo lo que sucede detrás de escena.

La curva de aprendizaje no es pronunciada, pero la documentación puede parecer abrumadora. Te encontrarás saltando entre documentos de autenticación, referencias de API y guías de webhooks solo para completar una tarea sencilla.

Esta guía se centra en lo que realmente utilizarás: productos, pedidos, clientes y webhooks. Aprenderás sobre autenticación, patrones comunes y cómo probar tus integraciones antes de que lleguen a una tienda en vivo.

💡

Si estás construyendo integraciones de BigCommerce, Apidog te ayuda a diseñar, probar y documentar esas llamadas a la API. Guarda solicitudes como colecciones, usa variables de entorno para diferentes tiendas y valida que las respuestas coincidan con los esquemas esperados. Detecta errores antes de que afecten a clientes reales.

botón

Prueba tus APIs de BigCommerce con Apidog - gratis

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

Configurar la autenticación de BigCommerce correctamente
Gestionar productos, variantes e inventario
Procesar pedidos y manejar datos de clientes
Configurar webhooks para actualizaciones en tiempo real
Probar y documentar tus integraciones con Apidog

Autenticación: obteniendo acceso a tu tienda

BigCommerce ofrece dos métodos de autenticación según lo que estés construyendo.

Método 1: Tokens de API (para integraciones personalizadas)

Si estás construyendo un script o servicio que funciona con una tienda, usa tokens de API.

Crear una cuenta de API:

Ve al panel de administración de tu tienda
Configuración → Cuentas de API → Crear cuenta de API
Elige "V3/V2 API Token"
Selecciona los scopes que necesites (Productos, Pedidos, Clientes, etc.)
Guarda las credenciales

Obtendrás:

URL de la tienda: mystore.mybigcommerce.com
Token de acceso: abc123def456...
ID de cliente: abc123...
Secreto de cliente: xyz789...

Realiza tu primera llamada:

curl -X GET "https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products" \
  -H "X-Auth-Token: {access-token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"

El store-hash es la parte después de /stores/ en tu ruta de API. También es visible en la URL de administración de tu tienda.

Método 2: OAuth (para aplicaciones de marketplace)

Si estás construyendo una aplicación para el marketplace de BigCommerce, usa OAuth.

El flujo de OAuth:

El usuario hace clic en "Instalar" en tu aplicación en el marketplace
BigCommerce redirige a tu URL de callback con un código de autenticación
Tu servidor intercambia el código por un token de acceso
Almacena el token para futuras llamadas a la API

Intercambiar código por token:

const response = await fetch('https://login.bigcommerce.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    client_id: process.env.BC_CLIENT_ID,
    client_secret: process.env.BC_CLIENT_SECRET,
    redirect_uri: 'https://yourapp.com/auth/callback',
    grant_type: 'authorization_code',
    code: authCode,
    scope: 'store_v2_default store_v3_products'
  })
})

const { access_token, context } = await response.json()
// access_token es lo que usas para las llamadas a la API
// context contiene el hash de la tienda

Usa el token:

curl -X GET "https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products" \
  -H "X-Auth-Token: {access-token}" \
  -H "Content-Type: application/json"

Gestión de productos y catálogo

Los productos son el corazón de cualquier tienda BigCommerce. La API de Catálogo V3 gestiona productos, variantes, categorías y marcas.

Listar productos

GET https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products
X-Auth-Token: {token}
Accept: application/json

Respuesta:

{
  "data": [
    {
      "id": 174,
      "name": "Plain T-Shirt",
      "type": "physical",
      "sku": "PLAIN-T",
      "price": 29.99,
      "sale_price": 24.99,
      "inventory_level": 150,
      "inventory_tracking": "product",
      "is_visible": true,
      "categories": [23, 45],
      "brand_id": 12
    }
  ],
  "meta": {
    "pagination": {
      "total": 500,
      "count": 50,
      "page": 1,
      "per_page": 50
    }
  }
}

Crear un producto

POST https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products
X-Auth-Token: {token}
Content-Type: application/json

{
  "name": "Premium Hoodie",
  "type": "physical",
  "sku": "HOODIE-PREM",
  "price": 79.99,
  "description": "Premium cotton blend hoodie",
  "weight": 1.5,
  "width": 20,
  "height": 28,
  "depth": 2,
  "inventory_level": 100,
  "inventory_tracking": "product",
  "is_visible": true,
  "categories": [23]
}

Actualizar variantes de producto

Los productos con opciones (talla, color) tienen variantes. Cada variante puede tener su propio SKU, precio e inventario.

PUT https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products/{product-id}/variants/{variant-id}
X-Auth-Token: {token}
Content-Type: application/json

{
  "sku": "HOODIE-PREM-BLK-M",
  "price": 79.99,
  "inventory_level": 50,
  "option_values": [
    {
      "option_display_name": "Color",
      "label": "Black"
    },
    {
      "option_display_name": "Size",
      "label": "Medium"
    }
  ]
}

Gestionar inventario

PUT https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products/{product-id}
X-Auth-Token: {token}
Content-Type: application/json

{
  "inventory_level": 75
}

O actualiza el inventario de la variante:

PUT https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products/{product-id}/variants/{variant-id}
Content-Type: application/json

{
  "inventory_level": 25
}

Pedidos y cumplimiento

Los pedidos son donde ocurre el negocio. La API de Pedidos V2 gestiona la creación, actualización y cumplimiento de pedidos.

Listar pedidos

GET https://api.bigcommerce.com/stores/{store-hash}/v2/orders
X-Auth-Token: {token}
Accept: application/json

Respuesta:

[
  {
    "id": 115,
    "status": "Awaiting Fulfillment",
    "status_id": 11,
    "customer_id": 45,
    "date_created": "2026-03-24T10:30:00+00:00",
    "subtotal_ex_tax": 149.99,
    "total_inc_tax": 162.49,
    "items_total": 2,
    "items_shipped": 0,
    "shipping_address": {
      "first_name": "John",
      "last_name": "Doe",
      "street_1": "123 Main St",
      "city": "Austin",
      "state": "Texas",
      "zip": "78701",
      "country": "United States"
    }
  }
]

Obtener detalles del pedido

GET https://api.bigcommerce.com/stores/{store-hash}/v2/orders/{order-id}
X-Auth-Token: {token}

Obtener productos del pedido

GET https://api.bigcommerce.com/stores/{store-hash}/v2/orders/{order-id}/products
X-Auth-Token: {token}

Actualizar estado del pedido

PUT https://api.bigcommerce.com/stores/{store-hash}/v2/orders/{order-id}
X-Auth-Token: {token}
Content-Type: application/json

{
  "status_id": 12
}

IDs de estado comunes:

0: Incompleto
11: Esperando cumplimiento
12: Completado
5: Cancelado
4: Reembolsado

Crear un envío (cumplimiento)

POST https://api.bigcommerce.com/stores/{store-hash}/v2/orders/{order-id}/shipments
X-Auth-Token: {token}
Content-Type: application/json

{
  "tracking_number": "1Z999AA10123456784",
  "carrier": "UPS",
  "shipping_method": "UPS Ground",
  "items": [
    {
      "order_product_id": 234,
      "quantity": 1
    }
  ]
}

Clientes y segmentación

La API de Clientes V3 gestiona datos de clientes, direcciones y grupos de clientes.

Listar clientes

GET https://api.bigcommerce.com/stores/{store-hash}/v3/customers
X-Auth-Token: {token}
Accept: application/json

Respuesta:

{
  "data": [
    {
      "id": 45,
      "email": "john.doe@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "company": "Acme Corp",
      "phone": "512-555-1234",
      "customer_group_id": 1,
      "notes": "VIP customer",
      "tax_exempt_category": "",
      "date_created": "2025-11-15T09:30:00+00:00",
      "date_modified": "2026-03-20T14:22:00+00:00"
    }
  ]
}

Crear un cliente

POST https://api.bigcommerce.com/stores/{store-hash}/v3/customers
X-Auth-Token: {token}
Content-Type: application/json

{
  "email": "jane.smith@example.com",
  "first_name": "Jane",
  "last_name": "Smith",
  "phone": "512-555-5678",
  "customer_group_id": 2
}

Actualizar cliente

PUT https://api.bigcommerce.com/stores/{store-hash}/v3/customers/{customer-id}
X-Auth-Token: {token}
Content-Type: application/json

{
  "notes": "Repeat customer - priority support",
  "customer_group_id": 3
}

Webhooks para actualizaciones en tiempo real

Los webhooks notifican a tu aplicación cuando ocurren eventos en una tienda. En lugar de sondear, BigCommerce envía datos a tus endpoints.

Crear un webhook

POST https://api.bigcommerce.com/stores/{store-hash}/v3/hooks
X-Auth-Token: {token}
Content-Type: application/json

{
  "scope": "store/order/created",
  "destination": "https://yourapp.com/webhooks/orders",
  "is_active": true
}

Scopes disponibles:

store/order/created - Nuevo pedido realizado
store/order/updated - Estado del pedido cambiado
store/order/archived - Pedido archivado
store/product/created - Producto añadido
store/product/updated - Producto modificado
store/product/deleted - Producto eliminado
store/customer/created - Nuevo cliente
store/inventory/updated - Stock cambiado

Verificar firmas de webhook

BigCommerce firma los webhooks para que puedas verificar que son legítimos:

import crypto from 'crypto'

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex')
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  )
}

app.post('/webhooks/orders', (req, res) => {
  const signature = req.headers['x-bc-webhook-signature']
  const payload = JSON.stringify(req.body)
  
  if (!verifyWebhook(payload, signature, process.env.BC_CLIENT_SECRET)) {
    return res.status(401).send('Firma inválida')
  }
  
  // Procesar el webhook
  console.log('Pedido creado:', req.body.data.id)
  res.status(200).send('OK')
})

Probando las APIs de BigCommerce con Apidog

Las APIs de BigCommerce requieren encabezados consistentes y una autenticación adecuada. Probar manualmente con curl se vuelve tedioso. Apidog lo simplifica.

1. Configuración del entorno

Crea entornos para cada tienda:

# Tienda de Producción
STORE_HASH: abc123
ACCESS_TOKEN: xyz789
BASE_URL: https://api.bigcommerce.com/stores/abc123

# Tienda de Staging
STORE_HASH: staging456
ACCESS_TOKEN: staging_token
BASE_URL: https://api.bigcommerce.com/stores/staging456

2. Scripts de pre-solicitud

Agrega los encabezados de autenticación automáticamente:

pm.request.headers.add({
  key: 'X-Auth-Token',
  value: pm.environment.get('ACCESS_TOKEN')
})
pm.request.headers.add({
  key: 'Accept',
  value: 'application/json'
})

3. Validar respuestas

Prueba que los productos tengan los campos requeridos:

pm.test('Los productos tienen los campos requeridos', () => {
  const response = pm.response.json()
  response.data.forEach(product => {
    pm.expect(product).to.have.property('id')
    pm.expect(product).to.have.property('name')
    pm.expect(product).to.have.property('price')
    pm.expect(product.price).to.be.above(0)
  })
})

pm.test('La paginación funciona', () => {
  const response = pm.response.json()
  pm.expect(response.meta.pagination).to.have.property('total')
  pm.expect(response.meta.pagination.page).to.eql(1)
})

Prueba las APIs de BigCommerce con Apidog - gratis

Errores comunes y soluciones

401 No autorizado

Causa: Token de acceso inválido o ausente.

Solución:

Verifica que el encabezado X-Auth-Token esté configurado
Verifica que el token no haya sido revocado
Asegúrate de que la cuenta de API tenga los scopes correctos

403 Prohibido

Causa: El token es válido pero carece del scope requerido.

Solución:

Verifica los permisos de tu cuenta de API
Agrega el scope faltante (Productos, Pedidos, etc.)
Genera un nuevo token con permisos expandidos

404 No encontrado

Causa: Endpoint incorrecto o el recurso no existe.

Solución:

Verifica que el hash de la tienda sea correcto
Comprueba la versión de la API en la URL (v2 vs v3)
Asegúrate de que el ID del recurso exista

429 Demasiadas solicitudes

Causa: Límite de tasa excedido.

Solución: BigCommerce permite diferentes límites por endpoint. Productos: 10,000 solicitudes/hora. Pedidos: 30,000 solicitudes/hora. Verifica el encabezado X-Rate-Limit-Remaining e implementa un retroceso exponencial.

async function callWithBackoff(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fn()
    if (response.status === 429) {
      const retryAfter = response.headers.get('X-Rate-Limit-Reset')
      await new Promise(r => setTimeout(r, retryAfter * 1000))
    } else {
      return response
    }
  }
}

422 Entidad no procesable

Causa: Error de validación en el cuerpo de la solicitud.

Solución: Revisa la respuesta para obtener detalles. BigCommerce devuelve errores de validación específicos:

{
  "errors": {
    "price": "Price must be greater than zero",
    "sku": "SKU already exists"
  }
}

Alternativas y comparaciones

Característica	BigCommerce	Shopify	WooCommerce
Control de versiones de API	V2 y V3	REST y GraphQL	REST
Límites de tasa	10K-30K/hora	2/min (cubeta con fugas)	Depende del hosting
Webhooks	Sí	Sí	Sí (plugin)
GraphQL	No	Sí	No
Calidad del SDK	Buena	Excelente	Solo PHP
Múltiples tiendas	Sí	No	No

La API V3 de BigCommerce es más consistente que el enfoque fragmentado de Shopify, pero la API GraphQL de Shopify ofrece más flexibilidad para consultas complejas.

Casos de uso reales

Sincronización de inventario multicanal. Una marca vende en BigCommerce, Amazon y tiendas físicas. Utilizan la API de Productos para sincronizar los niveles de inventario en todos los canales, evitando la sobreventa. Apidog prueba los endpoints de sincronización antes de cada despliegue.

Automatización de pedidos. Una empresa de cajas de suscripción utiliza webhooks para activar el cumplimiento cuando se crean los pedidos. La API de Pedidos actualiza los números de seguimiento. Su almacén recibe listas de picking automáticamente a través de los manejadores de webhooks.

Segmentación de clientes. Un sitio de e-commerce utiliza la API de Clientes para segmentar compradores según su historial de compras. Los clientes VIP se añaden a un grupo especial con precios exclusivos. La integración se ejecuta semanalmente mediante un trabajo programado.

Conclusión

Esto es lo que has aprendido:

La autenticación utiliza tokens de API (integraciones sencillas) o OAuth (aplicaciones de marketplace)
La API de Catálogo V3 gestiona productos y variantes
La API de Pedidos V2 gestiona el procesamiento y cumplimiento de pedidos
La API de Clientes V3 gestiona los datos de los clientes
Los webhooks envían actualizaciones en tiempo real a tus endpoints
Prueba y documenta con Apidog para integraciones fiables

Tus próximos pasos:

Crea una cuenta de API en tu tienda BigCommerce
Realiza tu primera llamada a la API para listar productos
Configura un webhook para la creación de pedidos
Guarda tus llamadas a la API en Apidog
Crea tu integración

Prueba las APIs de BigCommerce con Apidog - gratis

Preguntas Frecuentes

¿Cuál es la diferencia entre las APIs V2 y V3?La V3 es la API más nueva y consistente. Úsala para productos, categorías, marcas y clientes. La V2 maneja los pedidos, que aún no han sido migrados. Utilizarás ambas en la mayoría de las integraciones.

¿Cómo obtengo el hash de mi tienda?Está en la URL de administración de tu BigCommerce: https://store-abc123.mybigcommerce.com/manage. La parte abc123 es el hash de tu tienda. También es visible en la configuración de la cuenta de API.

¿Puedo usar la API en una tienda de prueba?Sí. Las tiendas de prueba de BigCommerce tienen acceso completo a la API. Esto es perfecto para el desarrollo y las pruebas antes de salir en vivo.

¿Cuál es el límite de tasa para las llamadas a la API?Depende del endpoint. Productos: 10,000 solicitudes/hora. Pedidos: 30,000 solicitudes/hora. Verifica X-Rate-Limit-Remaining en los encabezados de respuesta para ver tu límite actual.

¿Cómo manejo la paginación?Usa los parámetros de consulta page y limit. El límite predeterminado es 50. Verifica meta.pagination en las respuestas para el total de páginas. Recorre hasta que hayas obtenido todos los registros.

let allProducts = []
let page = 1

while (true) {
  const response = await fetch(
    `${baseUrl}/v3/catalog/products?page=${page}&limit=100`,
    { headers: { 'X-Auth-Token': token } }
  )
  const data = await response.json()
  allProducts.push(...data.data)
  
  if (page >= data.meta.pagination.total_pages) break
  page++
}

¿Puedo subir imágenes de productos a través de la API?Sí. Utiliza el endpoint de imágenes de productos:

POST https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products/{product-id}/images
Content-Type: application/json

{
  "image_url": "https://example.com/image.jpg",
  "is_thumbnail": true
}

¿Cómo manejo la moneda y las tiendas múltiples?Las tiendas de BigCommerce tienen una moneda base. La multimoneda se gestiona a nivel de la interfaz de la tienda, no de la API. Para múltiples tiendas, crea cuentas de API separadas y utiliza diferentes entornos en Apidog.

¿Qué sucede si mi endpoint de webhook no está disponible?BigCommerce reintenta los webhooks fallidos con un retroceso exponencial. Después de 5 fallos en 24 horas, el webhook se deshabilita. Monitorea tus endpoints y alerta sobre los fallos.