API de Dashboard

Consulte estatisticas e indicadores agregados da sua empresa via API. Este endpoint fornece uma visao consolidada de estoque, clientes, vendas e finanças em uma única requisição. Somente leitura -- não aceita operações de escrita ou exclusão.

---

Visao Geral

---

Endpoints

---

Obter Resumo do Dashboard

GET /v1/dashboard/

Escopo necessário: dashboard: read

Retorna estatisticas agregadas de todas as areas do sistema: estoque, clientes, vendas e finanças. Os dados sao calculados em tempo real a partir dos registros da empresa.

Exemplo com cURL

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

# Consultar dashboard completo
resposta = requests.get(f"{BASE_URL}/dashboard/", headers=headers)
dados = resposta.json()

if dados["success"]:
    dashboard = dados["data"]

    # Visao geral - Estoque
    estoque = dashboard["visao_geral"]["estoque"]
    print(f"Produtos ativos: {estoque['total_produtos']}")
    print(f"Valor em estoque: R$ {estoque['valor_total_estoque']}")
    print(f"Estoque baixo: {estoque['produtos_estoque_baixo']} produtos")

    # Visao geral - Clientes
    clientes = dashboard["visao_geral"]["clientes"]
    print(f"Total de clientes: {clientes['total_clientes']}")
    print(f"Novos (ultimos 30 dias): {clientes['novos_clientes']}")

    # Visao geral - Vendas
    vendas = dashboard["visao_geral"]["vendas"]
    print(f"Vendas no mes: {vendas['total_vendas_mes']}")
    print(f"Faturamento: R$ {vendas['total_valor_mes']}")
    print(f"Ticket medio: R$ {vendas['ticket_medio']}")

    # Financas
    financas = dashboard["financas"]["resumo"]
    print(f"Saldo atual: R$ {financas['saldo_atual']}")
    print(f"A receber: R$ {financas['contas_receber_total']}")
    print(f"A pagar: R$ {financas['contas_pagar_total']}")
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 resposta = await fetch(`${BASE_URL}/dashboard/`, {
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
  },
});

const dados = await resposta.json();

if (dados.success) {
  const dashboard = dados.data;

  // Visao geral - Estoque
  const estoque = dashboard.visao_geral.estoque;
  console.log(`Produtos ativos: ${estoque.total_produtos}`);
  console.log(`Valor em estoque: R$ ${estoque.valor_total_estoque}`);
  console.log(`Estoque baixo: ${estoque.produtos_estoque_baixo} produtos`);

  // Visao geral - Clientes
  const clientes = dashboard.visao_geral.clientes;
  console.log(`Total de clientes: ${clientes.total_clientes}`);
  console.log(`Novos (ultimos 30 dias): ${clientes.novos_clientes}`);

  // Visao geral - Vendas
  const vendas = dashboard.visao_geral.vendas;
  console.log(`Vendas no mes: ${vendas.total_vendas_mes}`);
  console.log(`Faturamento: R$ ${vendas.total_valor_mes}`);
  console.log(`Ticket medio: R$ ${vendas.ticket_medio}`);

  // Financas
  const financas = dashboard.financas.resumo;
  console.log(`Saldo atual: R$ ${financas.saldo_atual}`);
  console.log(`A receber: R$ ${financas.contas_receber_total}`);
  console.log(`A pagar: R$ ${financas.contas_pagar_total}`);
} else {
  console.error(`Erro: ${resposta.status}`);
}

Resposta (200 OK)

json
{
  "success": true,
  "message": "Dados do dashboard",
  "data": {
    "visao_geral": {
      "estoque": {
        "total_produtos": 342,
        "valor_total_estoque": "187450.00",
        "produtos_estoque_baixo": 12,
        "produtos_sem_movimento": 45
      },
      "clientes": {
        "total_clientes": 1580,
        "clientes_ativos": 1420,
        "novos_clientes": 38
      },
      "vendas": {
        "total_vendas_mes": 156,
        "total_valor_mes": "89750.00",
        "percentual_crescimento": 12.5,
        "media_diaria": 13,
        "vendas_pendentes": 8,
        "total_vendas": 2340,
        "total_pedidos": 2340,
        "ticket_medio": "575.32"
      }
    },
    "financas": {
      "resumo": {
        "saldo_atual": 45320.50,
        "contas_pagar_total": 28900.00,
        "contas_receber_total": 67450.00,
        "contas_vencendo_hoje": 3,
        "conta_maior_saldo": {
          "nome": "Banco do Brasil - CC",
          "saldo": 45320.50
        },
        "saldo_contas": 45320.50
      },
      "fluxo_caixa": {
        "receitas_total": 72300.00,
        "despesas_total": 41200.00,
        "saldo_acumulado": 31100.00,
        "receitas_por_categoria": [
          {
            "categoria": "Vendas",
            "valor": 65800.00
          },
          {
            "categoria": "Servicos",
            "valor": 6500.00
          }
        ],
        "despesas_por_categoria": [
          {
            "categoria": "Fornecedores",
            "valor": 28500.00
          },
          {
            "categoria": "Operacional",
            "valor": 12700.00
          }
        ]
      },
      "contas": {
        "contas_receber": {
          "total": 67450.00,
          "por_categoria": [
            {
              "categoria": "Vendas a prazo",
              "valor": 52300.00
            },
            {
              "categoria": "Servicos",
              "valor": 15150.00
            }
          ]
        },
        "contas_pagar": {
          "total": 28900.00,
          "por_categoria": [
            {
              "categoria": "Fornecedores",
              "valor": 18500.00
            },
            {
              "categoria": "Impostos",
              "valor": 7200.00
            },
            {
              "categoria": "Despesas fixas",
              "valor": 3200.00
            }
          ]
        }
      }
    },
    "ultima_atualizacao": "2026-02-12T15:30:00-03:00"
  }
}

---

Estrutura da Resposta

A resposta do dashboard e organizada em tres blocos principais: visao_geral, financas e ultima_atualizacao.

Objeto visao_geral

Contem estatisticas rapidas de estoque, clientes e vendas.

visao_geral.estoque

visao_geral.clientes

visao_geral.vendas

Objeto financas

Contem resumo financeiro, fluxo de caixa e detalhamento de contas.

financas.resumo

financas.fluxo_caixa

financas.contas

Campo ultima_atualizacao

---

Exemplo Pratico: Monitoramento Automatizado

O endpoint de dashboard e ideal para construir paineis de monitoramento e alertas automatizados.

Python - Alertas de estoque e financeiro

python
import requests

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

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

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

if dados["success"]:
    dashboard = dados["data"]

    # Alerta de estoque baixo
    estoque_baixo = dashboard["visao_geral"]["estoque"]["produtos_estoque_baixo"]
    if estoque_baixo > 10:
        print(f"ALERTA: {estoque_baixo} produtos com estoque abaixo do minimo!")

    # Alerta de contas vencendo
    vencendo = dashboard["financas"]["resumo"]["contas_vencendo_hoje"]
    if vencendo > 0:
        print(f"ATENCAO: {vencendo} contas vencem hoje!")

    # Resumo de vendas
    vendas = dashboard["visao_geral"]["vendas"]
    crescimento = vendas["percentual_crescimento"]
    if crescimento < 0:
        print(f"ALERTA: Vendas caindo {abs(crescimento)}% em relacao ao mes anterior")
    else:
        print(f"Vendas crescendo {crescimento}% em relacao ao mes anterior")

    # Saldo financeiro
    saldo = dashboard["financas"]["resumo"]["saldo_atual"]
    print(f"Saldo projetado: R$ {saldo:,.2f}")
else:
    print(f"Erro ao consultar dashboard: {resposta.status_code}")

JavaScript - Exibir indicadores

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

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

  const dados = await resposta.json();

  if (!dados.success) {
    console.error("Erro ao carregar dashboard");
    return;
  }

  const dashboard = dados.data;

  // Indicadores de estoque
  const estoque = dashboard.visao_geral.estoque;
  console.log("--- ESTOQUE ---");
  console.log(`Produtos: ${estoque.total_produtos}`);
  console.log(`Valor total: R$ ${estoque.valor_total_estoque}`);
  console.log(`Alerta (estoque baixo): ${estoque.produtos_estoque_baixo}`);
  console.log(`Sem movimento (90 dias): ${estoque.produtos_sem_movimento}`);

  // Indicadores de vendas
  const vendas = dashboard.visao_geral.vendas;
  console.log("--- VENDAS ---");
  console.log(`Vendas no mes: ${vendas.total_vendas_mes}`);
  console.log(`Faturamento: R$ ${vendas.total_valor_mes}`);
  console.log(`Ticket medio: R$ ${vendas.ticket_medio}`);
  console.log(`Crescimento: ${vendas.percentual_crescimento}%`);

  // Indicadores financeiros
  const financas = dashboard.financas.resumo;
  console.log("--- Financas ---");
  console.log(`Saldo contas: R$ ${financas.saldo_contas}`);
  console.log(`A receber: R$ ${financas.contas_receber_total}`);
  console.log(`A pagar: R$ ${financas.contas_pagar_total}`);
  console.log(`Vencendo hoje: ${financas.contas_vencendo_hoje}`);

  console.log(`\nAtualizado em: ${dashboard.ultima_atualizacao}`);
}

carregarDashboard();

---

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 praticas

• Cache local: Os dados do dashboard raramente mudam em intervalos curtos. Implemente cache de 1 a 5 minutos para reduzir o número de requisições
• Polling controlado: Se precisar atualizar periodicamente, use intervalos de no mínimo 30 segundos entre requisições
• Implemente retry com backoff: Ao receber 429, aguarde o tempo indicado e tente novamente
• Use para visao geral: Para dados detalhados de um módulo específico (ex: lista de vendas), use o endpoint dedicado daquele módulo ao inves do dashboard