API de Configurações

Consulte as configurações do sistema do Bunto ERP. Este endpoint permite listar os campos de configuração com seus valores efetivos para a empresa autenticada.

---

Visão Geral

---

Endpoints

---

Listar Configurações

GET /v1/configuracoes/

Escopo necessário: configuracoes: read

Retorna a lista paginada de campos de configuração visíveis, com seus valores efetivos para a empresa autenticada. Se a empresa não customizou um campo, retorna o valor padrão global.

Query Parameters

Exemplo com cURL

bash
curl 'https://api-backend.bunto.com.br/v1/configuracoes/?pagina=1&por_pagina=50&secao=fiscal&tipo=boolean' \
  -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 todas as configuracoes fiscais
resposta = requests.get(
    f"{BASE_URL}/configuracoes/",
    headers=headers,
    params={
        "pagina": 1,
        "por_pagina": 100,
        "secao":"fiscal",
    },
)

dados = resposta.json()

if dados["success"]:
    configuracoes = dados["data"]["resultados"]
    paginacao = dados["data"]["paginacao"]
    print(f"Total de configuracoes: {paginacao['total_registros']}")
    for config in configuracoes:
        print(f"  - {config['chave']} = {config['valor']} ({config['tipo']})")
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: "100",
  secao: "fiscal",
});

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

const dados = await resposta.json();

if (dados.success) {
  const configuracoes = dados.data.resultados;
  const paginacao = dados.data.paginacao;
  console.log(`Total de configuracoes: ${paginacao.total_registros}`);
  configuracoes.forEach((config) => {
    console.log(`  - ${config.chave} = ${config.valor} (${config.tipo})`);
  });
} else {
  console.error(`Erro: ${resposta.status}`);
}

Resposta (200 OK)

json
{
  "success": true,
  "message": "45 registros encontrados",
  "data": {
    "resultados": [
      {
        "chave": "fiscal_regime_tributario",
        "nome": "Regime tributário",
        "valor": "simples_nacional",
        "tipo": "select",
        "secao":"Fiscal",
        "categoria": "Financeiro"
      },
      {
        "chave": "fiscal_emitir_nfe_automatico",
        "nome": "Emitir NF-e automaticamente",
        "valor": "true",
        "tipo": "boolean",
        "secao":"Fiscal",
        "categoria": "Financeiro"
      },
      {
        "chave": "vendas_desconto_maximo_percentual",
        "nome": "Desconto maximo permitido (%)",
        "valor": "15",
        "tipo": "number",
        "secao":"Vendas",
        "categoria": "Comercial"
      },
      {
        "chave": "sistema_moeda",
        "nome": "Moeda padrao",
        "valor": "BRL",
        "tipo": "text",
        "secao":"Geral",
        "categoria": "Sistema"
      }
    ],
    "paginacao": {
      "pagina_atual": 1,
      "total_paginas": 1,
      "total_registros": 45,
      "por_pagina": 100,
      "proxima": null,
      "anterior": null
    }
  }
}

Campos da Listagem

Lógica de Valor Efetivo

O campo valor retorna o valor efetivo para a empresa autenticada, seguindo esta ordem de prioridade:

1. Valor customizado pela empresa -- se a empresa definiu um valor específico para o campo, este é retornado
2. Valor padrão global -- caso contrário, o valor padrão do sistema é retornado

---

Exemplo Prático: Consultar Configurações por Categoria

python
import requests

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

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

# Buscar todas as configuracoes, organizadas por categoria
todas_configuracoes = []
url = f"{BASE_URL}/configuracoes/?por_pagina=100"

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

    if not dados["success"]:
        break

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

# Agrupar por categoria
por_categoria = {}
for config in todas_configuracoes:
    categoria = config["categoria"] or "Sem categoria"
    if categoria not in por_categoria:
        por_categoria[categoria] = []
    por_categoria[categoria].append(config)

# Exibir
for categoria, configs in por_categoria.items():
    print(f"\n== {categoria} ==")
    for config in configs:
        print(f"  {config['chave']}: {config['valor']}")

print(f"\nTotal: {len(todas_configuracoes)} configuracoes")

---

Erros Comuns

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).

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 obter todas as configurações em poucas requisições
• Implemente retry com backoff exponencial ao receber 429
• Armazene em cache local -- configurações raramente mudam, então é recomendável cache de pelo menos 5 minutos
• Use os filtros secao e categoria para consultar apenas as configurações relevantes à sua integração

---

Paginação

O endpoint de listagem retorna dados paginados.

Parâmetros

Objeto paginacao na resposta

---

Valores de Referência

Tipos de Campo