API de Compras

Gerencie os pedidos de compra do Bunto ERP. Este endpoint permite listar, consultar, criar, atualizar e excluir pedidos de compra com itens via API.

Base URL

Produção:

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

Autenticação

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

Authorization: Bearer bnt_seu_token_aqui

Tokens são gerados em Integrações -> Tokens de API no painel do Bunto ERP. Escopo necessário: compras com a ação correspondente (read, write ou delete).

Endpoints

Listar Pedidos de Compra

GET /v1/compras/

Escopo necessário: compras: read

Retorna a lista paginada de pedidos de compra da empresa.

Query Parameters

Parâmetro	Tipo	Padrão	Descrição
`pagina`	integer	1	Número da página
`por_pagina`	integer	25	Registros por página (máximo: 100)
`busca`	string	-	Busca por número do pedido ou ordem de compra
`status`	string	-	Filtrar por status: `em_aberto`, `em_andamento`, `atendida`, `cancelada`
`fornecedor_id`	integer	-	Filtrar por ID do fornecedor
`data_inicio`	string	-	Data início da compra (formato: YYYY-MM-DD)
`data_fim`	string	-	Data fim da compra (formato: YYYY-MM-DD)
`ordenar`	string	`data_compra`	Campo de ordenação: `data_compra`, `total_pedido`, `status`, `id_interno`
`direcao`	string	`asc`	Direção da ordenação: `asc` ou `desc`

Exemplo com cURL

bash
curl 'https://api-backend.bunto.com.br/v1/compras/?pagina=1&por_pagina=10&status=em_aberto&ordenar=data_compra&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 pedidos em aberto ordenados por data mais recente
resposta = requests.get(
    f"{BASE_URL}/compras/",
    headers=headers,
    params={
        "pagina": 1,
        "por_pagina": 25,
        "status": "em_aberto",
        "ordenar": "data_compra",
        "direcao": "desc",
    },
)

dados = resposta.json()

if dados["success"]:
    pedidos = dados["data"]["resultados"]
    paginacao = dados["data"]["paginacao"]
    print(f"Total de pedidos: {paginacao['total_registros']}")
    for pedido in pedidos:
        print(f"  - #{pedido['id_interno']} | {pedido['fornecedor_nome']} | R$ {pedido['total_pedido']} | {pedido['data_compra']}")
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",
  status: "em_aberto",
  ordenar: "data_compra",
  direcao: "desc",
});

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

const dados = await resposta.json();

if (dados.success) {
  const pedidos = dados.data.resultados;
  const paginacao = dados.data.paginacao;
  console.log(`Total de pedidos: ${paginacao.total_registros}`);
  pedidos.forEach((pedido) => {
    console.log(`  - #${pedido.id_interno} | ${pedido.fornecedor_nome} | R$ ${pedido.total_pedido} | ${pedido.data_compra}`);
  });
} else {
  console.error(`Erro: ${resposta.status}`);
}

Resposta (200 OK)

json
{
  "success": true,
  "message": "3 registros encontrados",
  "data": {
    "resultados": [
      {
        "id": 45,
        "id_interno": 1012,
        "numero_pedido": "PC-2026-0045",
        "fornecedor_id": 15,
        "fornecedor_nome": "Distribuidora Nacional Ltda",
        "status": "em_aberto",
        "data_compra": "2026-02-10",
        "numero_itens": 5,
        "total_pedido": "8750.00"
      },
      {
        "id": 44,
        "id_interno": 1011,
        "numero_pedido": "PC-2026-0044",
        "fornecedor_id": 8,
        "fornecedor_nome": "Atacado Brasil ME",
        "status": "em_aberto",
        "data_compra": "2026-02-08",
        "numero_itens": 12,
        "total_pedido": "15320.50"
      },
      {
        "id": 42,
        "id_interno": 1009,
        "numero_pedido": null,
        "fornecedor_id": 22,
        "fornecedor_nome": "Indústria Modelo S.A.",
        "status": "em_aberto",
        "data_compra": "2026-02-05",
        "numero_itens": 3,
        "total_pedido": "4200.00"
      }
    ],
    "paginacao": {
      "pagina_atual": 1,
      "total_paginas": 1,
      "total_registros": 3,
      "por_pagina": 25,
      "proxima": null,
      "anterior": null
    }
  }
}

Campos da Listagem

Campo	Tipo	Descrição
`id`	integer	Identificador único do pedido de compra
`id_interno`	integer	Número sequencial interno do pedido
`numero_pedido`	string / null	Número do pedido informado pelo usuário
`fornecedor_id`	integer / null	ID do fornecedor
`fornecedor_nome`	string / null	Nome do fornecedor
`status`	string	Status do pedido: `em_aberto`, `em_andamento`, `atendida`, `cancelada`
`data_compra`	string (date)	Data da compra (formato: YYYY-MM-DD)
`numero_itens`	integer	Quantidade de itens no pedido
`total_pedido`	string (decimal)	Valor total do pedido (formato: "8750.00")

Obter Pedido de Compra

GET /v1/compras/{id}/

Escopo necessário: compras: read

Retorna os dados completos de um pedido de compra específico, incluindo a lista de itens, valores de impostos, frete e observações.

Exemplo com cURL

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

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

if dados["success"]:
    pedido = dados["data"]
    print(f"Pedido #{pedido['id_interno']} | {pedido['fornecedor_nome']}")
    print(f"Status: {pedido['status']} | Total: R$ {pedido['total_pedido']}")
    print(f"Frete: R$ {pedido['frete']} | IPI: R$ {pedido['total_ipi']}")
    if pedido["itens"]:
        print("Itens:")
        for item in pedido["itens"]:
            print(f"  - {item['produto_descricao']} | {item['quantidade']} x R$ {item['preco_unitario']} = R$ {item['preco_total']}")
else:
    print(f"Erro: {dados}")

Exemplo com JavaScript

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

const pedidoId = 45;

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

const dados = await resposta.json();

if (dados.success) {
  const pedido = dados.data;
  console.log(`Pedido #${pedido.id_interno} | ${pedido.fornecedor_nome}`);
  console.log(`Status: ${pedido.status} | Total: R$ ${pedido.total_pedido}`);
  console.log(`Frete: R$ ${pedido.frete} | IPI: R$ ${pedido.total_ipi}`);
  if (pedido.itens && pedido.itens.length > 0) {
    console.log("Itens:");
    pedido.itens.forEach((item) => {
      console.log(`  - ${item.produto_descricao} | ${item.quantidade} x R$ ${item.preco_unitario} = R$ ${item.preco_total}`);
    });
  }
} else {
  console.error(`Erro: ${JSON.stringify(dados)}`);
}

Resposta (200 OK)

json
{
  "success": true,
  "message": "Registro encontrado",
  "data": {
    "id": 45,
    "id_interno": 1012,
    "numero_pedido": "PC-2026-0045",
    "fornecedor_id": 15,
    "fornecedor_nome": "Distribuidora Nacional Ltda",
    "status": "em_aberto",
    "data_compra": "2026-02-10",
    "numero_itens": 5,
    "total_pedido": "8750.00",
    "ordem_compra": "OC-001",
    "data_prevista": "2026-02-25",
    "total_produtos": "8200.00",
    "total_icms_st": "0.00",
    "total_ipi": "350.00",
    "frete": "200.00",
    "transportador_id": 3,
    "categoria_id": 12,
    "observacoes":"Entrega parcial autorizada. Conferir volumes na recepção.",
    "data_criacao": "2026-02-10T09:15:00-03:00",
    "data_atualizacao": "2026-02-10T09:15:00-03:00",
    "itens": [
      {
        "id": 201,
        "produto_id": 87,
        "produto_descricao": "Camiseta Basica Branca M",
        "quantidade": "100.000",
        "preco_unitario": "25.00",
        "preco_total": "2500.00",
        "unidade": "UN",
        "codigo":"CAM-BB-M"
      },
      {
        "id": 202,
        "produto_id": 88,
        "produto_descricao": "Camiseta Basica Preta G",
        "quantidade": "80.000",
        "preco_unitario": "25.00",
        "preco_total": "2000.00",
        "unidade": "UN",
        "codigo":"CAM-BP-G"
      },
      {
        "id": 203,
        "produto_id": 112,
        "produto_descricao": "Bermuda Jeans Azul 42",
        "quantidade": "50.000",
        "preco_unitario": "45.00",
        "preco_total": "2250.00",
        "unidade": "UN",
        "codigo":"BER-Ja-42"
      },
      {
        "id": 204,
        "produto_id": 95,
        "produto_descricao": "Boné Aba Reta Preto",
        "quantidade": "60.000",
        "preco_unitario": "18.00",
        "preco_total": "1080.00",
        "unidade": "UN",
        "codigo":"BON-AR-P"
      },
      {
        "id": 205,
        "produto_id": 130,
        "produto_descricao": "Meia Esportiva Cano Alto",
        "quantidade": "200.000",
        "preco_unitario": "1.85",
        "preco_total": "370.00",
        "unidade": "PAR",
        "codigo":"MEI-EC-CA"
      }
    ]
  }
}

Campos do Detalhe (adicionais à listagem)

Campo	Tipo	Descrição
`ordem_compra`	string / null	Número da ordem de compra (máximo 30 caracteres)
`data_prevista`	string / null	Data prevista de entrega (formato: YYYY-MM-DD)
`total_produtos`	string (decimal)	Subtotal dos produtos (sem impostos nem frete)
`total_icms_st`	string (decimal)	Total de ICMS-ST do pedido
`total_ipi`	string (decimal)	Total de IPI do pedido
`frete`	string (decimal)	Valor do frete
`transportador_id`	integer / null	ID do transportador
`categoria_id`	integer / null	ID da categoria de compra
`observacoes`	string / null	Observações do pedido
`data_criacao`	datetime	Data e hora de criação
`data_atualizacao`	datetime	Data e hora da última atualização
`itens`	array	Lista de itens do pedido (máximo 200 itens retornados)

Campos de Cada Item

Campo	Tipo	Descrição
`id`	integer	Identificador único do item
`produto_id`	integer	ID do produto
`produto_descricao`	string	Descrição do produto
`quantidade`	string (decimal)	Quantidade comprada
`preco_unitario`	string (decimal)	Preço unitário
`preco_total`	string (decimal)	Preço total do item (quantidade x preço unitário)
`unidade`	string	Unidade de medida (UN, KG, CX, PAR, etc.)
`codigo`	string	Código do produto

Criar Pedido de Compra

POST /v1/compras/

Escopo necessário: compras: write

Cria um novo pedido de compra na empresa do token autenticado. Pode incluir itens no mesmo request.

Campos do Request Body

Campo	Tipo	Obrigatório	Descrição
`fornecedor_id`	integer	Sim	ID do fornecedor
`data_compra`	string	Não	Data da compra (formato: YYYY-MM-DD, padrão: data atual)
`numero_pedido`	string	Não	Número do pedido (máximo 20 caracteres)
`ordem_compra`	string	Não	Número da ordem de compra (máximo 30 caracteres)
`status`	string	Não	Status inicial: `em_aberto`, `em_andamento`, `atendida`, `cancelada` (padrão: `em_aberto`)
`data_prevista`	string	Não	Data prevista de entrega (formato: YYYY-MM-DD)
`frete`	decimal	Não	Valor do frete (padrão: 0.00)
`transportador_id`	integer	Não	ID do transportador
`categoria_id`	integer	Não	ID da categoria de compra
`observacoes`	string	Não	Observações do pedido
`itens`	array	Não	Lista de itens do pedido (padrão: lista vazia)

Campos de Cada Item (dentro do array `itens`)

Campo	Tipo	Obrigatório	Descrição
`produto_id`	integer	Sim	ID do produto
`quantidade`	decimal	Sim	Quantidade a comprar
`preco_unitario`	decimal	Sim	Preço unitário

Exemplo com cURL

bash
curl -X POST https://api-backend.bunto.com.br/v1/compras/ \
  -H 'Authorization: Bearer bnt_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9t0U1v2W3x4' \
  -H 'Content-Type: application/json' \
  -d '{
    "fornecedor_id": 15,
    "data_compra": "2026-02-12",
    "numero_pedido": "PC-2026-0050",
    "ordem_compra": "OC-005",
    "data_prevista": "2026-03-01",
    "frete": "150.00",
    "transportador_id": 3,
    "observacoes":"Pedido urgente - priorizar despacho.",
    "itens": [
      {
        "produto_id": 87,
        "quantidade": "50.000",
        "preco_unitario": "25.00"
      },
      {
        "produto_id": 112,
        "quantidade": "30.000",
        "preco_unitario": "45.00"
      }
    ]
  }'

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",
}

novo_pedido = {
    "fornecedor_id": 15,
    "data_compra": "2026-02-12",
    "numero_pedido": "PC-2026-0050",
    "ordem_compra": "OC-005",
    "data_prevista": "2026-03-01",
    "frete": "150.00",
    "transportador_id": 3,
    "observacoes":"Pedido urgente - priorizar despacho.",
    "itens": [
        {
            "produto_id": 87,
            "quantidade": "50.000",
            "preco_unitario": "25.00",
        },
        {
            "produto_id": 112,
            "quantidade": "30.000",
            "preco_unitario": "45.00",
        },
    ],
}

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

if dados["success"]:
    pedido = dados["data"]
    print(f"Pedido criado com sucesso! ID: {pedido['id']} | Interno: #{pedido['id_interno']}")
    print(f"Total: R$ {pedido['total_pedido']} | Itens: {pedido['numero_itens']}")
else:
    print(f"Erro ao criar pedido: {dados}")

Exemplo com JavaScript

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

const novoPedido = {
  fornecedor_id: 15,
  data_compra: "2026-02-12",
  numero_pedido: "PC-2026-0050",
  ordem_compra: "OC-005",
  data_prevista: "2026-03-01",
  frete: "150.00",
  transportador_id: 3,
  observacoes: "Pedido urgente - priorizar despacho.",
  itens: [
    {
      produto_id: 87,
      quantidade: "50.000",
      preco_unitario: "25.00",
    },
    {
      produto_id: 112,
      quantidade: "30.000",
      preco_unitario: "45.00",
    },
  ],
};

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

const dados = await resposta.json();

if (dados.success) {
  console.log(`Pedido criado com sucesso! ID: ${dados.data.id} | Interno: #${dados.data.id_interno}`);
  console.log(`Total: R$ ${dados.data.total_pedido} | Itens: ${dados.data.numero_itens}`);
} else {
  console.error(`Erro ao criar pedido:`, dados);
}

Resposta (201 Created)

json
{
  "success": true,
  "message": "Pedido de compra criado com sucesso",
  "data": {
    "id": 50,
    "id_interno": 1015,
    "numero_pedido": "PC-2026-0050",
    "fornecedor_id": 15,
    "fornecedor_nome": "Distribuidora Nacional Ltda",
    "status": "em_aberto",
    "data_compra": "2026-02-12",
    "numero_itens": 2,
    "total_pedido": "2750.00",
    "ordem_compra": "OC-005",
    "data_prevista": "2026-03-01",
    "total_produtos": "2600.00",
    "total_icms_st": "0.00",
    "total_ipi": "0.00",
    "frete": "150.00",
    "transportador_id": 3,
    "categoria_id": null,
    "observacoes":"Pedido urgente - priorizar despacho.",
    "data_criacao": "2026-02-12T16:30:00-03:00",
    "data_atualizacao": "2026-02-12T16:30:00-03:00",
    "itens": [
      {
        "id": 210,
        "produto_id": 87,
        "produto_descricao": "Camiseta Basica Branca M",
        "quantidade": "50.000",
        "preco_unitario": "25.00",
        "preco_total": "1250.00",
        "unidade": "UN",
        "codigo":"CAM-BB-M"
      },
      {
        "id": 211,
        "produto_id": 112,
        "produto_descricao": "Bermuda Jeans Azul 42",
        "quantidade": "30.000",
        "preco_unitario": "45.00",
        "preco_total": "1350.00",
        "unidade": "UN",
        "codigo":"BER-Ja-42"
      }
    ]
  }
}

Atualizar Pedido de Compra

PUT /v1/compras/{id}/

PATCH /v1/compras/{id}/

Escopo necessário: compras: write

Atualiza um pedido de compra 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/compras/50/ \
  -H 'Authorization: Bearer bnt_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9t0U1v2W3x4' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "em_andamento",
    "data_prevista": "2026-03-05",
    "observacoes":"Pedido confirmado pelo fornecedor. Previsão atualizada para 05/03."
  }'

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",
}

pedido_id = 50

# Atualizacao parcial (PATCH) - apenas os campos que mudaram
atualizacao = {
    "status": "em_andamento",
    "data_prevista": "2026-03-05",
    "observacoes":"Pedido confirmado pelo fornecedor. Previsão atualizada para 05/03.",
}

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

dados = resposta.json()

if dados["success"]:
    pedido = dados["data"]
    print(f"Pedido atualizado! Status: {pedido['status']}")
    print(f"Nova previsão: {pedido['data_prevista']}")
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 pedidoId = 50;

const atualizacao = {
  status: "em_andamento",
  data_prevista: "2026-03-05",
  observacoes: "Pedido confirmado pelo fornecedor. Previsão atualizada para 05/03.",
};

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

const dados = await resposta.json();

if (dados.success) {
  console.log(`Pedido atualizado! Status: ${dados.data.status}`);
  console.log(`Nova previsão: ${dados.data.data_prevista}`);
} else {
  console.error(`Erro ao atualizar:`, dados);
}

Resposta (200 OK)

json
{
  "success": true,
  "message": "Pedido de compra atualizado com sucesso",
  "data": {
    "id": 50,
    "id_interno": 1015,
    "numero_pedido": "PC-2026-0050",
    "fornecedor_id": 15,
    "fornecedor_nome": "Distribuidora Nacional Ltda",
    "status": "em_andamento",
    "data_compra": "2026-02-12",
    "numero_itens": 2,
    "total_pedido": "2750.00",
    "ordem_compra": "OC-005",
    "data_prevista": "2026-03-05",
    "total_produtos": "2600.00",
    "total_icms_st": "0.00",
    "total_ipi": "0.00",
    "frete": "150.00",
    "transportador_id": 3,
    "categoria_id": null,
    "observacoes":"Pedido confirmado pelo fornecedor. Previsão atualizada para 05/03.",
    "data_criacao": "2026-02-12T16:30:00-03:00",
    "data_atualizacao": "2026-02-12T17:45:00-03:00",
    "itens": [
      {
        "id": 210,
        "produto_id": 87,
        "produto_descricao": "Camiseta Basica Branca M",
        "quantidade": "50.000",
        "preco_unitario": "25.00",
        "preco_total": "1250.00",
        "unidade": "UN",
        "codigo":"CAM-BB-M"
      },
      {
        "id": 211,
        "produto_id": 112,
        "produto_descricao": "Bermuda Jeans Azul 42",
        "quantidade": "30.000",
        "preco_unitario": "45.00",
        "preco_total": "1350.00",
        "unidade": "UN",
        "codigo":"BER-Ja-42"
      }
    ]
  }
}

Excluir Pedido de Compra

DELETE /v1/compras/{id}/

Escopo necessário: compras: delete

Exclui o pedido de compra. O comportamento depende do status do pedido -- pedidos em aberto podem ser excluídos permanentemente, enquanto pedidos já atendidos ou em andamento são cancelados via soft delete para preservar o histórico.

Exemplo com cURL

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

pedido_id = 50
resposta = requests.delete(f"{BASE_URL}/compras/{pedido_id}/", headers=headers)
dados = resposta.json()

if dados["success"]:
    print("Pedido de compra excluído com sucesso!")
else:
    print(f"Erro ao excluir: {dados}")

Exemplo com JavaScript

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

const pedidoId = 50;

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

const dados = await resposta.json();

if (dados.success) {
  console.log("Pedido de compra excluído com sucesso!");
} else {
  console.error(`Erro ao excluir:`, dados);
}

Resposta (200 OK)

json
{
  "success": true,
  "message": "Registro excluído com sucesso"
}

Importante: Pedidos de compra que já geraram contas financeiras ou movimentações de estoque não podem ser excluídos permanentemente. Nesses casos, o pedido é cancelado (soft delete) para preservar a integridade dos dados financeiros e de estoque.

Erros Comuns

Código	Erro	Causa	Solução
400	`VALIDATION_ERROR`	Dados enviados são inválidos (campo obrigatório ausente, formato incorreto, status inválido, etc.)	Verifique os campos obrigatórios e os tipos de dados
401	`Token invalido`	Token ausente, expirado, revogado ou mal formatado	Verifique se o header é `Authorization: Bearer bnt_xxx`
403	`Token nao tem permissao`	O token não possui o escopo `compras` ou a ação necessária (`read`, `write`, `delete`)	Verifique os escopos do token no painel
404	`Nao encontrado`	Pedido de compra não existe ou pertence a outra empresa	Confirme o ID e se o pedido pertence à empresa do token
429	`Limite de requisicoes excedido`	Rate limit ultrapassado para o tipo de operação	Implemente retry com backoff exponencial

Exemplo de Resposta de Erro (400)

json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Erro de validacao",
    "details": {
      "fornecedor_id": ["Este campo é obrigatorio."],
      "status": ["\"pendente\" nao é um escolha valido. Escolha entre: em_aberto, em_andamento, atendida, cancelada."]
    }
  }
}

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.

Operação	Métodos HTTP	Limite
Leitura	GET, HEAD, OPTIONS	120 requisições/minuto
Escrita	POST, PUT, PATCH	30 requisições/minuto
Exclusão	DELETE	10 requisições/minuto

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 pedidos de compra
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
Ao criar pedidos com muitos itens, envie todos os itens no mesmo request para evitar múltiplas chamadas

Paginação

Todos os endpoints de listagem retornam dados paginados.

Parâmetros

Parâmetro	Tipo	Padrão	Máximo	Descrição
`pagina`	integer	1	-	Número da página
`por_pagina`	integer	25	100	Registros por página

Atenção: Os parâmetros são pagina e por_pagina (em português), não page e per_page.

Objeto `paginacao` na resposta

Campo	Tipo	Descrição
`pagina_atual`	integer	Número da página atual
`total_paginas`	integer	Total de páginas disponíveis
`total_registros`	integer	Total de registros encontrados
`por_pagina`	integer	Registros por página
`proxima`	string / null	URL da próxima página (null se for a última)
`anterior`	string / null	URL da página anterior (null se for a primeira)

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}"}

todos_os_pedidos = []
url = f"{BASE_URL}/compras/?por_pagina=100"

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

    if not dados["success"]:
        break

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

print(f"Total obtido: {len(todos_os_pedidos)} pedidos de compra")

Base URL

Autenticação

Endpoints

Listar Pedidos de Compra

Query Parameters

Exemplo com cURL

Exemplo com Python

Exemplo com JavaScript

Resposta (200 OK)

Campos da Listagem

Obter Pedido de Compra

Exemplo com cURL

Exemplo com Python

Exemplo com JavaScript

Resposta (200 OK)

Campos do Detalhe (adicionais à listagem)

Campos de Cada Item

Criar Pedido de Compra

Campos do Request Body

Campos de Cada Item (dentro do array itens)

Exemplo com cURL

Exemplo com Python

Exemplo com JavaScript

Resposta (201 Created)

Atualizar Pedido de Compra

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

Exemplo com Python

Exemplo com JavaScript

Resposta (200 OK)

Excluir Pedido de Compra

Exemplo com cURL

Exemplo com Python

Exemplo com JavaScript

Resposta (200 OK)

Erros Comuns

Exemplo de Resposta de Erro (400)

Exemplo de Resposta de Erro (403)

Rate Limiting

Boas práticas

Paginação

Parâmetros

Objeto paginacao na resposta

Exemplo: percorrer todas as páginas (Python)

Campos de Cada Item (dentro do array `itens`)

Objeto `paginacao` na resposta