API de Finanças

Gerencie as contas financeiras do Bunto ERP. Este endpoint permite listar, consultar, criar, atualizar e cancelar contas a pagar e contas a receber via API.

Base URL

Produção:

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

---

Autenticação

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

Authorization: Bearer bnt_seu_token_aqui

---

Endpoints

Listar Contas Financeiras

GET /v1/financas/

Escopo necessário: financas: read

Retorna a lista paginada de contas financeiras (a pagar e a receber) da empresa.

Query Parameters

Exemplo com cURL

bash
curl 'https://api-backend.bunto.com.br/v1/financas/?pagina=1&por_pagina=10&tipo_conta=receber&status=em_aberto&ordenar=data_vencimento&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 a receber em aberto ordenadas por vencimento
resposta = requests.get(
    f"{BASE_URL}/financas/",
    headers=headers,
    params={
        "pagina": 1,
        "por_pagina": 25,
        "tipo_conta": "receber",
        "status": "em_aberto",
        "ordenar": "data_vencimento",
        "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['numero_documento']}] {conta['contato_nome']} | R$ {conta['valor']} | Vence: {conta['data_vencimento']}")
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",
  tipo_conta: "receber",
  status: "em_aberto",
  ordenar: "data_vencimento",
  direcao: "asc",
});

const resposta = await fetch(`${BASE_URL}/financas/?${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.numero_documento}] ${conta.contato_nome} | R$ ${conta.valor} | Vence: ${conta.data_vencimento}`);
  });
} else {
  console.error(`Erro: ${resposta.status}`);
}

Resposta (200 OK)

json
{
  "success": true,
  "message": "5 registros encontrados",
  "data": {
    "resultados": [
      {
        "id": 101,
        "tipo_conta": "receber",
        "contato_id": 42,
        "contato_nome": "Maria Silva Ltda",
        "categoria_id": 7,
        "categoria_nome": "Vendas de Produtos",
        "valor": "1500.00",
        "data_vencimento": "2026-03-15",
        "data_emissao": "2026-02-10",
        "status": "em_aberto",
        "numero_documento": "NF-00451"
      },
      {
        "id": 102,
        "tipo_conta": "receber",
        "contato_id": 18,
        "contato_nome": "Comércio ABC ME",
        "categoria_id": 7,
        "categoria_nome": "Vendas de Produtos",
        "valor": "3200.50",
        "data_vencimento": "2026-03-20",
        "data_emissao": "2026-02-12",
        "status": "em_aberto",
        "numero_documento": "NF-00452"
      }
    ],
    "paginacao": {
      "pagina_atual": 1,
      "total_paginas": 1,
      "total_registros": 5,
      "por_pagina": 25,
      "proxima": null,
      "anterior": null
    }
  }
}

Campos da Listagem

---

Obter Conta Financeira

GET /v1/financas/{id}/

Escopo necessário: financas: read

Retorna os dados completos de uma conta financeira específica, incluindo campos de liquidação, forma de pagamento e vínculos com vendas, compras e notas fiscais.

Exemplo com cURL

bash
curl https://api-backend.bunto.com.br/v1/financas/101/ \
  -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 = 101
resposta = requests.get(f"{BASE_URL}/financas/{conta_id}/", headers=headers)
dados = resposta.json()

if dados["success"]:
    conta = dados["data"]
    print(f"Conta: {conta['numero_documento']} | {conta['tipo_conta']}")
    print(f"Contato: {conta['contato_nome']}")
    print(f"Valor: R$ {conta['valor']} | Vencimento: {conta['data_vencimento']}")
    print(f"Status: {conta['status']}")
    if conta["venda_origem_id"]:
        print(f"Venda de origem: #{conta['venda_origem_id']}")
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 = 101;

const resposta = await fetch(`${BASE_URL}/financas/${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.numero_documento} | ${conta.tipo_conta}`);
  console.log(`Contato: ${conta.contato_nome}`);
  console.log(`Valor: R$ ${conta.valor} | Vencimento: ${conta.data_vencimento}`);
  console.log(`Status: ${conta.status}`);
  if (conta.venda_origem_id) {
    console.log(`Venda de origem: #${conta.venda_origem_id}`);
  }
} else {
  console.error(`Erro: ${JSON.stringify(dados)}`);
}

Resposta (200 OK)

json
{
  "success": true,
  "message": "Registro encontrado",
  "data": {
    "id": 101,
    "tipo_conta": "receber",
    "contato_id": 42,
    "contato_nome": "Maria Silva Ltda",
    "categoria_id": 7,
    "categoria_nome": "Vendas de Produtos",
    "valor": "1500.00",
    "data_vencimento": "2026-03-15",
    "data_emissao": "2026-02-10",
    "status": "em_aberto",
    "numero_documento": "NF-00451",
    "competencia": "2026-02",
    "data_liquidacao": null,
    "forma_pagamento": 1,
    "historico": "Venda de produtos - Pedido #1023",
    "nosso_numero": "00000451",
    "venda_origem_id": 1023,
    "pedido_compra_origem_id": null,
    "nota_fiscal_id": 451,
    "nfse_origem_id": null,
    "data_criacao": "2026-02-10T10:30:00-03:00",
    "data_atualizacao": "2026-02-10T10:30:00-03:00"
  }
}

Campos do Detalhe (adicionais à listagem)

---

Criar Conta Financeira

POST /v1/financas/

Escopo necessário: financas: write

Cria uma nova conta financeira (a pagar ou a receber) na empresa do token autenticado.

Campos do Request Body

Exemplo com cURL

bash
curl -X POST https://api-backend.bunto.com.br/v1/financas/ \
  -H 'Authorization: Bearer bnt_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9t0U1v2W3x4' \
  -H 'Content-Type: application/json' \
  -d '{
    "tipo_conta": "receber",
    "contato_id": 42,
    "categoria_id": 7,
    "valor": "2500.00",
    "data_vencimento": "2026-04-10",
    "data_emissao": "2026-02-12",
    "competencia": "2026-02",
    "numero_documento": "NF-00460",
    "forma_pagamento": 1,
    "historico": "Venda de produtos - lote de fevereiro"
  }'

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_conta = {
    "tipo_conta": "receber",
    "contato_id": 42,
    "categoria_id": 7,
    "valor": "2500.00",
    "data_vencimento": "2026-04-10",
    "data_emissao": "2026-02-12",
    "competencia": "2026-02",
    "numero_documento": "NF-00460",
    "forma_pagamento": 1,
    "historico": "Venda de produtos - lote de fevereiro",
}

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

if dados["success"]:
    conta = dados["data"]
    print(f"Conta criada com sucesso! ID: {conta['id']}")
    print(f"Tipo: {conta['tipo_conta']} | Valor: R$ {conta['valor']}")
    print(f"Vencimento: {conta['data_vencimento']}")
else:
    print(f"Erro ao criar conta: {dados}")

Exemplo com JavaScript

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

const novaConta = {
  tipo_conta: "receber",
  contato_id: 42,
  categoria_id: 7,
  valor: "2500.00",
  data_vencimento: "2026-04-10",
  data_emissao: "2026-02-12",
  competencia: "2026-02",
  numero_documento: "NF-00460",
  forma_pagamento: 1,
  historico: "Venda de produtos - lote de fevereiro",
};

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

const dados = await resposta.json();

if (dados.success) {
  console.log(`Conta criada com sucesso! ID: ${dados.data.id}`);
  console.log(`Tipo: ${dados.data.tipo_conta} | Valor: R$ ${dados.data.valor}`);
  console.log(`Vencimento: ${dados.data.data_vencimento}`);
} else {
  console.error(`Erro ao criar conta:`, dados);
}

Resposta (201 Created)

json
{
  "success": true,
  "message": "Conta financeira criada com sucesso",
  "data": {
    "id": 115,
    "tipo_conta": "receber",
    "contato_id": 42,
    "contato_nome": "Maria Silva Ltda",
    "categoria_id": 7,
    "categoria_nome": "Vendas de Produtos",
    "valor": "2500.00",
    "data_vencimento": "2026-04-10",
    "data_emissao": "2026-02-12",
    "status": "em_aberto",
    "numero_documento": "NF-00460",
    "competencia": "2026-02",
    "data_liquidacao": null,
    "forma_pagamento": 1,
    "historico": "Venda de produtos - lote de fevereiro",
    "nosso_numero": null,
    "venda_origem_id": null,
    "pedido_compra_origem_id": null,
    "nota_fiscal_id": null,
    "nfse_origem_id": null,
    "data_criacao": "2026-02-12T16:00:00-03:00",
    "data_atualizacao": "2026-02-12T16:00:00-03:00"
  }
}

---

Atualizar Conta Financeira

PUT /v1/financas/{id}/

PATCH /v1/financas/{id}/

Escopo necessário: financas: write

Atualiza uma conta financeira 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/financas/115/ \
  -H 'Authorization: Bearer bnt_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9t0U1v2W3x4' \
  -H 'Content-Type: application/json' \
  -d '{
    "valor": "2800.00",
    "data_vencimento": "2026-04-15",
    "historico": "Venda de produtos - lote de fevereiro (valor atualizado)"
  }'

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 = 115

# Atualizacao parcial (PATCH) - apenas os campos que mudaram
atualizacao = {
    "valor": "2800.00",
    "data_vencimento": "2026-04-15",
    "historico": "Venda de produtos - lote de fevereiro (valor atualizado)",
}

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

dados = resposta.json()

if dados["success"]:
    conta = dados["data"]
    print(f"Conta atualizada! Valor: R$ {conta['valor']}")
    print(f"Novo vencimento: {conta['data_vencimento']}")
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 contaId = 115;

const atualizacao = {
  valor: "2800.00",
  data_vencimento: "2026-04-15",
  historico: "Venda de produtos - lote de fevereiro (valor atualizado)",
};

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

const dados = await resposta.json();

if (dados.success) {
  console.log(`Conta atualizada! Valor: R$ ${dados.data.valor}`);
  console.log(`Novo vencimento: ${dados.data.data_vencimento}`);
} else {
  console.error(`Erro ao atualizar:`, dados);
}

Resposta (200 OK)

json
{
  "success": true,
  "message": "Conta financeira atualizada com sucesso",
  "data": {
    "id": 115,
    "tipo_conta": "receber",
    "contato_id": 42,
    "contato_nome": "Maria Silva Ltda",
    "categoria_id": 7,
    "categoria_nome": "Vendas de Produtos",
    "valor": "2800.00",
    "data_vencimento": "2026-04-15",
    "data_emissao": "2026-02-12",
    "status": "em_aberto",
    "numero_documento": "NF-00460",
    "competencia": "2026-02",
    "data_liquidacao": null,
    "forma_pagamento": 1,
    "historico": "Venda de produtos - lote de fevereiro (valor atualizado)",
    "nosso_numero": null,
    "venda_origem_id": null,
    "pedido_compra_origem_id": null,
    "nota_fiscal_id": null,
    "nfse_origem_id": null,
    "data_criacao": "2026-02-12T16:00:00-03:00",
    "data_atualizacao": "2026-02-12T17:15:00-03:00"
  }
}

---

Cancelar Conta Financeira (Soft Delete)

DELETE /v1/financas/{id}/

Escopo necessário: financas: delete

Cancela a conta financeira (soft delete). O registro não é removido permanentemente do banco de dados -- o status é alterado para canceladas, preservando o histórico financeiro.

Exemplo com cURL

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

conta_id = 115
resposta = requests.delete(f"{BASE_URL}/financas/{conta_id}/", headers=headers)
dados = resposta.json()

if dados["success"]:
    print("Conta financeira cancelada com sucesso!")
else:
    print(f"Erro ao cancelar: {dados}")

Exemplo com JavaScript

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

const contaId = 115;

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

const dados = await resposta.json();

if (dados.success) {
  console.log("Conta financeira cancelada com sucesso!");
} else {
  console.error(`Erro ao cancelar:`, dados);
}

Resposta (200 OK)

json
{
  "success": true,
  "message": "Conta financeira cancelada com sucesso"
}

---

Erros Comuns

Exemplo de Resposta de Erro (400)

json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Erro de validacao",
    "details": {
      "tipo_conta": ["\"cobrar\" nao é um escolha valido. Escolha entre: pagar, receber."],
      "valor": ["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 contas financeiras
• 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
• Filtre por tipo_conta e status para reduzir o volume de dados retornados

---

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}/financas/?por_pagina=100&tipo_conta=receber"

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 a receber")