Developers
Referência da API · Cadastros

Cadastros

GET /stores

Listar lojas

Escopo stores.read

As lojas (e centros de distribuição) do cliente da chave. O code é o código de integração cadastrado no BIX: é por ele que os outros recursos identificam a loja.

Chave restrita a algumas lojas recebe só as lojas dela.

Parâmetros de consulta

store_code string · lista

Código de integração da loja.

Separe por vírgula, até 100 valores. Exemplo: 0012
updated_since string (data-hora)

Só registros alterados a partir desta data/hora (ISO 8601).

Exemplo: 2026-11-10T06:00:00-03:00
include_inactive boolean

Inclui os registros desativados (active: false). Use na sincronização incremental para saber o que saiu.

Padrão: false Exemplo: false
page integer

Página, começando em 1.

Padrão: 1 Exemplo: 1
page_size integer

Itens por página. Acima de 100 a chamada é recusada com invalid_parameter (não é cortada em silêncio).

Padrão: 50 Máximo: 100 Exemplo: 50

Sobre a resposta

  • kind: store (loja), dc (centro de distribuição) ou factory (fábrica).

  • code vazio: a loja não tem código de integração no BIX, e os filtros por store_code não a encontram. Peça ao administrador para cadastrar o mesmo código do ERP.

Erros possíveis

HTTPcodeQuando
401api_key_expiredA chave passou da data de expiração.
401api_key_revokedA chave foi revogada na Configuração Global › API.
401invalid_api_keyA chave não existe neste ambiente ou está errada.
401missing_api_keyA chamada veio sem o cabeçalho "Authorization: Bearer <chave>".
403insufficient_scopeA chave não tem o acesso que este endpoint exige.
429rate_limitedLimite de chamadas por minuto da chave atingido. Respeite o Retry-After.
500internal_errorErro interno. Tente de novo; se persistir, fale com o suporte.
 
curl -X GET "https://demonstracao.appbix.com.br/external-api/v1/stores?store_code=0012&updated_since=2026-11-10T06:00:00-03:00&page_size=100" \
  -H "Authorization: Bearer $BIX_API_KEY"
200 Resposta 
{
  "data": [
    {
      "id": 12,
      "code": "0012",
      "name": "Loja Centro",
      "cnpj": "12345678000190",
      "number": "12",
      "kind": "store",
      "active": true,
      "updated_at": "2026-11-10T08:30:00-03:00"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 50,
    "total_items": 1,
    "total_pages": 1,
    "has_next": false
  }
}
GET /products

Listar produtos

Escopo catalog.read

O cadastro de produtos do cliente. Cada código de barras é um item: o mesmo internal_code pode aparecer com vários ean (a unidade, a caixa, um EAN alternativo).

Ordem estável por id. Para sincronizar, use updated_since com include_inactive=true.

Parâmetros de consulta

internal_code string · lista

Código interno do produto.

Separe por vírgula, até 100 valores. Exemplo: 1001
ean string · lista

Código de barras.

Separe por vírgula, até 100 valores. Exemplo: 7891234567890
updated_since string (data-hora)

Só registros alterados a partir desta data/hora (ISO 8601).

Exemplo: 2026-11-10T06:00:00-03:00
include_inactive boolean

Inclui os registros desativados (active: false). Use na sincronização incremental para saber o que saiu.

Padrão: false Exemplo: false
page integer

Página, começando em 1.

Padrão: 1 Exemplo: 1
page_size integer

Itens por página. Acima de 100 a chamada é recusada com invalid_parameter (não é cortada em silêncio).

Padrão: 50 Máximo: 100 Exemplo: 50

Sobre a resposta

  • category: os códigos da estrutura mercadológica (ver GET /categories), nível a nível.

  • supplier e buyer são null quando o produto não tem fornecedor ou comprador.

Erros possíveis

HTTPcodeQuando
401api_key_expiredA chave passou da data de expiração.
401api_key_revokedA chave foi revogada na Configuração Global › API.
401invalid_api_keyA chave não existe neste ambiente ou está errada.
401missing_api_keyA chamada veio sem o cabeçalho "Authorization: Bearer <chave>".
403insufficient_scopeA chave não tem o acesso que este endpoint exige.
429rate_limitedLimite de chamadas por minuto da chave atingido. Respeite o Retry-After.
500internal_errorErro interno. Tente de novo; se persistir, fale com o suporte.
 
curl -X GET "https://demonstracao.appbix.com.br/external-api/v1/products?internal_code=1001&ean=7891234567890&page_size=100" \
  -H "Authorization: Bearer $BIX_API_KEY"
200 Resposta 
{
  "data": [
    {
      "internal_code": "1001",
      "ean": "7891234567890",
      "description": "ARROZ TIPO 1 5KG",
      "unit": "UN",
      "multiplier": 1,
      "price": 27.9,
      "category": {
        "n0": "",
        "n1": "01",
        "n2": "0105",
        "n3": "",
        "n4": ""
      },
      "reference_code": "",
      "color_code": "",
      "color_description": "",
      "size": "",
      "sales_curve": "A",
      "supplier": {
        "code": "12345678000190",
        "name": "Fornecedor Exemplo"
      },
      "buyer": {
        "code": "07",
        "name": "Comprador Mercearia"
      },
      "id": 345,
      "active": true,
      "updated_at": "2026-11-10T08:30:00-03:00"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 50,
    "total_items": 1,
    "total_pages": 1,
    "has_next": false
  }
}
POST /products

Enviar produtos (criar ou atualizar)

Escopo catalog.write

Cria ou atualiza produtos pela chave (internal_code, ean). Produto que já existe recebe só os campos enviados: o que não vier no item não é alterado. Para tirar um produto de linha, envie active: false.

Envie até 500 itens em {"items": [...]}. Use o cabeçalho Idempotency-Key para poder repetir a chamada (timeout, queda de rede) sem gravar duas vezes.

Corpo da requisição

Objeto JSON com items: uma lista de 1 a 500 itens. Cada item tem:

internal_code string obrigatório

Código interno no ERP.

Exemplo: 1001
ean string obrigatório

Código de barras. Com o internal_code, identifica o item.

Exemplo: 7891234567890
description string

Descrição.

Exemplo: ARROZ TIPO 1 5KG
unit string

Unidade de medida.

Exemplo: UN
multiplier integer

Quantas unidades este código de barras representa (caixa com 12 = 12).

Exemplo: 1
price number

Preço de cadastro. O preço por loja vai em POST /stock-prices.

Exemplo: 27.9
category object

Códigos da estrutura mercadológica, nível a nível (os mesmos de POST /categories).

n0 string

Código do nível N0.

n1 string

Código do nível N1.

n2 string

Código do nível N2.

n3 string

Código do nível N3.

n4 string

Código do nível N4.

reference_code string

Código de referência (informativo).

color_code string

Código da cor (informativo).

color_description string

Descrição da cor (informativo).

size string

Tamanho (informativo).

sales_curve string

Curva de venda da rede (A, B, C...).

Exemplo: A
supplier object

Fornecedor. Criado se não existir.

code string obrigatório

Código no ERP.

name string

Nome. Só preenche o cadastro que está sem nome.

buyer object

Comprador. Criado se não existir.

code string obrigatório

Código no ERP.

name string

Nome. Só preenche o cadastro que está sem nome.

active boolean

false tira o produto de linha; true reativa.

Exemplo: true

Aceita o cabeçalho Idempotency-Key: repetir a chamada com a mesma chave, em 24 horas, devolve a resposta da primeira sem gravar de novo. Ver Envio em lote e idempotência.

Sobre a resposta

  • A chamada responde 200 sempre que o lote foi processado, mesmo com itens recusados: confira o status de cada item em results (created, updated, skipped ou error).

  • results vem na ordem de items; index é a posição do item no lote, a partir de 0.

  • Item com erro não impede os outros: cada um é gravado ou recusado sozinho.

  • Item recusado traz code e detail (por exemplo, invalid_parameter com o campo e o motivo).

Erros possíveis

HTTPcodeQuando
400invalid_parameterParâmetro com valor inválido (o detail diz qual).
401api_key_expiredA chave passou da data de expiração.
401api_key_revokedA chave foi revogada na Configuração Global › API.
401invalid_api_keyA chave não existe neste ambiente ou está errada.
401missing_api_keyA chamada veio sem o cabeçalho "Authorization: Bearer <chave>".
403insufficient_scopeA chave não tem o acesso que este endpoint exige.
409idempotency_key_reusedO Idempotency-Key já foi usado, nas últimas 24 horas, numa chamada com outro corpo.
429rate_limitedLimite de chamadas por minuto da chave atingido. Respeite o Retry-After.
500internal_errorErro interno. Tente de novo; se persistir, fale com o suporte.
 
curl -X POST "https://demonstracao.appbix.com.br/external-api/v1/products" \
  -H "Authorization: Bearer $BIX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"items": [{"internal_code": "1001", "ean": "7891234567890", "description": "ARROZ TIPO 1 5KG", "unit": "UN", "multiplier": 1, "price": 27.9, "category": {"n0": "", "n1": "01", "n2": "0105", "n3": "", "n4": ""}, "sales_curve": "A", "supplier": {"code": "12345678000190", "name": "Fornecedor Exemplo"}}, {"internal_code": "1001", "ean": "17891234567897", "description": "ARROZ TIPO 1 5KG CX 6", "unit": "CX", "multiplier": 6}]}'
Corpo da requisição 
{
  "items": [
    {
      "internal_code": "1001",
      "ean": "7891234567890",
      "description": "ARROZ TIPO 1 5KG",
      "unit": "UN",
      "multiplier": 1,
      "price": 27.9,
      "category": {
        "n0": "",
        "n1": "01",
        "n2": "0105",
        "n3": "",
        "n4": ""
      },
      "sales_curve": "A",
      "supplier": {
        "code": "12345678000190",
        "name": "Fornecedor Exemplo"
      }
    },
    {
      "internal_code": "1001",
      "ean": "17891234567897",
      "description": "ARROZ TIPO 1 5KG CX 6",
      "unit": "CX",
      "multiplier": 6
    }
  ]
}
200 Resposta 
{
  "summary": {
    "total": 2,
    "created": 1,
    "updated": 1,
    "skipped": 0,
    "errors": 0
  },
  "results": [
    {
      "index": 0,
      "status": "updated",
      "id": 345,
      "code": null,
      "detail": null
    },
    {
      "index": 1,
      "status": "created",
      "id": 346,
      "code": null,
      "detail": null
    }
  ]
}
GET /categories

Listar a estrutura mercadológica

Escopo catalog.read

Os ramos da estrutura mercadológica do cliente, em até cinco níveis (n0 a n4, por exemplo Empresa › Departamento › Seção › Grupo › Subgrupo). Cada item é um ramo: a combinação dos códigos dos cinco níveis.

Parâmetros de consulta

updated_since string (data-hora)

Só registros alterados a partir desta data/hora (ISO 8601).

Exemplo: 2026-11-10T06:00:00-03:00
include_inactive boolean

Inclui os registros desativados (active: false). Use na sincronização incremental para saber o que saiu.

Padrão: false Exemplo: false
page integer

Página, começando em 1.

Padrão: 1 Exemplo: 1
page_size integer

Itens por página. Acima de 100 a chamada é recusada com invalid_parameter (não é cortada em silêncio).

Padrão: 50 Máximo: 100 Exemplo: 50

Erros possíveis

HTTPcodeQuando
401api_key_expiredA chave passou da data de expiração.
401api_key_revokedA chave foi revogada na Configuração Global › API.
401invalid_api_keyA chave não existe neste ambiente ou está errada.
401missing_api_keyA chamada veio sem o cabeçalho "Authorization: Bearer <chave>".
403insufficient_scopeA chave não tem o acesso que este endpoint exige.
429rate_limitedLimite de chamadas por minuto da chave atingido. Respeite o Retry-After.
500internal_errorErro interno. Tente de novo; se persistir, fale com o suporte.
 
curl -X GET "https://demonstracao.appbix.com.br/external-api/v1/categories?updated_since=2026-11-10T06:00:00-03:00&include_inactive=false&page_size=100" \
  -H "Authorization: Bearer $BIX_API_KEY"
200 Resposta 
{
  "data": [
    {
      "n0": {
        "code": "",
        "name": ""
      },
      "n1": {
        "code": "01",
        "name": "MERCEARIA"
      },
      "n2": {
        "code": "0105",
        "name": "ARROZ E FEIJÃO"
      },
      "n3": {
        "code": "",
        "name": ""
      },
      "n4": {
        "code": "",
        "name": ""
      },
      "id": 88,
      "active": true,
      "updated_at": "2026-11-10T08:30:00-03:00"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 50,
    "total_items": 1,
    "total_pages": 1,
    "has_next": false
  }
}
POST /categories

Enviar a estrutura mercadológica

Escopo catalog.write

Cria ou atualiza ramos da estrutura. A chave é a combinação dos códigos dos cinco níveis: o mesmo ramo enviado de novo só atualiza os nomes. Nível que não existe no seu ERP pode ser omitido.

Envie até 500 itens em {"items": [...]}. Use o cabeçalho Idempotency-Key para poder repetir a chamada (timeout, queda de rede) sem gravar duas vezes.

Corpo da requisição

Objeto JSON com items: uma lista de 1 a 500 itens. Cada item tem:

n0 object

Nível N0 do ramo.

code string obrigatório

Código do nível no ERP.

name string

Nome do nível.

n1 object

Nível N1 do ramo.

code string obrigatório

Código do nível no ERP.

name string

Nome do nível.

n2 object

Nível N2 do ramo.

code string obrigatório

Código do nível no ERP.

name string

Nome do nível.

n3 object

Nível N3 do ramo.

code string obrigatório

Código do nível no ERP.

name string

Nome do nível.

n4 object

Nível N4 do ramo.

code string obrigatório

Código do nível no ERP.

name string

Nome do nível.

Aceita o cabeçalho Idempotency-Key: repetir a chamada com a mesma chave, em 24 horas, devolve a resposta da primeira sem gravar de novo. Ver Envio em lote e idempotência.

Sobre a resposta

  • A chamada responde 200 sempre que o lote foi processado, mesmo com itens recusados: confira o status de cada item em results (created, updated, skipped ou error).

  • results vem na ordem de items; index é a posição do item no lote, a partir de 0.

  • Item com erro não impede os outros: cada um é gravado ou recusado sozinho.

Erros possíveis

HTTPcodeQuando
400invalid_parameterParâmetro com valor inválido (o detail diz qual).
401api_key_expiredA chave passou da data de expiração.
401api_key_revokedA chave foi revogada na Configuração Global › API.
401invalid_api_keyA chave não existe neste ambiente ou está errada.
401missing_api_keyA chamada veio sem o cabeçalho "Authorization: Bearer <chave>".
403insufficient_scopeA chave não tem o acesso que este endpoint exige.
409idempotency_key_reusedO Idempotency-Key já foi usado, nas últimas 24 horas, numa chamada com outro corpo.
429rate_limitedLimite de chamadas por minuto da chave atingido. Respeite o Retry-After.
500internal_errorErro interno. Tente de novo; se persistir, fale com o suporte.
 
curl -X POST "https://demonstracao.appbix.com.br/external-api/v1/categories" \
  -H "Authorization: Bearer $BIX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"items": [{"n1": {"code": "01", "name": "MERCEARIA"}, "n2": {"code": "0105", "name": "ARROZ E FEIJÃO"}}, {"n1": {"code": "01", "name": "MERCEARIA"}, "n2": {"code": "0106", "name": "MASSAS"}}]}'
Corpo da requisição 
{
  "items": [
    {
      "n1": {
        "code": "01",
        "name": "MERCEARIA"
      },
      "n2": {
        "code": "0105",
        "name": "ARROZ E FEIJÃO"
      }
    },
    {
      "n1": {
        "code": "01",
        "name": "MERCEARIA"
      },
      "n2": {
        "code": "0106",
        "name": "MASSAS"
      }
    }
  ]
}
200 Resposta 
{
  "summary": {
    "total": 2,
    "created": 1,
    "updated": 1,
    "skipped": 0,
    "errors": 0
  },
  "results": [
    {
      "index": 0,
      "status": "updated",
      "id": 88,
      "code": null,
      "detail": null
    },
    {
      "index": 1,
      "status": "created",
      "id": 89,
      "code": null,
      "detail": null
    }
  ]
}
GET /stock-prices

Listar preço e saldo por loja

Escopo stock_prices.read

O preço e o saldo de cada produto em cada loja, como o ERP informou (por depósito, quando o ERP separa). É o saldo do ERP, não o do WMS do BIX: para esse, use GET /wms/stock-balances.

Ordem estável por id.

Parâmetros de consulta

store_code string · lista

Código de integração da loja.

Separe por vírgula, até 100 valores. Exemplo: 0012
store_id integer · lista

Id da loja no BIX.

Separe por vírgula, até 100 valores. Exemplo: 12
internal_code string · lista

Código interno do produto.

Separe por vírgula, até 100 valores. Exemplo: 1001
ean string · lista

Código de barras.

Separe por vírgula, até 100 valores. Exemplo: 7891234567890
warehouse string

Depósito, como o ERP envia.

Exemplo: 01
page integer

Página, começando em 1.

Padrão: 1 Exemplo: 1
page_size integer

Itens por página. Acima de 100 a chamada é recusada com invalid_parameter (não é cortada em silêncio).

Padrão: 50 Máximo: 100 Exemplo: 50

Sobre a resposta

  • price_offer é null quando não há oferta. Custo nunca informado vem 0.

  • updated_at é informativo: a carga em lote do BIX não o atualiza em toda linha.

  • Sem filtro por data de alteração: a carga em lote do BIX não marca a hora em toda linha, e um updated_since aqui perderia mudanças. Leia por loja.

Erros possíveis

HTTPcodeQuando
401api_key_expiredA chave passou da data de expiração.
401api_key_revokedA chave foi revogada na Configuração Global › API.
401invalid_api_keyA chave não existe neste ambiente ou está errada.
401missing_api_keyA chamada veio sem o cabeçalho "Authorization: Bearer <chave>".
403insufficient_scopeA chave não tem o acesso que este endpoint exige.
429rate_limitedLimite de chamadas por minuto da chave atingido. Respeite o Retry-After.
500internal_errorErro interno. Tente de novo; se persistir, fale com o suporte.
 
curl -X GET "https://demonstracao.appbix.com.br/external-api/v1/stock-prices?store_code=0012&store_id=12&page_size=100" \
  -H "Authorization: Bearer $BIX_API_KEY"
200 Resposta 
{
  "data": [
    {
      "id": 5012,
      "store": {
        "id": 12,
        "code": "0012",
        "name": "Loja Centro"
      },
      "product": {
        "id": 345,
        "internal_code": "1001",
        "ean": "7891234567890",
        "description": "ARROZ TIPO 1 5KG"
      },
      "warehouse": "01",
      "balance": 48.0,
      "price": 27.9,
      "price_regular": 29.9,
      "price_offer": 27.9,
      "curve": "A",
      "costs": {
        "average_accounting": 18.4,
        "average_no_tax": 16.9,
        "average_with_tax": 19.2,
        "last_purchase_gross": 20.5,
        "last_purchase_net": 17.8
      },
      "updated_at": "2026-11-10T08:30:00-03:00"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 50,
    "total_items": 1,
    "total_pages": 1,
    "has_next": false
  }
}
POST /stock-prices

Enviar preço e saldo por loja

Escopo stock_prices.write

Cria ou atualiza o preço e o saldo de produtos por loja, pela chave (loja, produto, depósito). É parcial: campo ausente não é alterado, então uma carga de preço e outra de saldo não apagam uma à outra.

A loja vem por store_code (código de integração) ou store_id; o produto, por ean ou internal_code. Um internal_code com vários EANs atualiza todos eles.

update_only: true só atualiza o que já existe: sem registro na loja, o item volta skipped. Use em carga que não traz preço nem saldo (só a curva, por exemplo), para não criar linha zerada.

Envie até 500 itens em {"items": [...]}. Use o cabeçalho Idempotency-Key para poder repetir a chamada (timeout, queda de rede) sem gravar duas vezes.

Corpo da requisição

Objeto JSON com items: uma lista de 1 a 500 itens. Cada item tem:

store_code string

Código de integração da loja. Ou store_id.

Exemplo: 0012
store_id integer

Id da loja no BIX. Ou store_code.

ean string

Código de barras. Ou internal_code.

internal_code string

Código interno. Ou ean.

Exemplo: 1001
warehouse string

Depósito no ERP. Vazio quando o ERP não separa.

Exemplo: 01
balance number

Saldo.

Exemplo: 48
price number

Preço de venda praticado.

Exemplo: 27.9
price_regular number

Preço regular (sem oferta). Tem prioridade na rebaixa.

Exemplo: 29.9
price_offer number

Preço de oferta. null encerra a oferta.

Exemplo: 27.9
curve string

Curva do produto na loja (até 50 caracteres). Vazio limpa.

Exemplo: A
costs object

Custos (opcionais).

average_accounting number

Custo médio contábil.

average_no_tax number

Custo médio sem impostos.

average_with_tax number

Custo médio com impostos.

last_purchase_gross number

Custo da última compra, bruto.

last_purchase_net number

Custo da última compra, líquido.

update_only boolean

Só atualiza registro existente.

Exemplo: false

Aceita o cabeçalho Idempotency-Key: repetir a chamada com a mesma chave, em 24 horas, devolve a resposta da primeira sem gravar de novo. Ver Envio em lote e idempotência.

Sobre a resposta

  • A chamada responde 200 sempre que o lote foi processado, mesmo com itens recusados: confira o status de cada item em results (created, updated, skipped ou error).

  • results vem na ordem de items; index é a posição do item no lote, a partir de 0.

  • Item com erro não impede os outros: cada um é gravado ou recusado sozinho.

  • store_not_allowed: a chave está restrita a algumas lojas e o item é de outra.

Erros possíveis

HTTPcodeQuando
400invalid_parameterParâmetro com valor inválido (o detail diz qual).
401api_key_expiredA chave passou da data de expiração.
401api_key_revokedA chave foi revogada na Configuração Global › API.
401invalid_api_keyA chave não existe neste ambiente ou está errada.
401missing_api_keyA chamada veio sem o cabeçalho "Authorization: Bearer <chave>".
403insufficient_scopeA chave não tem o acesso que este endpoint exige.
403store_not_allowedA chave está restrita a algumas lojas e uma das pedidas não é delas.
409idempotency_key_reusedO Idempotency-Key já foi usado, nas últimas 24 horas, numa chamada com outro corpo.
429rate_limitedLimite de chamadas por minuto da chave atingido. Respeite o Retry-After.
500internal_errorErro interno. Tente de novo; se persistir, fale com o suporte.
 
curl -X POST "https://demonstracao.appbix.com.br/external-api/v1/stock-prices" \
  -H "Authorization: Bearer $BIX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"items": [{"store_code": "0012", "internal_code": "1001", "warehouse": "01", "balance": 48, "price": 27.9, "price_regular": 29.9}, {"store_code": "0012", "internal_code": "1001", "warehouse": "01", "curve": "A", "update_only": true}]}'
Corpo da requisição 
{
  "items": [
    {
      "store_code": "0012",
      "internal_code": "1001",
      "warehouse": "01",
      "balance": 48,
      "price": 27.9,
      "price_regular": 29.9
    },
    {
      "store_code": "0012",
      "internal_code": "1001",
      "warehouse": "01",
      "curve": "A",
      "update_only": true
    }
  ]
}
200 Resposta 
{
  "summary": {
    "total": 2,
    "created": 1,
    "updated": 1,
    "skipped": 0,
    "errors": 0
  },
  "results": [
    {
      "index": 0,
      "status": "created",
      "code": null,
      "detail": null
    },
    {
      "index": 1,
      "status": "updated",
      "code": null,
      "detail": null
    }
  ]
}
GET /suppliers

Listar fornecedores

Escopo catalog.read

Os fornecedores do cliente. O code é o código do fornecedor no ERP (em geral o CNPJ) e é o mesmo que o produto usa em supplier.code.

Parâmetros de consulta

code string · lista

Código no ERP.

Separe por vírgula, até 100 valores. Exemplo: 12345678000190
updated_since string (data-hora)

Só registros alterados a partir desta data/hora (ISO 8601).

Exemplo: 2026-11-10T06:00:00-03:00
include_inactive boolean

Inclui os registros desativados (active: false). Use na sincronização incremental para saber o que saiu.

Padrão: false Exemplo: false
page integer

Página, começando em 1.

Padrão: 1 Exemplo: 1
page_size integer

Itens por página. Acima de 100 a chamada é recusada com invalid_parameter (não é cortada em silêncio).

Padrão: 50 Máximo: 100 Exemplo: 50

Erros possíveis

HTTPcodeQuando
401api_key_expiredA chave passou da data de expiração.
401api_key_revokedA chave foi revogada na Configuração Global › API.
401invalid_api_keyA chave não existe neste ambiente ou está errada.
401missing_api_keyA chamada veio sem o cabeçalho "Authorization: Bearer <chave>".
403insufficient_scopeA chave não tem o acesso que este endpoint exige.
429rate_limitedLimite de chamadas por minuto da chave atingido. Respeite o Retry-After.
500internal_errorErro interno. Tente de novo; se persistir, fale com o suporte.
 
curl -X GET "https://demonstracao.appbix.com.br/external-api/v1/suppliers?code=12345678000190&updated_since=2026-11-10T06:00:00-03:00&page_size=100" \
  -H "Authorization: Bearer $BIX_API_KEY"
200 Resposta 
{
  "data": [
    {
      "id": 31,
      "code": "12345678000190",
      "legal_name": "FORNECEDOR EXEMPLO LTDA",
      "trade_name": "Exemplo",
      "active": true,
      "updated_at": "2026-11-10T08:30:00-03:00"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 50,
    "total_items": 1,
    "total_pages": 1,
    "has_next": false
  }
}
POST /suppliers

Enviar fornecedores

Escopo catalog.write

Cria ou atualiza fornecedores pelo code. Aqui o ERP é a fonte: o nome enviado substitui o que está no BIX. Campo ausente não é alterado.

Envie até 500 itens em {"items": [...]}. Use o cabeçalho Idempotency-Key para poder repetir a chamada (timeout, queda de rede) sem gravar duas vezes.

Corpo da requisição

Objeto JSON com items: uma lista de 1 a 500 itens. Cada item tem:

code string obrigatório

Código do fornecedor no ERP (em geral o CNPJ).

Exemplo: 12345678000190
legal_name string

Razão social.

Exemplo: FORNECEDOR EXEMPLO LTDA
trade_name string

Nome fantasia.

Exemplo: Exemplo
active boolean

false desativa.

Exemplo: true

Aceita o cabeçalho Idempotency-Key: repetir a chamada com a mesma chave, em 24 horas, devolve a resposta da primeira sem gravar de novo. Ver Envio em lote e idempotência.

Sobre a resposta

  • A chamada responde 200 sempre que o lote foi processado, mesmo com itens recusados: confira o status de cada item em results (created, updated, skipped ou error).

  • results vem na ordem de items; index é a posição do item no lote, a partir de 0.

  • Item com erro não impede os outros: cada um é gravado ou recusado sozinho.

Erros possíveis

HTTPcodeQuando
400invalid_parameterParâmetro com valor inválido (o detail diz qual).
401api_key_expiredA chave passou da data de expiração.
401api_key_revokedA chave foi revogada na Configuração Global › API.
401invalid_api_keyA chave não existe neste ambiente ou está errada.
401missing_api_keyA chamada veio sem o cabeçalho "Authorization: Bearer <chave>".
403insufficient_scopeA chave não tem o acesso que este endpoint exige.
409idempotency_key_reusedO Idempotency-Key já foi usado, nas últimas 24 horas, numa chamada com outro corpo.
429rate_limitedLimite de chamadas por minuto da chave atingido. Respeite o Retry-After.
500internal_errorErro interno. Tente de novo; se persistir, fale com o suporte.
 
curl -X POST "https://demonstracao.appbix.com.br/external-api/v1/suppliers" \
  -H "Authorization: Bearer $BIX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"items": [{"code": "12345678000190", "legal_name": "FORNECEDOR EXEMPLO LTDA", "trade_name": "Exemplo"}]}'
Corpo da requisição 
{
  "items": [
    {
      "code": "12345678000190",
      "legal_name": "FORNECEDOR EXEMPLO LTDA",
      "trade_name": "Exemplo"
    }
  ]
}
200 Resposta 
{
  "summary": {
    "total": 1,
    "created": 1,
    "updated": 0,
    "skipped": 0,
    "errors": 0
  },
  "results": [
    {
      "index": 0,
      "status": "created",
      "id": 31,
      "code": null,
      "detail": null
    }
  ]
}
GET /buyers

Listar compradores

Escopo catalog.read

Os compradores do cliente. O code é o mesmo que o produto usa em buyer.code.

Parâmetros de consulta

code string · lista

Código do comprador no ERP.

Separe por vírgula, até 100 valores. Exemplo: 07
updated_since string (data-hora)

Só registros alterados a partir desta data/hora (ISO 8601).

Exemplo: 2026-11-10T06:00:00-03:00
include_inactive boolean

Inclui os registros desativados (active: false). Use na sincronização incremental para saber o que saiu.

Padrão: false Exemplo: false
page integer

Página, começando em 1.

Padrão: 1 Exemplo: 1
page_size integer

Itens por página. Acima de 100 a chamada é recusada com invalid_parameter (não é cortada em silêncio).

Padrão: 50 Máximo: 100 Exemplo: 50

Erros possíveis

HTTPcodeQuando
401api_key_expiredA chave passou da data de expiração.
401api_key_revokedA chave foi revogada na Configuração Global › API.
401invalid_api_keyA chave não existe neste ambiente ou está errada.
401missing_api_keyA chamada veio sem o cabeçalho "Authorization: Bearer <chave>".
403insufficient_scopeA chave não tem o acesso que este endpoint exige.
429rate_limitedLimite de chamadas por minuto da chave atingido. Respeite o Retry-After.
500internal_errorErro interno. Tente de novo; se persistir, fale com o suporte.
 
curl -X GET "https://demonstracao.appbix.com.br/external-api/v1/buyers?code=07&updated_since=2026-11-10T06:00:00-03:00&page_size=100" \
  -H "Authorization: Bearer $BIX_API_KEY"
200 Resposta 
{
  "data": [
    {
      "id": 7,
      "code": "07",
      "name": "COMPRADOR MERCEARIA",
      "active": true,
      "updated_at": "2026-11-10T08:30:00-03:00"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 50,
    "total_items": 1,
    "total_pages": 1,
    "has_next": false
  }
}
POST /buyers

Enviar compradores

Escopo catalog.write

Cria ou atualiza compradores pelo code. O nome enviado substitui o que está no BIX.

Envie até 500 itens em {"items": [...]}. Use o cabeçalho Idempotency-Key para poder repetir a chamada (timeout, queda de rede) sem gravar duas vezes.

Corpo da requisição

Objeto JSON com items: uma lista de 1 a 500 itens. Cada item tem:

code string obrigatório

Código do comprador no ERP.

Exemplo: 07
name string

Nome.

Exemplo: COMPRADOR MERCEARIA
active boolean

false desativa.

Exemplo: true

Aceita o cabeçalho Idempotency-Key: repetir a chamada com a mesma chave, em 24 horas, devolve a resposta da primeira sem gravar de novo. Ver Envio em lote e idempotência.

Sobre a resposta

  • A chamada responde 200 sempre que o lote foi processado, mesmo com itens recusados: confira o status de cada item em results (created, updated, skipped ou error).

  • results vem na ordem de items; index é a posição do item no lote, a partir de 0.

  • Item com erro não impede os outros: cada um é gravado ou recusado sozinho.

Erros possíveis

HTTPcodeQuando
400invalid_parameterParâmetro com valor inválido (o detail diz qual).
401api_key_expiredA chave passou da data de expiração.
401api_key_revokedA chave foi revogada na Configuração Global › API.
401invalid_api_keyA chave não existe neste ambiente ou está errada.
401missing_api_keyA chamada veio sem o cabeçalho "Authorization: Bearer <chave>".
403insufficient_scopeA chave não tem o acesso que este endpoint exige.
409idempotency_key_reusedO Idempotency-Key já foi usado, nas últimas 24 horas, numa chamada com outro corpo.
429rate_limitedLimite de chamadas por minuto da chave atingido. Respeite o Retry-After.
500internal_errorErro interno. Tente de novo; se persistir, fale com o suporte.
 
curl -X POST "https://demonstracao.appbix.com.br/external-api/v1/buyers" \
  -H "Authorization: Bearer $BIX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"items": [{"code": "07", "name": "COMPRADOR MERCEARIA"}]}'
Corpo da requisição 
{
  "items": [
    {
      "code": "07",
      "name": "COMPRADOR MERCEARIA"
    }
  ]
}
200 Resposta 
{
  "summary": {
    "total": 1,
    "created": 1,
    "updated": 0,
    "skipped": 0,
    "errors": 0
  },
  "results": [
    {
      "index": 0,
      "status": "created",
      "id": 31,
      "code": null,
      "detail": null
    }
  ]
}
GET /store-groups

Listar grupos de lojas

Escopo stores.read

Os grupos de lojas do cliente (regional, bandeira, cluster), usados para agendar tarefas e filtrar relatórios por um conjunto de lojas.

Parâmetros de consulta

updated_since string (data-hora)

Só registros alterados a partir desta data/hora (ISO 8601).

Exemplo: 2026-11-10T06:00:00-03:00
include_inactive boolean

Inclui os registros desativados (active: false). Use na sincronização incremental para saber o que saiu.

Padrão: false Exemplo: false
page integer

Página, começando em 1.

Padrão: 1 Exemplo: 1
page_size integer

Itens por página. Acima de 100 a chamada é recusada com invalid_parameter (não é cortada em silêncio).

Padrão: 50 Máximo: 100 Exemplo: 50

Erros possíveis

HTTPcodeQuando
401api_key_expiredA chave passou da data de expiração.
401api_key_revokedA chave foi revogada na Configuração Global › API.
401invalid_api_keyA chave não existe neste ambiente ou está errada.
401missing_api_keyA chamada veio sem o cabeçalho "Authorization: Bearer <chave>".
403insufficient_scopeA chave não tem o acesso que este endpoint exige.
429rate_limitedLimite de chamadas por minuto da chave atingido. Respeite o Retry-After.
500internal_errorErro interno. Tente de novo; se persistir, fale com o suporte.
 
curl -X GET "https://demonstracao.appbix.com.br/external-api/v1/store-groups?updated_since=2026-11-10T06:00:00-03:00&include_inactive=false&page_size=100" \
  -H "Authorization: Bearer $BIX_API_KEY"
200 Resposta 
{
  "data": [
    {
      "id": 4,
      "name": "REGIONAL SUL",
      "description": "Lojas do RS e SC",
      "stores": [
        {
          "id": 12,
          "code": "0012",
          "name": "Loja Centro"
        }
      ],
      "active": true,
      "updated_at": "2026-11-10T08:30:00-03:00"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 50,
    "total_items": 1,
    "total_pages": 1,
    "has_next": false
  }
}
POST /store-groups

Enviar grupos de lojas

Escopo store_groups.write

Cria ou atualiza grupos pelo nome (sem diferenciar maiúsculas). stores, quando enviado, substitui as lojas do grupo: mande a lista completa.

Envie até 500 itens em {"items": [...]}. Use o cabeçalho Idempotency-Key para poder repetir a chamada (timeout, queda de rede) sem gravar duas vezes.

Corpo da requisição

Objeto JSON com items: uma lista de 1 a 500 itens. Cada item tem:

name string obrigatório

Nome do grupo (é a chave).

Exemplo: REGIONAL SUL
description string

Descrição.

Exemplo: Lojas do RS e SC
stores array

Códigos de integração das lojas do grupo (lista completa).

Exemplo: ['0012', '0020']
active boolean

false desativa.

Exemplo: true

Aceita o cabeçalho Idempotency-Key: repetir a chamada com a mesma chave, em 24 horas, devolve a resposta da primeira sem gravar de novo. Ver Envio em lote e idempotência.

Sobre a resposta

  • A chamada responde 200 sempre que o lote foi processado, mesmo com itens recusados: confira o status de cada item em results (created, updated, skipped ou error).

  • results vem na ordem de items; index é a posição do item no lote, a partir de 0.

  • Item com erro não impede os outros: cada um é gravado ou recusado sozinho.

Erros possíveis

HTTPcodeQuando
400invalid_parameterParâmetro com valor inválido (o detail diz qual).
401api_key_expiredA chave passou da data de expiração.
401api_key_revokedA chave foi revogada na Configuração Global › API.
401invalid_api_keyA chave não existe neste ambiente ou está errada.
401missing_api_keyA chamada veio sem o cabeçalho "Authorization: Bearer <chave>".
403insufficient_scopeA chave não tem o acesso que este endpoint exige.
409idempotency_key_reusedO Idempotency-Key já foi usado, nas últimas 24 horas, numa chamada com outro corpo.
429rate_limitedLimite de chamadas por minuto da chave atingido. Respeite o Retry-After.
500internal_errorErro interno. Tente de novo; se persistir, fale com o suporte.
 
curl -X POST "https://demonstracao.appbix.com.br/external-api/v1/store-groups" \
  -H "Authorization: Bearer $BIX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"items": [{"name": "REGIONAL SUL", "description": "Lojas do RS e SC", "stores": ["0012", "0020"]}]}'
Corpo da requisição 
{
  "items": [
    {
      "name": "REGIONAL SUL",
      "description": "Lojas do RS e SC",
      "stores": [
        "0012",
        "0020"
      ]
    }
  ]
}
200 Resposta 
{
  "summary": {
    "total": 1,
    "created": 1,
    "updated": 0,
    "skipped": 0,
    "errors": 0
  },
  "results": [
    {
      "index": 0,
      "status": "created",
      "id": 31,
      "code": null,
      "detail": null
    }
  ]
}