Integração

Visão geral

O BCX-Brain, a plataforma de vendas da BCX Capital and Holding, tem uma API REST v3 em JSON, no formato que o mercado de comércio eletrônico já usa: produto, variação, pedido, cliente e aviso por webhook. Se o seu ERP já integra com loja virtual, o trabalho é de de-para: apontar para o endereço da loja, usar a chave que entregamos e seguir os campos desta página.

A divisão é simples: o ERP é a fonte do catálogo (produto, preço e estoque) e a loja é a fonte da venda (pedido e cliente). A nota fiscal e o rastreio voltam do ERP para o pedido.

Primeiros passos

1. Receba o ambiente de teste. Toda integração começa numa loja de homologação, com o catálogo real da empresa e pagamento simulado. Nada do que acontece ali chega ao cliente final.
2. Receba a chave de acesso. Entregamos uma chave por loja: bcx_test_… na homologação e bcx_live_… na loja no ar.
3. Faça a primeira chamada. Liste os produtos para testar o acesso.
4. Monte o de-para. Use as tabelas de Produtos e Campos de extensão.
5. Rode a homologação. Siga o roteiro de homologação. Com tudo aprovado, entregamos a chave da loja no ar.

curl https://{sua-loja}/api/v3/products?per_page=5 \
  -H "Authorization: Bearer $BCX_CHAVE"

Autenticação

Toda chamada leva a chave de acesso no cabeçalho Authorization, no formato Bearer, sempre sobre HTTPS. Chamada sem chave, com chave revogada ou sem HTTPS volta 401.

Authorization: Bearer bcx_test_SUA_CHAVE
Content-Type: application/json; charset=utf-8

Convenções

Criar produto

Cria o produto na loja. O produto nasce como draft (rascunho) até ter foto e descrição aprovadas pelo nosso time; preço e estoque já valem desde o primeiro envio. Todo produto criado pela integração tem controle de estoque ligado.

Campos

curl -X POST https://{sua-loja}/api/v3/products \
  -H "Authorization: Bearer $BCX_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "sku": "100245",
  "name": "Cimento CP II-E-32 Votoran 50 kg",
  "regular_price": "38.90",
  "manage_stock": true,
  "stock_quantity": 420,
  "weight": "50.2",
  "dimensions": { "length": "60", "width": "40", "height": "12" },
  "meta_data": [
    { "key": "bcx_ean", "value": "7891234567895" },
    { "key": "bcx_ncm", "value": "25232910" },
    { "key": "bcx_marca", "value": "Votoran" },
    { "key": "bcx_unidade_venda", "value": "saco" }
  ]
}'

{
  "id": 48213,
  "sku": "100245",
  "name": "Cimento CP II-E-32 Votoran 50 kg",
  "status": "draft",
  "regular_price": "38.90",
  "stock_quantity": 420,
  "stock_status": "instock",
  "date_created_gmt": "2026-10-20T18:42:10"
}

Buscar produto por SKU

Use antes de criar, para não duplicar. Se a lista voltar vazia, o produto ainda não existe na loja.

curl "https://{sua-loja}/api/v3/products?sku=100245" \
  -H "Authorization: Bearer $BCX_CHAVE"

Atualizar em lote

Cria, atualiza e despublica até 100 produtos numa chamada só. É o caminho recomendado para a carga inicial e para a sincronização periódica.

{
  "create": [ { "sku": "100246", "name": "Argamassa AC-II Quartzolit 20 kg", "regular_price": "32.50", … } ],
  "update": [ { "id": 48213, "stock_quantity": 380 } ],
  "delete": []
}

Estoque e preço

Atualização leve, só com o que mudou. Para muitos itens, use o lote.

{
  "regular_price": "39.90",
  "sale_price": "36.90",
  "stock_quantity": 355
}

Estoque por filial: envie em stock_quantity o saldo das filiais que atendem a loja on-line, e o detalhe por filial em bcx_estoque_filiais.

Variações

Para o mesmo produto em versões diferentes (voltagem 110V e 220V, cor, tamanho). O produto pai é criado com "type": "variable" e cada variação tem o seu SKU, preço e estoque.

{
  "sku": "200871-220",
  "regular_price": "1249.00",
  "manage_stock": true,
  "stock_quantity": 6,
  "attributes": [ { "name": "Voltagem", "option": "220V" } ]
}

Campos de extensão

Dados do ERP que o padrão não tem campo próprio vão em meta_data, sempre com o prefixo bcx_. A plataforma usa esses campos na vitrine, na busca, no frete e no painel de vendas.

Listar pedidos

O ERP busca os pedidos pagos que ainda não importou. processing quer dizer pagamento confirmado: é o momento de faturar e separar. Com bcx_pendente_erp=true, a loja devolve só os pedidos que ainda não têm o número do ERP gravado (veja Registrar a importação).

curl "https://{sua-loja}/api/v3/orders?status=processing&bcx_pendente_erp=true&per_page=50&orderby=date&order=asc" \
  -H "Authorization: Bearer $BCX_CHAVE"

Objeto do pedido

Os campos que o ERP precisa para faturar. O pedido traz CPF ou CNPJ, inscrição estadual, número e bairro em campos separados.

{
  "id": 10582,
  "number": "10582",
  "status": "processing",
  "date_paid_gmt": "2026-10-20T19:05:44",
  "payment_method": "asaas-pix",
  "transaction_id": "pay_8f2k1x0q",
  "total": "1027.80",
  "discount_total": "54.10",
  "shipping_total": "49.90",
  "billing": {
    "first_name": "Marcos", "last_name": "Almeida",
    "company": "Almeida Reformas Ltda",
    "persontype": "2", "cnpj": "12.345.678/0001-90", "ie": "123.456.789.110",
    "address_1": "Rua das Palmeiras", "number": "120",
    "neighborhood": "Jabaquara", "city": "São Paulo",
    "state": "SP", "postcode": "04321-000",
    "email": "compras@exemplo.com.br", "phone": "(11) 90000-0000"
  },
  "line_items": [
    { "sku": "100245", "name": "Cimento CP II-E-32 Votoran 50 kg", "quantity": 20, "price": 38.90, "total": "778.00" }
  ],
  "shipping_lines": [ { "method_title": "Entrega própria", "total": "49.90" } ],
  "meta_data": [
    { "key": "bcx_canal", "value": "mesa" },
    { "key": "bcx_filial", "value": "01" }
  ]
}

O valor que o ERP fatura é sempre o total do pedido. Taxas e divisões de pagamento ficam na plataforma de pagamento e não entram na nota.

Status do pedido

Registrar a importação no ERP

Logo depois de importar, grave o número do pedido no ERP. A partir daí o pedido sai da lista bcx_pendente_erp=true, e o número aparece no painel da loja, para o nosso time encontrar o pedido nos dois lados.

{
  "meta_data": [
    { "key": "bcx_erp_pedido", "value": "PV-558120" },
    { "key": "bcx_erp_importado_em", "value": "2026-10-20T16:07:02-03:00" }
  ]
}

Nota fiscal e rastreio

Quando a NF-e for autorizada e o pedido sair, devolva os dados e mude o status para completed. O cliente recebe o aviso por e-mail, uma vez só, com o número da nota, o link do DANFE e o rastreio, e passa a ver tudo na conta dele, em «Nota fiscal e entrega».

{
  "status": "completed",
  "meta_data": [
    { "key": "bcx_nfe_chave", "value": "35261012345678000190550010000123451000123456" },
    { "key": "bcx_nfe_numero", "value": "12345" },
    { "key": "bcx_nfe_serie", "value": "1" },
    { "key": "bcx_nfe_danfe_url", "value": "https://…/danfe.pdf" },
    { "key": "bcx_nfe_xml_url", "value": "https://…/nfe.xml" },
    { "key": "bcx_rastreio_codigo", "value": "AB123456789BR" },
    { "key": "bcx_rastreio_transportadora", "value": "Correios" },
    { "key": "bcx_volumes", "value": "3" }
  ]
}

Clientes

Os dados do cliente já chegam completos dentro do pedido. Esta rota serve para quem quer manter o cadastro do ERP sincronizado com as contas da loja, como construtoras e revendas com tabela de preço própria.

Para ligar uma conta a uma tabela de preço, grave bcx_tabela_preco (ex.: revenda) no meta_data do cliente com PUT /customers/{id}. Logado, esse cliente vê e paga o preço da tabela dele em todo produto que tiver a tabela em bcx_tabelas_preco, e a página avisa que o preço da tabela foi aplicado.

Webhooks

A loja avisa o ERP no momento em que algo acontece, com um POST em JSON para o endereço que o ERP informar. Nós cadastramos os avisos na homologação. O corpo é o mesmo objeto que a API devolve, e o remetente se identifica como BCX-Brain-Webhook/1.7.

Validar a assinatura

Calcule o HMAC-SHA256 do corpo recebido, sem alterar nada, com o segredo do webhook, e compare com o cabeçalho. Se não bater, descarte.

const crypto = require('crypto');
const esperado = crypto.createHmac('sha256', SEGREDO_WEBHOOK)
  .update(corpoBruto).digest('base64');
if (esperado !== req.headers['x-bcx-signature']) return res.status(401).end();

$esperado = base64_encode(hash_hmac('sha256', $corpoBruto, SEGREDO_WEBHOOK, true));
if (!hash_equals($esperado, $_SERVER['HTTP_X_BCX_SIGNATURE'] ?? '')) { http_response_code(401); exit; }

using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(segredoWebhook));
var esperado = Convert.ToBase64String(hmac.ComputeHash(corpoBruto));
if (esperado != Request.Headers["X-Bcx-Signature"]) return Unauthorized();

Padrão de cadastro

O frete, a busca e o Google Shopping dependem do cadastro. Um produto sem peso, por exemplo, é cotado como se pesasse 1 kg, e a diferença aparece depois na conta da transportadora. Por isso o padrão abaixo é obrigatório.

Portão de entrada

Toda carga passa por uma conferência automática. O que é recusado volta 400 com a lista de motivos, e o produto mantém os dados anteriores. No lote, cada item tem o seu resultado: um item recusado não trava os outros. O que fica em conferência é gravado e marcado em bcx_conferencia.

Acima de 30 kg, de 100 cm no maior lado ou de 200 cm na soma dos lados, os Correios não levam. Esses produtos devem vir com bcx_nao_fracionavel = sim.

Homologação

A integração vai para a loja no ar depois de passar por este roteiro na loja de teste, com o nosso time acompanhando.

1. Carga do catálogo. Todos os produtos ativos do ERP entram pelo lote, sem recusa no portão.
2. Estoque e preço. Uma alteração feita no ERP aparece na loja dentro da frequência combinada.
3. Pedido pago no Pix. O pedido entra no ERP com cliente, itens, frete e desconto corretos.
4. Pedido de pessoa jurídica. CNPJ e inscrição estadual chegam nos campos certos.
5. Nota e rastreio. A NF-e e o código voltam para o pedido e o status vira completed.
6. Cancelamento. O pedido cancelado na loja é cancelado no ERP e o estoque volta.
7. Falha do aviso. Com o webhook desligado, a consulta periódica importa o pedido mesmo assim.

Erros

{
  "code": "bcx_cadastro_recusado",
  "message": "Cadastro recusado no portão de entrada: As três dimensões estão abaixo de 3: provável metro. Envie em centímetros.",
  "data": {
    "status": 400,
    "sku": "100245",
    "motivos": [ { "motivo": "dimensao_em_metro", "mensagem": "As três dimensões estão abaixo de 3: provável metro. Envie em centímetros." } ]
  }
}

Novidades da versão

Toda mudança na API entra numa versão nova e fica registrada aqui.

Suporte técnico

O nosso time acompanha a integração do primeiro teste até a loja no ar. Para dúvida técnica, credencial ou ambiente de teste, fale com o nosso time pelo mesmo canal em que você recebeu esta documentação, informando a empresa e o endereço da loja.