API de Produtos

Gerencie o cadastro de produtos do Bunto ERP. Este endpoint permite listar, consultar, criar, atualizar e excluir produtos da sua empresa via API.

Base URL

Produção:

https://api-backend.bunto.com.br/v1/produtos/

---

Autenticação

Todas as requisições exigem um Token de API no header Authorization:

Authorization: Bearer bnt_seu_token_aqui

---

Endpoints

Listar Produtos

GET /v1/produtos/

Escopo necessário: produtos: read

Retorna a lista paginada de produtos ativos da empresa.

Query Parameters

Exemplo com cURL

bash
curl 'https://api-backend.bunto.com.br/v1/produtos/?pagina=1&por_pagina=10&busca=camiseta&ordenar=preco&direcao=desc' \
  -H 'Authorization: Bearer bnt_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9t0U1v2W3x4' \
  -H 'Content-Type: application/json'

Exemplo com Python

python
import requests

BASE_URL = "https://api-backend.bunto.com.br/v1"
TOKEN = "bnt_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9t0U1v2W3x4"

headers = {
    "Authorization": f"Bearer {TOKEN}",
    "Content-Type": "application/json",
}

# Listar produtos com filtros
resposta = requests.get(
    f"{BASE_URL}/produtos/",
    headers=headers,
    params={
        "pagina": 1,
        "por_pagina": 25,
        "situacao":"A",
        "ordenar": "nome",
        "direcao": "asc",
    },
)

dados = resposta.json()

if dados["success"]:
    produtos = dados["data"]["resultados"]
    paginacao = dados["data"]["paginacao"]
    print(f"Total de produtos: {paginacao['total_registros']}")
    for produto in produtos:
        print(f"  - [{produto['codigo']}] {produto['nome']} - R$ {produto['preco']}")
else:
    print(f"Erro: {resposta.status_code}")

Exemplo com JavaScript

javascript
const BASE_URL = "https://api-backend.bunto.com.br/v1";
const TOKEN = "bnt_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9t0U1v2W3x4";

const params = new URLSearchParams({
  pagina: "1",
  por_pagina: "25",
  situacao: "A",
  ordenar: "nome",
  direcao: "asc",
});

const resposta = await fetch(`${BASE_URL}/produtos/?${params}`, {
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
  },
});

const dados = await resposta.json();

if (dados.success) {
  const produtos = dados.data.resultados;
  const paginacao = dados.data.paginacao;
  console.log(`Total de produtos: ${paginacao.total_registros}`);
  produtos.forEach((produto) => {
    console.log(`  - [${produto.codigo}] ${produto.nome} - R$ ${produto.preco}`);
  });
} else {
  console.error(`Erro: ${resposta.status}`);
}

Resposta (200 OK)

json
{
  "success": true,
  "message": "142 registros encontrados",
  "data": {
    "resultados": [
      {
        "id": 1,
        "nome": "Camiseta Basica Algodão",
        "codigo":"CAM-001",
        "gtin": "7891234560012",
        "unidade": "UN",
        "marca": "Hering",
        "preco":"49.9000000000",
        "preco_custo": "22.5000000000",
        "preco_promocional": null,
        "formato": "S",
        "situacao":"A",
        "controlar_estoque": true,
        "ativo": true,
        "categoria_nome": "Vestuário",
        "criado_em": "2026-01-15T10:30:00-03:00",
        "atualizado_em": "2026-02-10T14:22:00-03:00"
      },
      {
        "id": 2,
        "nome": "Bermuda Jeans Masculina",
        "codigo":"BER-002",
        "gtin": "7891234560029",
        "unidade": "UN",
        "marca": "Colcci",
        "preco":"129.9000000000",
        "preco_custo": "65.0000000000",
        "preco_promocional": "99.9000000000",
        "formato": "V",
        "situacao":"A",
        "controlar_estoque": true,
        "ativo": true,
        "categoria_nome": "Vestuário",
        "criado_em": "2026-01-20T09:15:00-03:00",
        "atualizado_em": "2026-02-11T08:45:00-03:00"
      }
    ],
    "paginacao": {
      "pagina_atual": 1,
      "total_paginas": 6,
      "total_registros": 142,
      "por_pagina": 25,
      "proxima": "https://api-backend.bunto.com.br/v1/produtos/?pagina=2",
      "anterior": null
    }
  }
}

Campos da Listagem

---

Obter Produto

GET /v1/produtos/{id}/

Escopo necessário: produtos: read

Retorna os dados completos de um produto específico, incluindo dimensões, dados fiscais e estoque.

Exemplo com cURL

bash
curl https://api-backend.bunto.com.br/v1/produtos/1/ \
  -H 'Authorization: Bearer bnt_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9t0U1v2W3x4' \
  -H 'Content-Type: application/json'

Exemplo com Python

python
import requests

BASE_URL = "https://api-backend.bunto.com.br/v1"
TOKEN = "bnt_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9t0U1v2W3x4"

headers = {
    "Authorization": f"Bearer {TOKEN}",
    "Content-Type": "application/json",
}

produto_id = 1
resposta = requests.get(f"{BASE_URL}/produtos/{produto_id}/", headers=headers)
dados = resposta.json()

if dados["success"]:
    produto = dados["data"]
    print(f"Produto: {produto['nome']}")
    print(f"Preco: R$ {produto['preco']}")
    print(f"Estoque: {produto['estoque_total']}")
    if produto["fiscal"]:
        print(f"NCM: {produto['fiscal']['ncm']}")
else:
    print(f"Erro: {dados}")

Exemplo com JavaScript

javascript
const BASE_URL = "https://api-backend.bunto.com.br/v1";
const TOKEN = "bnt_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9t0U1v2W3x4";

const produtoId = 1;

const resposta = await fetch(`${BASE_URL}/produtos/${produtoId}/`, {
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
  },
});

const dados = await resposta.json();

if (dados.success) {
  const produto = dados.data;
  console.log(`Produto: ${produto.nome}`);
  console.log(`Preco: R$ ${produto.preco}`);
  console.log(`Estoque: ${produto.estoque_total}`);
  if (produto.fiscal) {
    console.log(`NCM: ${produto.fiscal.ncm}`);
  }
} else {
  console.error(`Erro: ${JSON.stringify(dados)}`);
}

Resposta (200 OK)

json
{
  "success": true,
  "message": "Registro encontrado",
  "data": {
    "id": 1,
    "nome": "Camiseta Basica Algodão",
    "codigo":"CAM-001",
    "gtin": "7891234560012",
    "unidade": "UN",
    "marca": "Hering",
    "preco":"49.9000000000",
    "preco_custo": "22.5000000000",
    "preco_promocional": null,
    "formato": "S",
    "situacao":"A",
    "controlar_estoque": true,
    "ativo": true,
    "categoria_nome": "Vestuário",
    "criado_em": "2026-01-15T10:30:00-03:00",
    "atualizado_em": "2026-02-10T14:22:00-03:00",
    "fantasia": "Camiseta Basica Algodão",
    "descricao_curta": "Camiseta basica 100% algodão, confortável para uso diário.",
    "descricao_complementar": "Tecido penteado 30.1, costura reforçada, etiqueta interna em serigrafia.",
    "observacoes":null,
    "condicao": "1",
    "tipo_producao": "P",
    "markup": "1.2178",
    "peso_liquido": "0.180",
    "peso_bruto": "0.220",
    "largura": "30.000",
    "altura": "2.000",
    "profundidade": "25.000",
    "estoque_total": "154",
    "fiscal": {
      "ncm": "61051000",
      "cest": "2800100",
      "origem": "0",
      "tipo_item_sped": "00",
      "gtin_tributario": null
    }
  }
}

Campos do Detalhe (adicionais à listagem)

Objeto fiscal

---

Criar Produto

POST /v1/produtos/

Escopo necessário: produtos: write

Cria um novo produto na empresa do token autenticado.

Campos do Request Body

Exemplo com cURL

bash
curl -X POST https://api-backend.bunto.com.br/v1/produtos/ \
  -H 'Authorization: Bearer bnt_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9t0U1v2W3x4' \
  -H 'Content-Type: application/json' \
  -d '{
    "nome": "Tênis Esportivo Running Pro",
    "codigo":"TEN-045",
    "gtin": "7891234560098",
    "unidade": "PAR",
    "marca": "Olympikus",
    "preco":299.90,
    "preco_custo": 145.00,
    "formato": "S",
    "situacao":"A",
    "condicao": "1",
    "controlar_estoque": true,
    "descricao_curta": "Tênis esportivo para corrida com amortecimento em gel.",
    "peso_liquido": 0.320,
    "peso_bruto": 0.580,
    "largura": 35.0,
    "altura": 15.0,
    "profundidade": 12.0,
    "garantia_meses": 3,
    "categoria_id": 5
  }'

Exemplo com Python

python
import requests

BASE_URL = "https://api-backend.bunto.com.br/v1"
TOKEN = "bnt_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9t0U1v2W3x4"

headers = {
    "Authorization": f"Bearer {TOKEN}",
    "Content-Type": "application/json",
}

novo_produto = {
    "nome": "Tênis Esportivo Running Pro",
    "codigo":"TEN-045",
    "gtin": "7891234560098",
    "unidade": "PAR",
    "marca": "Olympikus",
    "preco":299.90,
    "preco_custo": 145.00,
    "formato": "S",
    "situacao":"A",
    "condicao": "1",
    "controlar_estoque": True,
    "descricao_curta": "Tênis esportivo para corrida com amortecimento em gel.",
    "peso_liquido": 0.320,
    "peso_bruto": 0.580,
    "largura": 35.0,
    "altura": 15.0,
    "profundidade": 12.0,
    "garantia_meses": 3,
    "categoria_id": 5,
}

resposta = requests.post(f"{BASE_URL}/produtos/", headers=headers, json=novo_produto)
dados = resposta.json()

if dados["success"]:
    produto = dados["data"]
    print(f"Produto criado com sucesso! ID: {produto['id']}")
    print(f"Nome: {produto['nome']}")
else:
    print(f"Erro ao criar produto: {dados}")

Exemplo com JavaScript

javascript
const BASE_URL = "https://api-backend.bunto.com.br/v1";
const TOKEN = "bnt_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9t0U1v2W3x4";

const novoProduto = {
  nome: "Tênis Esportivo Running Pro",
  codigo: "TEN-045",
  gtin: "7891234560098",
  unidade: "PAR",
  marca: "Olympikus",
  preco: 299.9,
  preco_custo: 145.0,
  formato: "S",
  situacao: "A",
  condicao: "1",
  controlar_estoque: true,
  descricao_curta: "Tênis esportivo para corrida com amortecimento em gel.",
  peso_liquido: 0.32,
  peso_bruto: 0.58,
  largura: 35.0,
  altura: 15.0,
  profundidade: 12.0,
  garantia_meses: 3,
  categoria_id: 5,
};

const resposta = await fetch(`${BASE_URL}/produtos/`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(novoProduto),
});

const dados = await resposta.json();

if (dados.success) {
  console.log(`Produto criado com sucesso! ID: ${dados.data.id}`);
  console.log(`Nome: ${dados.data.nome}`);
} else {
  console.error(`Erro ao criar produto:`, dados);
}

Resposta (201 Created)

json
{
  "success": true,
  "message": "Produto criado com sucesso",
  "data": {
    "id": 143,
    "nome": "Tênis Esportivo Running Pro",
    "codigo":"TEN-045",
    "gtin": "7891234560098",
    "unidade": "PAR",
    "marca": "Olympikus",
    "preco":"299.9000000000",
    "preco_custo": "145.0000000000",
    "preco_promocional": null,
    "formato": "S",
    "situacao":"A",
    "controlar_estoque": true,
    "ativo": true,
    "categoria_nome": "Calçados",
    "criado_em": "2026-02-12T15:30:00-03:00",
    "atualizado_em": "2026-02-12T15:30:00-03:00",
    "fantasia": "Tênis Esportivo Running Pro",
    "descricao_curta": "Tênis esportivo para corrida com amortecimento em gel.",
    "descricao_complementar": null,
    "observacoes":null,
    "condicao": "1",
    "tipo_producao": null,
    "markup": null,
    "peso_liquido": "0.320",
    "peso_bruto": "0.580",
    "largura": "35.000",
    "altura": "15.000",
    "profundidade": "12.000",
    "estoque_total": "0",
    "fiscal": null
  }
}

---

Atualizar Produto

PUT /v1/produtos/{id}/

PATCH /v1/produtos/{id}/

Escopo necessário: produtos: write

Atualiza um produto existente. Use PUT para atualização completa ou PATCH para atualização parcial (apenas os campos enviados serão alterados).

Exemplo com cURL (PATCH - atualização parcial)

bash
curl -X PATCH https://api-backend.bunto.com.br/v1/produtos/143/ \
  -H 'Authorization: Bearer bnt_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9t0U1v2W3x4' \
  -H 'Content-Type: application/json' \
  -d '{
    "preco":279.90,
    "preco_promocional": 249.90,
    "descricao_curta": "Tênis esportivo para corrida com amortecimento em gel e solado antiderrapante."
  }'

Exemplo com Python

python
import requests

BASE_URL = "https://api-backend.bunto.com.br/v1"
TOKEN = "bnt_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9t0U1v2W3x4"

headers = {
    "Authorization": f"Bearer {TOKEN}",
    "Content-Type": "application/json",
}

produto_id = 143

# Atualizacao parcial (PATCH) - apenas os campos que mudaram
atualizacao = {
    "preco":279.90,
    "preco_promocional": 249.90,
    "descricao_curta": "Tênis esportivo para corrida com amortecimento em gel e solado antiderrapante.",
}

resposta = requests.patch(
    f"{BASE_URL}/produtos/{produto_id}/",
    headers=headers,
    json=atualizacao,
)

dados = resposta.json()

if dados["success"]:
    produto = dados["data"]
    print(f"Produto atualizado! Novo preco: R$ {produto['preco']}")
else:
    print(f"Erro ao atualizar: {dados}")

Exemplo com JavaScript

javascript
const BASE_URL = "https://api-backend.bunto.com.br/v1";
const TOKEN = "bnt_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9t0U1v2W3x4";

const produtoId = 143;

const atualizacao = {
  preco: 279.9,
  preco_promocional: 249.9,
  descricao_curta:
    "Tênis esportivo para corrida com amortecimento em gel e solado antiderrapante.",
};

const resposta = await fetch(`${BASE_URL}/produtos/${produtoId}/`, {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(atualizacao),
});

const dados = await resposta.json();

if (dados.success) {
  console.log(`Produto atualizado! Novo preco: R$ ${dados.data.preco}`);
} else {
  console.error(`Erro ao atualizar:`, dados);
}

Resposta (200 OK)

json
{
  "success": true,
  "message": "Produto atualizado com sucesso",
  "data": {
    "id": 143,
    "nome": "Tênis Esportivo Running Pro",
    "codigo":"TEN-045",
    "gtin": "7891234560098",
    "unidade": "PAR",
    "marca": "Olympikus",
    "preco":"279.9000000000",
    "preco_custo": "145.0000000000",
    "preco_promocional": "249.9000000000",
    "formato": "S",
    "situacao":"A",
    "controlar_estoque": true,
    "ativo": true,
    "categoria_nome": "Calçados",
    "criado_em": "2026-02-12T15:30:00-03:00",
    "atualizado_em": "2026-02-12T16:45:00-03:00",
    "fantasia": "Tênis Esportivo Running Pro",
    "descricao_curta": "Tênis esportivo para corrida com amortecimento em gel e solado antiderrapante.",
    "descricao_complementar": null,
    "observacoes":null,
    "condicao": "1",
    "tipo_producao": null,
    "markup": null,
    "peso_liquido": "0.320",
    "peso_bruto": "0.580",
    "largura": "35.000",
    "altura": "15.000",
    "profundidade": "12.000",
    "estoque_total": "0",
    "fiscal": null
  }
}

---

Excluir Produto (Soft Delete)

DELETE /v1/produtos/{id}/

Escopo necessário: produtos: delete

Desativa o produto (soft delete). O registro não é removido permanentemente do banco de dados -- o campo ativo é definido como false, preservando o histórico de vendas e movimentações.

Exemplo com cURL

bash
curl -X DELETE https://api-backend.bunto.com.br/v1/produtos/143/ \
  -H 'Authorization: Bearer bnt_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9t0U1v2W3x4'

Exemplo com Python

python
import requests

BASE_URL = "https://api-backend.bunto.com.br/v1"
TOKEN = "bnt_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9t0U1v2W3x4"

headers = {"Authorization": f"Bearer {TOKEN}"}

produto_id = 143
resposta = requests.delete(f"{BASE_URL}/produtos/{produto_id}/", headers=headers)
dados = resposta.json()

if dados["success"]:
    print(f"Produto excluído com sucesso!")
else:
    print(f"Erro ao excluir: {dados}")

Exemplo com JavaScript

javascript
const BASE_URL = "https://api-backend.bunto.com.br/v1";
const TOKEN = "bnt_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9t0U1v2W3x4";

const produtoId = 143;

const resposta = await fetch(`${BASE_URL}/produtos/${produtoId}/`, {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${TOKEN}`,
  },
});

const dados = await resposta.json();

if (dados.success) {
  console.log("Produto excluído com sucesso!");
} else {
  console.error(`Erro ao excluir:`, dados);
}

Resposta (200 OK)

json
{
  "success": true,
  "message": "Registro excluído com sucesso"
}

---

Erros Comuns

Exemplo de Resposta de Erro (400)

json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Erro de validacao",
    "details": {
      "nome": ["Este campo é obrigatorio."],
      "gtin": ["Certifique-se de que este campo nao tenha mais de 14 caracteres."]
    }
  }
}

Exemplo de Resposta de Erro (403)

json
{
  "detail": "Token nao tem permissao para este recurso"
}

---

Rate Limiting

A API aplica limites de requisição por token (não por IP). Cada tipo de operação tem um limite diferente.

Ao exceder o limite, a API retorna 429 Too Many Requests:

json
{
  "detail": "Limite de requisicoes excedido. Tente novamente em 45 segundos."
}

Boas práticas

• Use por_pagina=100 para reduzir o número de requisições ao listar produtos
• Implemente retry com backoff exponencial ao receber 429
• Armazene dados em cache local quando possível
• Para atualizações em lote, use PATCH apenas com os campos alterados para economizar requisições de escrita

---

Paginação

Todos os endpoints de listagem retornam dados paginados.

Parâmetros

Objeto paginacao na resposta

Exemplo: percorrer todas as páginas (Python)

python
import requests

BASE_URL = "https://api-backend.bunto.com.br/v1"
TOKEN = "bnt_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9t0U1v2W3x4"

headers = {"Authorization": f"Bearer {TOKEN}"}

todos_os_produtos = []
url = f"{BASE_URL}/produtos/?por_pagina=100"

while url:
    resposta = requests.get(url, headers=headers)
    dados = resposta.json()

    if not dados["success"]:
        break

    todos_os_produtos.extend(dados["data"]["resultados"])
    url = dados["data"]["paginacao"]["proxima"]

print(f"Total obtido: {len(todos_os_produtos)} produtos")

---

Valores de Referência

Formato do Produto

Situação do Produto

Condição do Produto

Origem Fiscal

Tipo do Item SPED