API de Contas Bancárias

Consulte as contas bancárias cadastradas no Bunto ERP. Este endpoint permite listar e consultar contas bancárias de forma somente leitura via API.

Base URL

Produção:

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

---

Autenticação

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

Authorization: Bearer bnt_seu_token_aqui

---

Endpoints

Listar Contas Bancárias

GET /v1/contas/

Escopo necessário: contas: read

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

Query Parameters

Exemplo com cURL

bash
curl 'https://api-backend.bunto.com.br/v1/contas/?pagina=1&por_pagina=10&ordenar=descricao&direcao=asc' \
  -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 contas bancárias ativas ordenadas por descricao
resposta = requests.get(
    f"{BASE_URL}/contas/",
    headers=headers,
    params={
        "pagina": 1,
        "por_pagina": 25,
        "ordenar": "descricao",
        "direcao": "asc",
    },
)

dados = resposta.json()

if dados["success"]:
    contas = dados["data"]["resultados"]
    paginacao = dados["data"]["paginacao"]
    print(f"Total de contas: {paginacao['total_registros']}")
    for conta in contas:
        print(f"  - [{conta['banco_codigo']}] {conta['descricao']} | Ag: {conta['agencia']} Cc: {conta['conta']}")
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",
  ordenar: "descricao",
  direcao: "asc",
});

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

const dados = await resposta.json();

if (dados.success) {
  const contas = dados.data.resultados;
  const paginacao = dados.data.paginacao;
  console.log(`Total de contas: ${paginacao.total_registros}`);
  contas.forEach((conta) => {
    console.log(`  - [${conta.banco_codigo}] ${conta.descricao} | Ag: ${conta.agencia} Cc: ${conta.conta}`);
  });
} else {
  console.error(`Erro: ${resposta.status}`);
}

Resposta (200 OK)

json
{
  "success": true,
  "message": "3 registros encontrados",
  "data": {
    "resultados": [
      {
        "id": 1,
        "banco_codigo": "001",
        "descricao":"Banco do Brasil - Conta Principal",
        "agencia": "1234",
        "conta": "56789-0",
        "ativo": true,
        "principal": true
      },
      {
        "id": 2,
        "banco_codigo": "341",
        "descricao":"Itaú - Conta Secundária",
        "agencia": "0567",
        "conta": "12345-6",
        "ativo": true,
        "principal": false
      },
      {
        "id": 3,
        "banco_codigo": "033",
        "descricao":"Santander - Recebimentos",
        "agencia": "0890",
        "conta": "01234567-8",
        "ativo": true,
        "principal": false
      }
    ],
    "paginacao": {
      "pagina_atual": 1,
      "total_paginas": 1,
      "total_registros": 3,
      "por_pagina": 25,
      "proxima": null,
      "anterior": null
    }
  }
}

Campos da Listagem

---

Obter Conta Bancária

GET /v1/contas/{id}/

Escopo necessário: contas: read

Retorna os dados completos de uma conta bancária específica, incluindo informações adicionais como dígitos da agência e conta, tipo de conta e dados do titular.

Exemplo com cURL

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

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

if dados["success"]:
    conta = dados["data"]
    print(f"Conta: {conta['descricao']}")
    print(f"Banco: {conta['banco_codigo']}")
    print(f"Agência: {conta['agencia']}-{conta['agencia_digito'] or ''}")
    print(f"Conta: {conta['conta']}-{conta['conta_digito'] or ''}")
    print(f"Titular: {conta['titular']}")
else:
    print(f"Erro: {dados}")

Exemplo com JavaScript

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

const contaId = 1;

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

const dados = await resposta.json();

if (dados.success) {
  const conta = dados.data;
  console.log(`Conta: ${conta.descricao}`);
  console.log(`Banco: ${conta.banco_codigo}`);
  console.log(`Agência: ${conta.agencia}-${conta.agencia_digito ?? ""}`);
  console.log(`Conta: ${conta.conta}-${conta.conta_digito ?? ""}`);
  console.log(`Titular: ${conta.titular}`);
} else {
  console.error(`Erro: ${JSON.stringify(dados)}`);
}

Resposta (200 OK)

json
{
  "success": true,
  "message": "Registro encontrado",
  "data": {
    "id": 1,
    "banco_codigo": "001",
    "descricao":"Banco do Brasil - Conta Principal",
    "agencia": "1234",
    "conta": "56789-0",
    "ativo": true,
    "principal": true,
    "agencia_digito": "5",
    "conta_digito": "0",
    "tipo_conta": "corrente",
    "titular": "Empresa Exemplo LTDA",
    "documento_titular": "12.345.678/0001-90"
  }
}

Campos do Detalhe (adicionais à listagem)

---

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 reduzir o número de requisições ao listar contas
• Implemente retry com backoff exponencial ao receber 429
• Armazene dados em cache local quando possível

---

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_contas = []
url = f"{BASE_URL}/contas/?por_pagina=100"

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

    if not dados["success"]:
        break

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

print(f"Total obtido: {len(todas_as_contas)} contas bancárias")