API de Embalagens

Gerencie o cadastro de embalagens da sua empresa via API. Consulte, crie, atualize e exclua registros de embalagens de forma programática.

---

Visão Geral

---

Endpoints

---

Listar Embalagens

GET /v1/embalagens/

Escopo necessário: embalagens: read

Retorna uma lista paginada de embalagens da empresa. Embalagens com situação E (Excluído) são automaticamente excluídas da listagem.

Parâmetros de consulta

Campos retornados na listagem

Exemplo com cURL

bash
curl 'https://api-backend.bunto.com.br/v1/embalagens/?pagina=1&por_pagina=10&busca=caixa&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 embalagens com filtros
resposta = requests.get(
    f"{BASE_URL}/embalagens/",
    headers=headers,
    params={
        "pagina": 1,
        "por_pagina": 25,
        "situacao":"A",
        "ordenar": "descricao",
        "direcao": "asc",
    },
)

dados = resposta.json()

if dados["success"]:
    embalagens = dados["data"]["resultados"]
    paginacao = dados["data"]["paginacao"]
    print(f"Total de embalagens: {paginacao['total_registros']}")
    for embalagem in embalagens:
        print(f"  - {embalagem['descricao']} ({embalagem['tipo_nome']}) - {embalagem['peso']} kg")
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",
  situacao: "A",
  ordenar: "descricao",
  direcao: "asc",
});

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

const dados = await resposta.json();

if (dados.success) {
  const embalagens = dados.data.resultados;
  const paginacao = dados.data.paginacao;
  console.log(`Total de embalagens: ${paginacao.total_registros}`);
  embalagens.forEach((embalagem) => {
    console.log(`  - ${embalagem.descricao} (${embalagem.tipo_nome}) - ${embalagem.peso} kg`);
  });
} else {
  console.error(`Erro: ${resposta.status}`);
}

Resposta de sucesso (200)

json
{
  "success": true,
  "message": "18 registros encontrados",
  "data": {
    "resultados": [
      {
        "id": 1,
        "descricao":"Caixa Correios Pequena",
        "altura": "14.000",
        "largura": "18.000",
        "comprimento_profundidade": "27.000",
        "peso": "0.150",
        "situacao":"A",
        "tipo_nome": "Caixa"
      },
      {
        "id": 2,
        "descricao":"Envelope Acolchoado Médio",
        "altura": "2.000",
        "largura": "26.000",
        "comprimento_profundidade": "36.000",
        "peso": "0.080",
        "situacao":"A",
        "tipo_nome": "Envelope"
      }
    ],
    "paginacao": {
      "pagina_atual": 1,
      "total_paginas": 1,
      "total_registros": 18,
      "por_pagina": 25,
      "proxima": null,
      "anterior": null
    }
  }
}

---

Detalhar Embalagem

GET /v1/embalagens/{id}/

Escopo necessário: embalagens: read

Retorna os dados completos de uma embalagem específica, incluindo campos adicionais como diâmetro, tipo de embalagem e indicador de embalagem padrão.

Parâmetros de rota

Campos retornados no detalhe

Além de todos os campos da listagem, o detalhe inclui:

Exemplo com cURL

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

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

if dados["success"]:
    embalagem = dados["data"]
    print(f"Descricao: {embalagem['descricao']}")
    print(f"Dimensões: {embalagem['largura']}cm x {embalagem['altura']}cm x {embalagem['comprimento_profundidade']}cm")
    print(f"Peso: {embalagem['peso']} kg")
    print(f"Padrao: {'Sim' if embalagem['padrao'] else 'Nao'}")
else:
    print(f"Erro: {dados}")

Exemplo com JavaScript

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

const embalagemId = 1;

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

const dados = await resposta.json();

if (dados.success) {
  const embalagem = dados.data;
  console.log(`Descricao: ${embalagem.descricao}`);
  console.log(`Dimensões: ${embalagem.largura}cm x ${embalagem.altura}cm x ${embalagem.comprimento_profundidade}cm`);
  console.log(`Peso: ${embalagem.peso} kg`);
  console.log(`Padrao: ${embalagem.padrao ? "Sim" : "Nao"}`);
} else {
  console.error(`Erro: ${JSON.stringify(dados)}`);
}

Resposta de sucesso (200)

json
{
  "success": true,
  "message": "Registro encontrado",
  "data": {
    "id": 1,
    "descricao":"Caixa Correios Pequena",
    "altura": "14.000",
    "largura": "18.000",
    "comprimento_profundidade": "27.000",
    "peso": "0.150",
    "situacao":"A",
    "tipo_nome": "Caixa",
    "diametro": null,
    "embalagem_tipo_id": 2,
    "padrao":true,
    "criado_em": "2026-01-10T09:00:00-03:00",
    "atualizado_em": "2026-02-05T11:30:00-03:00"
  }
}

---

Criar Embalagem

POST /v1/embalagens/

Escopo necessário: embalagens: write

Cria uma nova embalagem na empresa do token autenticado.

Campos do body

Exemplo com cURL

bash
curl -X POST https://api-backend.bunto.com.br/v1/embalagens/ \
  -H 'Authorization: Bearer bnt_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9t0U1v2W3x4' \
  -H 'Content-Type: application/json' \
  -d '{
    "descricao":"Caixa Papelão Reforçada Grande",
    "embalagem_tipo_id": 2,
    "altura": 40.0,
    "largura": 50.0,
    "comprimento_profundidade": 60.0,
    "peso": 0.850,
    "situacao":"A"
  }'

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_embalagem = {
    "descricao":"Caixa Papelão Reforçada Grande",
    "embalagem_tipo_id": 2,
    "altura": 40.0,
    "largura": 50.0,
    "comprimento_profundidade": 60.0,
    "peso": 0.850,
    "situacao":"A",
}

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

if dados["success"]:
    embalagem = dados["data"]
    print(f"Embalagem criada com sucesso! ID: {embalagem['id']}")
    print(f"Descricao: {embalagem['descricao']}")
else:
    print(f"Erro ao criar embalagem: {dados}")

Exemplo com JavaScript

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

const novaEmbalagem = {
  descricao: "Caixa Papelão Reforçada Grande",
  embalagem_tipo_id: 2,
  altura: 40.0,
  largura: 50.0,
  comprimento_profundidade: 60.0,
  peso: 0.85,
  situacao: "A",
};

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

const dados = await resposta.json();

if (dados.success) {
  console.log(`Embalagem criada com sucesso! ID: ${dados.data.id}`);
  console.log(`Descricao: ${dados.data.descricao}`);
} else {
  console.error(`Erro ao criar embalagem:`, dados);
}

Resposta de sucesso (201)

json
{
  "success": true,
  "message": "Registro criado com sucesso",
  "data": {
    "id": 19,
    "descricao":"Caixa Papelão Reforçada Grande",
    "altura": "40.000",
    "largura": "50.000",
    "comprimento_profundidade": "60.000",
    "peso": "0.850",
    "situacao":"A",
    "tipo_nome": "Caixa",
    "diametro": null,
    "embalagem_tipo_id": 2,
    "padrao":false,
    "criado_em": "2026-02-12T15:30:00-03:00",
    "atualizado_em": "2026-02-12T15:30:00-03:00"
  }
}

---

Atualizar Embalagem

Atualização completa

PUT /v1/embalagens/{id}/

Atualiza todos os campos da embalagem. Campos não enviados serão definidos como null (exceto campos obrigatórios).

Atualização parcial

PATCH /v1/embalagens/{id}/

Atualiza apenas os campos enviados no body. Campos omitidos permanecem inalterados.

Escopo necessário: embalagens: write

Exemplo com cURL (PATCH)

bash
curl -X PATCH https://api-backend.bunto.com.br/v1/embalagens/19/ \
  -H 'Authorization: Bearer bnt_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9t0U1v2W3x4' \
  -H 'Content-Type: application/json' \
  -d '{
    "peso": 0.920,
    "altura": 42.0,
    "descricao":"Caixa Papelão Reforçada Grande (Revisada)"
  }'

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

embalagem_id = 19

# Atualizacao parcial (PATCH) - apenas os campos que mudaram
atualizacao = {
    "peso": 0.920,
    "altura": 42.0,
    "descricao":"Caixa Papelão Reforçada Grande (Revisada)",
}

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

dados = resposta.json()

if dados["success"]:
    embalagem = dados["data"]
    print(f"Embalagem atualizada! Novo peso: {embalagem['peso']} kg")
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 embalagemId = 19;

const atualizacao = {
  peso: 0.92,
  altura: 42.0,
  descricao: "Caixa Papelão Reforçada Grande (Revisada)",
};

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

const dados = await resposta.json();

if (dados.success) {
  console.log(`Embalagem atualizada! Novo peso: ${dados.data.peso} kg`);
} else {
  console.error(`Erro ao atualizar:`, dados);
}

Resposta de sucesso (200)

json
{
  "success": true,
  "message": "Registro atualizado com sucesso",
  "data": {
    "id": 19,
    "descricao":"Caixa Papelão Reforçada Grande (Revisada)",
    "altura": "42.000",
    "largura": "50.000",
    "comprimento_profundidade": "60.000",
    "peso": "0.920",
    "situacao":"A",
    "tipo_nome": "Caixa",
    "diametro": null,
    "embalagem_tipo_id": 2,
    "padrao":false,
    "criado_em": "2026-02-12T15:30:00-03:00",
    "atualizado_em": "2026-02-12T16:45:00-03:00"
  }
}

---

Excluir Embalagem (Soft Delete)

DELETE /v1/embalagens/{id}/

Escopo necessário: embalagens: delete

Exclui a embalagem via soft delete. O registro não é removido permanentemente do banco de dados -- o campo situacao é alterado para E (Excluído), preservando o histórico de uso em pedidos e envios.

Exemplo com cURL

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

embalagem_id = 19
resposta = requests.delete(f"{BASE_URL}/embalagens/{embalagem_id}/", headers=headers)
dados = resposta.json()

if dados["success"]:
    print("Embalagem excluída com sucesso!")
else:
    print(f"Erro ao excluir: {dados['message']}")

Exemplo com JavaScript

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

const embalagemId = 19;

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

const dados = await resposta.json();

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

Resposta de sucesso (200)

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

---

Erros

Validação (400)

Retornado quando os dados enviados são inválidos.

json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Erro de validacao",
    "details": {
      "descricao": ["Este campo é obrigatorio."]
    }
  }
}

Descrição excede limite (400)

json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Erro de validacao",
    "details": {
      "descricao": ["Certifique-se de que este campo nao tenha mais de 200 caracteres."]
    }
  }
}

Não autenticado (401)

json
{
  "detail": "Token invalido"
}

Sem permissão (403)

Retornado quando o token não possui o escopo necessário.

json
{
  "detail": "Token nao tem permissao para este recurso"
}

Não encontrado (404)

Retornado quando a embalagem não existe ou pertence a outra empresa.

json
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Registro nao encontrado"
  }
}

Rate limit excedido (429)

json
{
  "detail": "Limite de requisicoes excedido. Tente novamente em 45 segundos."
}

---

Códigos de Status HTTP

---

Rate Limiting

Os limites de requisição são aplicados por token.

Ao exceder o limite, a API retorna 429 Too Many Requests. Implemente retry com backoff exponencial para lidar com esses casos.

---

Paginação

Endpoints de listagem retornam dados paginados.

Objeto paginacao na resposta

Navegação entre páginas (Python)

python
import requests

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

headers = {"Authorization": f"Bearer {TOKEN}"}

todas_embalagens = []
url = f"{BASE_URL}/embalagens/?por_pagina=100"

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

    if not dados["success"]:
        break

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

print(f"Total obtido: {len(todas_embalagens)} embalagens")

---

Valores de Referência

Situação da Embalagem