Como Usar APIs BigCommerce: Guia do Desenvolvedor para Integração de E-commerce

TL;DR

As APIs do BigCommerce permitem que você gerencie produtos, pedidos, clientes e operações da loja programaticamente. Você se autentica com tokens de API (para o lado do servidor) ou OAuth (para aplicativos), chama endpoints REST em api.bigcommerce.com e lida com webhooks para atualizações em tempo real. Para testes, use o Apidog para salvar suas chamadas de API, validar respostas e compartilhar coleções com sua equipe.

Introdução

O BigCommerce impulsiona mais de 60.000 lojas online. Cada uma delas precisa de integrações personalizadas - sincronização de estoque, processamento de pedidos, gerenciamento de clientes, manuseio de pagamentos. É aí que as APIs entram.

A plataforma oferece três tipos de API: Storefront API (comércio headless), Management API (operações de back-end) e Payments API (transações). A maioria dos desenvolvedores trabalha com a Management API. Ela lida com produtos, pedidos, clientes e tudo o que acontece nos bastidores.

A curva de aprendizado não é íngreme, mas a documentação pode parecer esmagadora. Você se verá pulando entre documentos de autenticação, referências de API e guias de webhook apenas para completar uma tarefa simples.

Este guia foca no que você realmente usará. Produtos, pedidos, clientes e webhooks. Você aprenderá autenticação, padrões comuns e como testar suas integrações antes que elas toquem uma loja real.

💡

Se você está construindo integrações BigCommerce, o Apidog ajuda a projetar, testar e documentar essas chamadas de API. Salve requisições como coleções, use variáveis de ambiente para diferentes lojas e valide se as respostas correspondem aos esquemas esperados. Ele captura erros antes que afetem clientes reais.

botão

Teste suas APIs BigCommerce com Apidog - grátis

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

Configurar a autenticação BigCommerce corretamente
Gerenciar produtos, variantes e estoque
Processar pedidos e lidar com dados de clientes
Configurar webhooks para atualizações em tempo real
Testar e documentar suas integrações com Apidog

Autenticação: obtendo acesso à sua loja

O BigCommerce oferece dois métodos de autenticação, dependendo do que você está construindo.

Método 1: Tokens de API (para integrações personalizadas)

Se você está construindo um script ou serviço que funciona com uma loja, use tokens de API.

Criar uma conta de API:

Vá para o painel de administração da sua loja
Configurações → Contas de API → Criar Conta de API
Escolha "V3/V2 API Token"
Selecione os escopos necessários (Produtos, Pedidos, Clientes, etc.)
Salve as credenciais

Você obterá:

URL da Loja: mystore.mybigcommerce.com
Token de Acesso: abc123def456...
ID do Cliente: abc123...
Segredo do Cliente: xyz789...

Faça sua primeira chamada:

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"

O store-hash é a parte após /stores/ no seu caminho de API. Também é visível na URL de administração da sua loja.

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

Se você está construindo um aplicativo para o marketplace do BigCommerce, use OAuth.

O fluxo OAuth:

O usuário clica em "Instalar" no seu aplicativo no marketplace
O BigCommerce redireciona para sua URL de callback com um código de autenticação
Seu servidor troca o código por um token de acesso
Armazene o token para futuras chamadas de API

Trocar 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 é o que você usa para chamadas de API
// context contém store_hash

Use o 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"

Produtos e gerenciamento de catálogo

Os produtos são o coração de qualquer loja BigCommerce. A V3 Catalog API lida com produtos, variantes, categorias e marcas.

Listar produtos

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

Resposta:

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

Criar um produto

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

Atualizar variantes de produto

Produtos com opções (tamanho, cor) têm variantes. Cada variante pode ter seu próprio SKU, preço e estoque.

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

Gerenciar estoque

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

{
  "inventory_level": 75
}

Ou atualize o estoque da 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 e fulfillment

Pedidos são onde o negócio acontece. A Orders V2 API lida com a criação, atualização e fulfillment de pedidos.

Listar pedidos

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

Resposta:

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

Obter detalhes do pedido

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

Obter produtos do pedido

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

Atualizar status do 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 status comuns:

0: Incompleto
11: Aguardando Fulfillment
12: Concluído
5: Cancelado
4: Reembolsado

Criar um envio (fulfillment)

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 e segmentação

A Customers V3 API lida com dados de clientes, endereços e grupos de clientes.

Listar clientes

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

Resposta:

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

Criar um 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
}

Atualizar 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 atualizações em tempo real

Webhooks notificam seu aplicativo quando eventos ocorrem em uma loja. Em vez de polling, o BigCommerce envia dados para seus endpoints.

Criar um 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
}

Escopos disponíveis:

store/order/created - Novo pedido feito
store/order/updated - Status do pedido alterado
store/order/archived - Pedido arquivado
store/product/created - Produto adicionado
store/product/updated - Produto modificado
store/product/deleted - Produto removido
store/customer/created - Novo cliente
store/inventory/updated - Estoque alterado

Verificar assinaturas de webhook

O BigCommerce assina webhooks para que você possa verificar se são 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('Invalid signature')
  }
  
  // Processar o webhook
  console.log('Pedido criado:', req.body.data.id)
  res.status(200).send('OK')
})

Testando APIs BigCommerce com Apidog

As APIs BigCommerce exigem cabeçalhos consistentes e autenticação adequada. Testar manualmente com curl se torna tedioso. O Apidog simplifica isso.

1. Configuração de ambiente

Crie ambientes para cada loja:

# Loja de Produção
STORE_HASH: abc123
ACCESS_TOKEN: xyz789
BASE_URL: https://api.bigcommerce.com/stores/abc123

# Loja de Homologação
STORE_HASH: staging456
ACCESS_TOKEN: staging_token
BASE_URL: https://api.bigcommerce.com/stores/staging456

2. Scripts de pré-requisição

Adicione os cabeçalhos de autenticação automaticamente:

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 respostas

Teste se os produtos têm os campos obrigatórios:

pm.test('Produtos têm campos obrigatórios', () => {
  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('A paginação funciona', () => {
  const response = pm.response.json()
  pm.expect(response.meta.pagination).to.have.property('total')
  pm.expect(response.meta.pagination.page).to.eql(1)
})

Teste APIs BigCommerce com Apidog - grátis

Erros comuns e soluções

401 Não Autorizado

Causa: Token de acesso inválido ou ausente.

Solução:

Verifique se o cabeçalho X-Auth-Token está configurado
Verifique se o token não foi revogado
Garanta que a conta de API tenha os escopos corretos

403 Proibido

Causa: O token é válido, mas não possui o escopo necessário.

Solução:

Verifique as permissões da sua conta de API
Adicione o escopo ausente (Produtos, Pedidos, etc.)
Gere um novo token com permissões expandidas

404 Não Encontrado

Causa: Endpoint errado ou recurso não existe.

Solução:

Verifique se o hash da loja está correto
Verifique a versão da API na URL (v2 vs v3)
Garanta que o ID do recurso exista

429 Muitas Requisições

Causa: Limite de taxa excedido.

Solução: O BigCommerce permite limites diferentes por endpoint. Produtos: 10.000 requisições/hora. Pedidos: 30.000 requisições/hora. Verifique o cabeçalho X-Rate-Limit-Remaining e implemente um backoff.

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 Entidade Não Processável

Causa: Erro de validação no corpo da requisição.

Solução: Verifique a resposta para detalhes. O BigCommerce retorna erros de validação específicos:

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

Alternativas e comparações

Recurso	BigCommerce	Shopify	WooCommerce
Versionamento de API	V2 e V3	REST e GraphQL	REST
Limites de taxa	10K-30K/hora	2/min (leaky bucket)	Depende da hospedagem
Webhooks	Sim	Sim	Sim (plugin)
GraphQL	Não	Sim	Não
Qualidade do SDK	Boa	Excelente	Somente PHP
Multi-loja	Sim	Não	Não

A V3 API do BigCommerce é mais consistente do que a abordagem fragmentada do Shopify, mas a GraphQL API do Shopify oferece mais flexibilidade para consultas complexas.

Casos de uso reais

Sincronização de estoque multi-canal. Uma marca vende no BigCommerce, Amazon e lojas físicas. Eles usam a Products API para sincronizar os níveis de estoque em todos os canais, evitando vendas em excesso. O Apidog testa os endpoints de sincronização antes de cada implantação.

Automação de pedidos. Uma empresa de caixas de assinatura usa webhooks para acionar o fulfillment quando os pedidos são criados. A Orders API atualiza os números de rastreamento. Seu armazém recebe listas de separação automaticamente via manipuladores de webhook.

Segmentação de clientes. Um site de e-commerce usa a Customers API para segmentar compradores com base no histórico de compras. Clientes VIP são adicionados a um grupo especial com preços exclusivos. A integração é executada semanalmente por meio de um trabalho agendado.

Conclusão

Aqui está o que você aprendeu:

A autenticação usa tokens de API (integrações simples) ou OAuth (aplicativos de marketplace)
A V3 Catalog API lida com produtos e variantes
A V2 Orders API lida com o processamento e fulfillment de pedidos
A V3 Customers API lida com dados de clientes
Webhooks enviam atualizações em tempo real para seus endpoints
Teste e documente com Apidog para integrações confiáveis

Seus próximos passos:

Crie uma conta de API na sua loja BigCommerce
Faça sua primeira chamada de API para listar produtos
Configure um webhook para a criação de pedidos
Salve suas chamadas de API no Apidog
Construa sua integração

Teste APIs BigCommerce com Apidog - grátis

FAQ

Qual a diferença entre as APIs V2 e V3?V3 é a API mais nova e consistente. Use-a para produtos, categorias, marcas e clientes. A V2 lida com pedidos, que ainda não foram migrados. Você usará ambas na maioria das integrações.

Como obtenho o hash da minha loja?Está na URL de administração do seu BigCommerce: https://store-abc123.mybigcommerce.com/manage. A parte abc123 é o hash da sua loja. Também é visível nas configurações da conta de API.

Posso usar a API em uma loja de teste?Sim. As lojas de teste do BigCommerce têm acesso total à API. Isso é perfeito para desenvolvimento e testes antes de ir ao ar.

Qual é o limite de taxa para chamadas de API?Depende do endpoint. Produtos: 10.000 requisições/hora. Pedidos: 30.000 requisições/hora. Verifique X-Rate-Limit-Remaining nos cabeçalhos da resposta para ver seu limite atual.

Como lido com a paginação?Use os parâmetros de consulta page e limit. O limite padrão é 50. Verifique meta.pagination nas respostas para o total de páginas. Repita até ter buscado todos os 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++
}

Posso fazer upload de imagens de produto via API?Sim. Use o endpoint de imagens de produto:

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
}

Como lido com moeda e multi-loja?As lojas BigCommerce têm uma moeda base. A multi-moeda é tratada no nível do storefront, não da API. Para várias lojas, crie contas de API separadas e use diferentes ambientes no Apidog.

O que acontece se meu endpoint de webhook estiver inativo?O BigCommerce tenta novamente os webhooks falhos com backoff exponencial. Após 5 falhas em 24 horas, o webhook é desativado. Monitore seus endpoints e alerte sobre falhas.