DEV Community

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

Posted on • Originally published at apidog.com

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

En resumen

Las APIs de BigCommerce permiten gestionar productos, pedidos, clientes y operaciones de la tienda de forma programática. Se usa autenticación con tokens de API (para servidor) u OAuth (para aplicaciones), se llaman a los endpoints REST en api.bigcommerce.com y se gestionan webhooks para notificaciones en tiempo real. Para probar tus integraciones, usa Apidog para guardar llamadas, validar respuestas y compartir colecciones.

Prueba Apidog hoy

Introducción

BigCommerce impulsa más de 60,000 tiendas online, cada una con necesidades de integración personalizadas: inventario, pedidos, clientes, pagos. Aquí entran las APIs.

La plataforma ofrece tres tipos de API:

  • Storefront API: para comercio sin interfaz.
  • Management API: operaciones de backend.
  • Payments API: procesamiento de transacciones.

La mayoría de los desarrolladores trabajan con la Management API para gestionar productos, pedidos y clientes.

La documentación puede ser extensa. Necesitarás moverte entre documentos de autenticación, referencias y guías de webhooks para tareas básicas.

Esta guía va al grano sobre lo esencial: productos, pedidos, clientes y webhooks. Verás autenticación, patrones comunes y cómo probar integraciones antes de lanzarlas.

💡 Tip: Si construyes integraciones de BigCommerce, Apidog ayuda a diseñar, probar y documentar esas llamadas. Guarda solicitudes como colecciones, usa variables de entorno y valida respuestas. Detecta errores antes de que lleguen a producción.

Prueba tus APIs de BigCommerce con Apidog - gratis.

Al final de esta guía podrás:

  • Configurar 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 tu caso de uso.

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

Si desarrollas un script o servicio para una tienda, usa tokens de API.

Cómo crear una cuenta de API:

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

Obtendrás:

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

Primera llamada de prueba:

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

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

Método 2: OAuth (aplicaciones de marketplace)

Para apps en el marketplace de BigCommerce, usa OAuth.

Flujo de OAuth:

  1. El usuario instala tu app desde el marketplace.
  2. BigCommerce redirige a tu callback con un código de autenticación.
  3. Tu servidor intercambia el código por un token de acceso.
  4. Almacena el token para futuras llamadas.

Intercambia el 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 se usa para llamadas a la API
// context contiene el hash de la tienda
Enter fullscreen mode Exit fullscreen mode

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

Gestión de productos y catálogo

La API de Catálogo V3 administra 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
Enter fullscreen mode Exit fullscreen mode

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

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

Actualizar variantes de producto 

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

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

O para una variante:

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

{
  "inventory_level": 25
}
Enter fullscreen mode Exit fullscreen mode

Pedidos y cumplimiento

La API de Pedidos V2 permite gestionar pedidos, actualizaciones y cumplimiento.

Listar pedidos 

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

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

Obtener detalles del pedido 

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

Obtener productos del pedido 

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

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

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

Clientes y segmentación

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

Listar clientes 

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

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

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

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

Webhooks para actualizaciones en tiempo real

Los webhooks notifican a tu app cuando ocurren eventos. 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
}
Enter fullscreen mode Exit fullscreen mode

Scopes disponibles:

  • store/order/created - Nuevo pedido
  • store/order/updated - Estado de 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. Usa este ejemplo en Node.js:

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

Probando las APIs de BigCommerce con Apidog

Las APIs de BigCommerce requieren autenticación y encabezados consistentes. Probar manualmente con curl es tedioso; Apidog lo simplifica.

Apidog BigCommerce

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

2. Scripts de pre-solicitud

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

3. Validar respuestas

Verifica campos requeridos en productos y la paginación:

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

Prueba las APIs de BigCommerce con Apidog - gratis.

Errores comunes y soluciones

401 No autorizado

Causa: Token inválido o ausente.

Solución:

  1. Verifica que el encabezado X-Auth-Token esté presente.
  2. Revisa que el token no haya sido revocado.
  3. Asegúrate de tener los scopes correctos.

403 Prohibido

Causa: El token es válido pero falta un scope.

Solución:

  1. Revisa permisos de tu cuenta de API.
  2. Agrega el scope faltante.
  3. Genera un nuevo token con permisos adecuados.

404 No encontrado

Causa: Endpoint incorrecto o recurso inexistente.

Solución:

  1. Verifica el hash de la tienda.
  2. Comprueba la versión de la API en la URL (v2 vs v3).
  3. Asegúrate de que el recurso exista.

429 Demasiadas solicitudes

Causa: Límite de tasa excedido.

Solución: BigCommerce permite límites distintos por endpoint. Productos: 10,000/hora. Pedidos: 30,000/hora. Verifica el encabezado X-Rate-Limit-Remaining y usa 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
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

422 Entidad no procesable

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

Solución: Revisa la respuesta. BigCommerce especifica errores:

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

Alternativas y comparaciones

Característica BigCommerce Shopify WooCommerce
Control de versiones 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 Shopify REST, pero la GraphQL de Shopify permite mayor flexibilidad en consultas complejas.

Casos de uso reales

Sincronización de inventario multicanal: Una marca vende en BigCommerce, Amazon y tiendas físicas. Usa la API de Productos para sincronizar inventario y evitar sobreventas. Apidog valida los endpoints antes de cada despliegue.

Automatización de pedidos: Una empresa de suscripciones utiliza webhooks para activar el cumplimiento al crear pedidos. La API de Pedidos actualiza los números de seguimiento y el almacén recibe listas de picking automáticas.

Segmentación de clientes: Un e-commerce segmenta compradores según historial usando la API de Clientes. Los VIP se añaden a un grupo especial con precios exclusivos. La integración corre semanalmente de forma programada.

Conclusión

Resumen de lo aprendido:

  • Autenticación con tokens de API (integraciones) u OAuth (apps marketplace)
  • API de Catálogo V3 para productos y variantes
  • API de Pedidos V2 para procesamiento y cumplimiento
  • API de Clientes V3 para datos de clientes
  • Webhooks para actualizaciones en tiempo real
  • Prueba y documentación con Apidog para integraciones fiables

Próximos pasos:

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

Prueba las APIs de BigCommerce con Apidog - gratis.

Preguntas Frecuentes

¿Cuál es la diferencia entre las APIs V2 y V3?

V3 es la API más nueva y consistente, ideal para productos, categorías, marcas y clientes. V2 se usa para pedidos. La mayoría de integraciones usan ambas.

¿Cómo obtengo el hash de mi tienda?

Está en la URL de administración:

https://store-abc123.mybigcommerce.com/manage

La parte abc123 es el hash. También visible en la configuración de la cuenta de API.

¿Puedo usar la API en una tienda de prueba?

Sí, las tiendas de prueba tienen acceso completo a la API. Ideal para desarrollo y pruebas.

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

Depende del endpoint. Productos: 10,000/hora. Pedidos: 30,000/hora. Verifica X-Rate-Limit-Remaining en los headers de respuesta.

¿Cómo manejo la paginación?

Usa los parámetros de consulta page y limit. El límite por defecto es 50. Consulta meta.pagination para el total de páginas. Itera hasta obtener 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++
}
Enter fullscreen mode Exit fullscreen mode

¿Puedo subir imágenes de productos por API?

Sí, usa 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
}
Enter fullscreen mode Exit fullscreen mode

¿Cómo manejo moneda y múltiples tiendas?

Cada tienda tiene una moneda base. La multimoneda se gestiona en la interfaz, no en la API. Para varias tiendas, crea cuentas de API separadas y usa entornos distintos en Apidog.

¿Qué pasa si mi endpoint de webhook no está disponible?

BigCommerce reintenta webhooks fallidos con retroceso exponencial. Tras 5 fallos en 24 horas, el webhook se desactiva. Monitorea y alerta sobre los fallos.

Top comments (0)