API de Regras Tributárias

Gerencie as regras tributárias da Reforma Tributária (IBS/CBS/IS) no Bunto ERP. Este endpoint permite listar, consultar, criar, atualizar e excluir regras que definem alíquotas de CBS, IBS (estadual e municipal) e Imposto Seletivo via API.

Base URL

Produção:

https://api-backend.bunto.com.br/v1/regras-tributarias/

---

Autenticação

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

Authorization: Bearer bnt_seu_token_aqui

---

Endpoints

Listar Regras Tributárias

GET /v1/regras-tributarias/

Escopo necessário: regras_tributarias: read

Retorna a lista paginada de regras tributárias da empresa. Por padrão, apenas regras ativas são retornadas.

Query Parameters

Exemplo com cURL

bash
curl 'https://api-backend.bunto.com.br/v1/regras-tributarias/?pagina=1&por_pagina=10&ativo=true&ordenar=data_criacao&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 regras tributárias ativas, mais recentes primeiro
resposta = requests.get(
    f"{BASE_URL}/regras-tributarias/",
    headers=headers,
    params={
        "pagina": 1,
        "por_pagina": 25,
        "ativo": "true",
        "ordenar": "data_criacao",
        "direcao": "desc",
    },
)

dados = resposta.json()

if dados["success"]:
    regras = dados["data"]["resultados"]
    paginacao = dados["data"]["paginacao"]
    print(f"Total de regras: {paginacao['total_registros']}")
    for regra in regras:
        print(f"  - {regra['situacao_tributaria_nome']} / {regra['classificacao_tributaria_nome']}")
        print(f"    CBS: {regra['cbs_aliq_principal']}% | IBS UF: {regra['ibs_uf_aliq_principal']}% | IBS Mun: {regra['ibs_mun_aliq_principal']}%")
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",
  ativo: "true",
  ordenar: "data_criacao",
  direcao: "desc",
});

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

const dados = await resposta.json();

if (dados.success) {
  const regras = dados.data.resultados;
  const paginacao = dados.data.paginacao;
  console.log(`Total de regras: ${paginacao.total_registros}`);
  regras.forEach((regra) => {
    console.log(`  - ${regra.situacao_tributaria_nome} / ${regra.classificacao_tributaria_nome}`);
    console.log(`    CBS: ${regra.cbs_aliq_principal}% | IBS UF: ${regra.ibs_uf_aliq_principal}% | IBS Mun: ${regra.ibs_mun_aliq_principal}%`);
  });
} else {
  console.error(`Erro: ${resposta.status}`);
}

Resposta (200 OK)

json
{
  "success": true,
  "message": "3 registros encontrados",
  "data": {
    "resultados": [
      {
        "id": 1,
        "situacao_tributaria_id": 1,
        "situacao_tributaria_nome": "Tributacao normal",
        "classificacao_tributaria_id": 1,
        "classificacao_tributaria_nome": "Mercadoria em geral",
        "cbs_aliq_principal": "8.8000",
        "ibs_uf_aliq_principal": "7.0000",
        "ibs_mun_aliq_principal": "5.5000",
        "is_aliquota": "0.0000",
        "ativo": true
      },
      {
        "id": 2,
        "situacao_tributaria_id": 2,
        "situacao_tributaria_nome": "Redução de alíquota",
        "classificacao_tributaria_id": 3,
        "classificacao_tributaria_nome": "Alimentos da cesta basica",
        "cbs_aliq_principal": "4.4000",
        "ibs_uf_aliq_principal": "3.5000",
        "ibs_mun_aliq_principal": "2.7500",
        "is_aliquota": "0.0000",
        "ativo": true
      },
      {
        "id": 3,
        "situacao_tributaria_id": 1,
        "situacao_tributaria_nome": "Tributacao normal",
        "classificacao_tributaria_id": 5,
        "classificacao_tributaria_nome": "Bebidas alcoólicas",
        "cbs_aliq_principal": "8.8000",
        "ibs_uf_aliq_principal": "7.0000",
        "ibs_mun_aliq_principal": "5.5000",
        "is_aliquota": "20.0000",
        "ativo": true
      }
    ],
    "paginacao": {
      "pagina_atual": 1,
      "total_paginas": 1,
      "total_registros": 3,
      "por_pagina": 25,
      "proxima": null,
      "anterior": null
    }
  }
}

Campos da Listagem

---

Obter Regra Tributária

GET /v1/regras-tributarias/{id}/

Escopo necessário: regras_tributarias: read

Retorna os dados completos de uma regra tributária específica, incluindo alíquotas de diferimento, reduções, naturezas vinculadas e filtros.

Exemplo com cURL

bash
curl https://api-backend.bunto.com.br/v1/regras-tributarias/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",
}

regra_id = 1
resposta = requests.get(f"{BASE_URL}/regras-tributarias/{regra_id}/", headers=headers)
dados = resposta.json()

if dados["success"]:
    regra = dados["data"]
    print(f"Situacao: {regra['situacao_tributaria_nome']}")
    print(f"Classificacao: {regra['classificacao_tributaria_nome']}")
    print(f"CBS: {regra['cbs_aliq_principal']}%")
    print(f"IBS UF: {regra['ibs_uf_aliq_principal']}%")
    print(f"IBS Mun: {regra['ibs_mun_aliq_principal']}%")
    print(f"IS: {regra['is_aliquota']}%")
    if regra["naturezas"]:
        print("Naturezas vinculadas:")
        for nat in regra["naturezas"]:
            print(f"  - Natureza ID: {nat['natureza_id']}")
    if regra["filtros"]:
        print("Filtros:")
        for filtro in regra["filtros"]:
            print(f"  - {filtro['tipo']}: {filtro['valor']} ({filtro['descricao']})")
else:
    print(f"Erro: {dados}")

Exemplo com JavaScript

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

const regraId = 1;

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

const dados = await resposta.json();

if (dados.success) {
  const regra = dados.data;
  console.log(`Situacao: ${regra.situacao_tributaria_nome}`);
  console.log(`Classificacao: ${regra.classificacao_tributaria_nome}`);
  console.log(`CBS: ${regra.cbs_aliq_principal}%`);
  console.log(`IBS UF: ${regra.ibs_uf_aliq_principal}%`);
  console.log(`IBS Mun: ${regra.ibs_mun_aliq_principal}%`);
  console.log(`IS: ${regra.is_aliquota}%`);
  if (regra.naturezas && regra.naturezas.length > 0) {
    console.log("Naturezas vinculadas:");
    regra.naturezas.forEach((nat) => {
      console.log(`  - Natureza ID: ${nat.natureza_id}`);
    });
  }
  if (regra.filtros && regra.filtros.length > 0) {
    console.log("Filtros:");
    regra.filtros.forEach((filtro) => {
      console.log(`  - ${filtro.tipo}: ${filtro.valor} (${filtro.descricao})`);
    });
  }
} else {
  console.error(`Erro: ${JSON.stringify(dados)}`);
}

Resposta (200 OK)

json
{
  "success": true,
  "message": "Registro encontrado",
  "data": {
    "id": 1,
    "situacao_tributaria_id": 1,
    "situacao_tributaria_nome": "Tributacao normal",
    "classificacao_tributaria_id": 1,
    "classificacao_tributaria_nome": "Mercadoria em geral",
    "cbs_aliq_principal": "8.8000",
    "ibs_uf_aliq_principal": "7.0000",
    "ibs_mun_aliq_principal": "5.5000",
    "is_aliquota": "0.0000",
    "cbs_aliq_diferimento": "0.0000",
    "cbs_reducao_aliq": "0.0000",
    "ibs_uf_aliq_diferimento": "0.0000",
    "ibs_uf_reducao_aliq": "0.0000",
    "ibs_mun_aliq_diferimento": "0.0000",
    "ibs_mun_reducao_aliq": "0.0000",
    "ativo": true,
    "data_criacao": "2026-01-15T10:00:00-03:00",
    "data_atualizacao": "2026-02-10T14:30:00-03:00",
    "naturezas": [
      {
        "natureza_id": 1
      },
      {
        "natureza_id": 2
      }
    ],
    "filtros": [
      {
        "tipo": "ncm",
        "valor": "2203.00.00",
        "descricao":"Cervejas de malte"
      }
    ]
  }
}

Campos do Detalhe (adicionais à listagem)

Campos de cada filtro

---

Criar Regra Tributária

POST /v1/regras-tributarias/

Escopo necessário: regras_tributarias: write

Cria uma nova regra tributária na empresa do token autenticado.

Campos do Request Body

Exemplo com cURL

bash
curl -X POST https://api-backend.bunto.com.br/v1/regras-tributarias/ \
  -H 'Authorization: Bearer bnt_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9t0U1v2W3x4' \
  -H 'Content-Type: application/json' \
  -d '{
    "situacao_tributaria_id": 1,
    "classificacao_tributaria_id": 1,
    "cbs_aliq_principal": "8.8000",
    "ibs_uf_aliq_principal": "7.0000",
    "ibs_mun_aliq_principal": "5.5000",
    "is_aliquota": "0.0000",
    "ativo": true
  }'

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

nova_regra = {
    "situacao_tributaria_id": 1,
    "classificacao_tributaria_id": 1,
    "cbs_aliq_principal": "8.8000",
    "ibs_uf_aliq_principal": "7.0000",
    "ibs_mun_aliq_principal": "5.5000",
    "is_aliquota": "0.0000",
    "ativo": True,
}

resposta = requests.post(f"{BASE_URL}/regras-tributarias/", headers=headers, json=nova_regra)
dados = resposta.json()

if dados["success"]:
    regra = dados["data"]
    print(f"Regra criada com sucesso! ID: {regra['id']}")
    print(f"Situacao: {regra['situacao_tributaria_nome']}")
    print(f"CBS: {regra['cbs_aliq_principal']}%")
else:
    print(f"Erro ao criar regra: {dados}")

Exemplo com JavaScript

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

const novaRegra = {
  situacao_tributaria_id: 1,
  classificacao_tributaria_id: 1,
  cbs_aliq_principal: "8.8000",
  ibs_uf_aliq_principal: "7.0000",
  ibs_mun_aliq_principal: "5.5000",
  is_aliquota: "0.0000",
  ativo: true,
};

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

const dados = await resposta.json();

if (dados.success) {
  console.log(`Regra criada com sucesso! ID: ${dados.data.id}`);
  console.log(`Situacao: ${dados.data.situacao_tributaria_nome}`);
  console.log(`CBS: ${dados.data.cbs_aliq_principal}%`);
} else {
  console.error(`Erro ao criar regra:`, dados);
}

Resposta (201 Created)

json
{
  "success": true,
  "message": "Regra tributária criada com sucesso",
  "data": {
    "id": 4,
    "situacao_tributaria_id": 1,
    "situacao_tributaria_nome": "Tributacao normal",
    "classificacao_tributaria_id": 1,
    "classificacao_tributaria_nome": "Mercadoria em geral",
    "cbs_aliq_principal": "8.8000",
    "ibs_uf_aliq_principal": "7.0000",
    "ibs_mun_aliq_principal": "5.5000",
    "is_aliquota": "0.0000",
    "cbs_aliq_diferimento": "0.0000",
    "cbs_reducao_aliq": "0.0000",
    "ibs_uf_aliq_diferimento": "0.0000",
    "ibs_uf_reducao_aliq": "0.0000",
    "ibs_mun_aliq_diferimento": "0.0000",
    "ibs_mun_reducao_aliq": "0.0000",
    "ativo": true,
    "data_criacao": "2026-02-12T15:30:00-03:00",
    "data_atualizacao": "2026-02-12T15:30:00-03:00",
    "naturezas": [],
    "filtros": []
  }
}

---

Atualizar Regra Tributária

PUT /v1/regras-tributarias/{id}/

PATCH /v1/regras-tributarias/{id}/

Escopo necessário: regras_tributarias: write

Atualiza uma regra tributária 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/regras-tributarias/4/ \
  -H 'Authorization: Bearer bnt_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9t0U1v2W3x4' \
  -H 'Content-Type: application/json' \
  -d '{
    "cbs_aliq_principal": "9.2500",
    "ibs_uf_aliq_principal": "7.3000",
    "ibs_mun_aliq_principal": "5.8000"
  }'

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

regra_id = 4

# Atualizacao parcial (PATCH) - apenas os campos que mudaram
atualizacao = {
    "cbs_aliq_principal": "9.2500",
    "ibs_uf_aliq_principal": "7.3000",
    "ibs_mun_aliq_principal": "5.8000",
}

resposta = requests.patch(
    f"{BASE_URL}/regras-tributarias/{regra_id}/",
    headers=headers,
    json=atualizacao,
)

dados = resposta.json()

if dados["success"]:
    regra = dados["data"]
    print(f"Regra atualizada! ID: {regra['id']}")
    print(f"CBS: {regra['cbs_aliq_principal']}%")
    print(f"IBS UF: {regra['ibs_uf_aliq_principal']}%")
    print(f"IBS Mun: {regra['ibs_mun_aliq_principal']}%")
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 regraId = 4;

const atualizacao = {
  cbs_aliq_principal: "9.2500",
  ibs_uf_aliq_principal: "7.3000",
  ibs_mun_aliq_principal: "5.8000",
};

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

const dados = await resposta.json();

if (dados.success) {
  console.log(`Regra atualizada! ID: ${dados.data.id}`);
  console.log(`CBS: ${dados.data.cbs_aliq_principal}%`);
  console.log(`IBS UF: ${dados.data.ibs_uf_aliq_principal}%`);
  console.log(`IBS Mun: ${dados.data.ibs_mun_aliq_principal}%`);
} else {
  console.error(`Erro ao atualizar:`, dados);
}

Resposta (200 OK)

json
{
  "success": true,
  "message": "Regra tributária atualizada com sucesso",
  "data": {
    "id": 4,
    "situacao_tributaria_id": 1,
    "situacao_tributaria_nome": "Tributacao normal",
    "classificacao_tributaria_id": 1,
    "classificacao_tributaria_nome": "Mercadoria em geral",
    "cbs_aliq_principal": "9.2500",
    "ibs_uf_aliq_principal": "7.3000",
    "ibs_mun_aliq_principal": "5.8000",
    "is_aliquota": "0.0000",
    "cbs_aliq_diferimento": "0.0000",
    "cbs_reducao_aliq": "0.0000",
    "ibs_uf_aliq_diferimento": "0.0000",
    "ibs_uf_reducao_aliq": "0.0000",
    "ibs_mun_aliq_diferimento": "0.0000",
    "ibs_mun_reducao_aliq": "0.0000",
    "ativo": true,
    "data_criacao": "2026-02-12T15:30:00-03:00",
    "data_atualizacao": "2026-02-12T16:45:00-03:00",
    "naturezas": [],
    "filtros": []
  }
}

---

Excluir Regra Tributária (Soft Delete)

DELETE /v1/regras-tributarias/{id}/

Escopo necessário: regras_tributarias: delete

Desativa a regra tributária (soft delete). O registro não é removido permanentemente do banco de dados -- o campo ativo é definido como false, preservando o histórico e os vínculos com naturezas.

Exemplo com cURL

bash
curl -X DELETE https://api-backend.bunto.com.br/v1/regras-tributarias/4/ \
  -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}"}

regra_id = 4
resposta = requests.delete(f"{BASE_URL}/regras-tributarias/{regra_id}/", headers=headers)
dados = resposta.json()

if dados["success"]:
    print("Regra tributária excluída 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 regraId = 4;

const resposta = await fetch(`${BASE_URL}/regras-tributarias/${regraId}/`, {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${TOKEN}`,
  },
});

const dados = await resposta.json();

if (dados.success) {
  console.log("Regra tributária excluída 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": {
      "situacao_tributaria_id": ["Este campo é obrigatorio."],
      "classificacao_tributaria_id": ["Este campo é obrigatorio."]
    }
  }
}

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 regras tributárias
• 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}"}

todas_as_regras = []
url = f"{BASE_URL}/regras-tributarias/?por_pagina=100"

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

    if not dados["success"]:
        break

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

print(f"Total obtido: {len(todas_as_regras)} regras tributárias")