API de Arquivos

Consulte e gerencie metadados de arquivos no Bunto ERP. Este endpoint permite listar, consultar, atualizar metadados e desativar arquivos da sua empresa via API.

Base URL

Produção:

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

---

Autenticação

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

Authorization: Bearer bnt_seu_token_aqui

---

Endpoints

Listar Arquivos

GET /v1/arquivos/

Escopo necessário: arquivos: read

Retorna a lista paginada de arquivos ativos da empresa (apenas metadados).

Query Parameters

Exemplo com cURL

bash
curl 'https://api-backend.bunto.com.br/v1/arquivos/?pagina=1&por_pagina=10&modulo=produtos&tipo=imagem&ordenar=criado_em&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 arquivos com filtros
resposta = requests.get(
    f"{BASE_URL}/arquivos/",
    headers=headers,
    params={
        "pagina": 1,
        "por_pagina": 25,
        "modulo": "produtos",
        "tipo": "imagem",
        "ordenar": "criado_em",
        "direcao": "desc",
    },
)

dados = resposta.json()

if dados["success"]:
    arquivos = dados["data"]["resultados"]
    paginacao = dados["data"]["paginacao"]
    print(f"Total de arquivos: {paginacao['total_registros']}")
    for arq in arquivos:
        tamanho_kb = arq["tamanho"] / 1024
        print(f"  - {arq['nome_original']} ({tamanho_kb:.1f} KB) [{arq['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: "25",
  modulo: "produtos",
  tipo: "imagem",
  ordenar: "criado_em",
  direcao: "desc",
});

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

const dados = await resposta.json();

if (dados.success) {
  const arquivos = dados.data.resultados;
  const paginacao = dados.data.paginacao;
  console.log(`Total de arquivos: ${paginacao.total_registros}`);
  arquivos.forEach((arq) => {
    const tamanhoKb = (arq.tamanho / 1024).toFixed(1);
    console.log(
      `  - ${arq.nome_original} (${tamanhoKb} KB) [${arq.tipo}]`
    );
  });
} else {
  console.error(`Erro: ${resposta.status}`);
}

Resposta (200 OK)

json
{
  "success": true,
  "message": "56 registros encontrados",
  "data": {
    "resultados": [
      {
        "id": 1,
        "nome_original": "camiseta-basica-frente.jpg",
        "extensao": "jpg",
        "mime_type": "image/jpeg",
        "modulo": "produtos",
        "tipo": "imagem",
        "tamanho": 245760,
        "publico": true,
        "ativo": true,
        "criado_em": "2026-02-10T14:30:00-03:00"
      },
      {
        "id": 2,
        "nome_original": "catalogo-verao-2026.pdf",
        "extensao": "pdf",
        "mime_type": "application/pdf",
        "modulo": "produtos",
        "tipo": "pdf",
        "tamanho": 5242880,
        "publico": false,
        "ativo": true,
        "criado_em": "2026-02-08T09:15:00-03:00"
      }
    ],
    "paginacao": {
      "pagina_atual": 1,
      "total_paginas": 3,
      "total_registros": 56,
      "por_pagina": 25,
      "proxima": "https://api-backend.bunto.com.br/v1/arquivos/?pagina=2",
      "anterior": null
    }
  }
}

Campos da Listagem

---

Obter Arquivo

GET /v1/arquivos/{id}/

Escopo necessário: arquivos: read

Retorna os metadados completos de um arquivo específico, incluindo descrição e caminho completo.

Exemplo com cURL

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

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

if dados["success"]:
    arq = dados["data"]
    print(f"Arquivo: {arq['nome_original']}")
    print(f"Tipo: {arq['tipo']} ({arq['mime_type']})")
    tamanho_kb = arq["tamanho"] / 1024
    print(f"Tamanho: {tamanho_kb:.1f} KB")
    print(f"Público: {'Sim' if arq['publico'] else 'Não'}")
    print(f"Caminho: {arq['caminho_completo']}")
else:
    print(f"Erro: {dados}")

Exemplo com JavaScript

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

const arquivoId = 1;

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

const dados = await resposta.json();

if (dados.success) {
  const arq = dados.data;
  console.log(`Arquivo: ${arq.nome_original}`);
  console.log(`Tipo: ${arq.tipo} (${arq.mime_type})`);
  const tamanhoKb = (arq.tamanho / 1024).toFixed(1);
  console.log(`Tamanho: ${tamanhoKb} KB`);
  console.log(`Público: ${arq.publico ? "Sim" : "Não"}`);
  console.log(`Caminho: ${arq.caminho_completo}`);
} else {
  console.error(`Erro: ${JSON.stringify(dados)}`);
}

Resposta (200 OK)

json
{
  "success": true,
  "message": "Registro encontrado",
  "data": {
    "id": 1,
    "nome_original": "camiseta-basica-frente.jpg",
    "extensao": "jpg",
    "mime_type": "image/jpeg",
    "modulo": "produtos",
    "tipo": "imagem",
    "tamanho": 245760,
    "publico": true,
    "ativo": true,
    "criado_em": "2026-02-10T14:30:00-03:00",
    "descricao": "Foto frontal da camiseta básica algodão - cor branca",
    "caminho_completo": "empresas/1/produtos/2026/02/camiseta-basica-frente.jpg",
    "atualizado_em": "2026-02-10T14:30:00-03:00"
  }
}

Campos do Detalhe (adicionais à listagem)

---

Criar Arquivo (Não Suportado)

POST /v1/arquivos/

Resposta (405 Method Not Allowed)

json
{
  "success": false,
  "error": {
    "code": "NOT_SUPPORTED",
    "message": "Upload de arquivos via API não é suportado. Utilize o painel para fazer upload de arquivos."
  }
}

---

Atualizar Metadados do Arquivo

PUT /v1/arquivos/{id}/

PATCH /v1/arquivos/{id}/

Escopo necessário: arquivos: write

Atualiza apenas os metadados de um arquivo existente. O conteúdo do arquivo em si não pode ser alterado via API. Use PUT para atualização completa ou PATCH para atualização parcial.

Campos do Request Body

Exemplo com cURL (PATCH - atualização parcial)

bash
curl -X PATCH https://api-backend.bunto.com.br/v1/arquivos/1/ \
  -H 'Authorization: Bearer bnt_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9t0U1v2W3x4' \
  -H 'Content-Type: application/json' \
  -d '{
    "descricao": "Foto frontal da camiseta básica algodão - cor branca, tamanho M",
    "publico": 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",
}

arquivo_id = 1

# Atualização parcial (PATCH) - apenas os metadados que mudaram
atualizacao = {
    "descricao": "Foto frontal da camiseta básica algodão - cor branca, tamanho M",
    "publico": True,
}

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

dados = resposta.json()

if dados["success"]:
    arq = dados["data"]
    print(f"Arquivo atualizado! Descrição: {arq['descricao']}")
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 arquivoId = 1;

const atualizacao = {
  descricao:
    "Foto frontal da camiseta básica algodão - cor branca, tamanho M",
  publico: true,
};

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

const dados = await resposta.json();

if (dados.success) {
  console.log(`Arquivo atualizado! Descrição: ${dados.data.descricao}`);
} else {
  console.error(`Erro ao atualizar:`, dados);
}

Resposta (200 OK)

json
{
  "success": true,
  "message": "Arquivo atualizado com sucesso",
  "data": {
    "id": 1,
    "nome_original": "camiseta-basica-frente.jpg",
    "extensao": "jpg",
    "mime_type": "image/jpeg",
    "modulo": "produtos",
    "tipo": "imagem",
    "tamanho": 245760,
    "publico": true,
    "ativo": true,
    "criado_em": "2026-02-10T14:30:00-03:00",
    "descricao": "Foto frontal da camiseta básica algodão - cor branca, tamanho M",
    "caminho_completo": "empresas/1/produtos/2026/02/camiseta-basica-frente.jpg",
    "atualizado_em": "2026-02-12T17:15:00-03:00"
  }
}

---

Desativar Arquivo (Soft Delete)

DELETE /v1/arquivos/{id}/

Escopo necessário: arquivos: delete

Desativa o arquivo (soft delete). O registro não é removido permanentemente do banco de dados e o arquivo físico não é excluído do armazenamento -- o campo ativo é definido como false.

Exemplo com cURL

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

arquivo_id = 1
resposta = requests.delete(f"{BASE_URL}/arquivos/{arquivo_id}/", headers=headers)
dados = resposta.json()

if dados["success"]:
    print(f"Arquivo desativado com sucesso!")
else:
    print(f"Erro ao desativar: {dados}")

Exemplo com JavaScript

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

const arquivoId = 1;

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

const dados = await resposta.json();

if (dados.success) {
  console.log("Arquivo desativado com sucesso!");
} else {
  console.error(`Erro ao desativar:`, dados);
}

Resposta (200 OK)

json
{
  "success": true,
  "message": "Arquivo desativado com sucesso"
}

---

Erros Comuns

Exemplo de Resposta de Erro (405)

json
{
  "success": false,
  "error": {
    "code": "NOT_SUPPORTED",
    "message": "Upload de arquivos via API não é suportado. Utilize o painel para fazer upload de arquivos."
  }
}

Exemplo de Resposta de Erro (403)

json
{
  "detail": "Token não tem permissão 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 requisições excedido. Tente novamente em 45 segundos."
}

Boas práticas

• Use por_pagina=100 para reduzir o número de requisições ao listar arquivos
• Implemente retry com backoff exponencial ao receber 429
• Use os filtros modulo e tipo para reduzir o volume de dados retornados
• Para atualizações em lote de metadados, use PATCH apenas com os campos alterados

---

Paginação

Todos os endpoints de listagem retornam dados paginados.

Parâmetros

Objeto paginacao na resposta

---

Limitações

• Upload não suportado: Não é possível fazer upload de arquivos via API. Use o painel do Bunto ERP.
• Conteúdo imutável: O conteúdo do arquivo em si não pode ser alterado via API, apenas seus metadados.
• Somente metadados: Este endpoint não retorna o conteúdo binário do arquivo, apenas informações sobre ele.
• Soft delete: Ao desativar um arquivo, o arquivo físico permanece no armazenamento. A desativação apenas impede que ele apareça nas listagens.