API de Devoluções

Gerencie as devoluções de venda do Bunto ERP. Este endpoint permite listar, consultar, criar, atualizar e cancelar devoluções via API, com suporte a devoluções parciais e diferentes meios de restituição.

Base URL

Produção:

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

---

Autenticação

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

Authorization: Bearer bnt_seu_token_aqui

---

Endpoints

Listar Devoluções

GET /v1/devolucoes/

Escopo necessário: devolucoes: read

Retorna a lista paginada de devoluções de venda da empresa.

Query Parameters

Exemplo com cURL

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

dados = resposta.json()

if dados["success"]:
    devolucoes = dados["data"]["resultados"]
    paginacao = dados["data"]["paginacao"]
    print(f"Total de devolucoes: {paginacao['total_registros']}")
    for dev in devolucoes:
        parcial = "Parcial" if dev["devolucao_parcial"] else "Total"
        print(f"  - #{dev['numero_devolucao']} | {dev['cliente_nome']} | R$ {dev['total_devolver']} | {parcial} | Meio: {dev['meio_devolucao']}")
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_criacao",
  direcao: "desc",
});

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

const dados = await resposta.json();

if (dados.success) {
  const devolucoes = dados.data.resultados;
  const paginacao = dados.data.paginacao;
  console.log(`Total de devolucoes: ${paginacao.total_registros}`);
  devolucoes.forEach((dev) => {
    const parcial = dev.devolucao_parcial ? "Parcial" : "Total";
    console.log(`  - #${dev.numero_devolucao} | ${dev.cliente_nome} | R$ ${dev.total_devolver} | ${parcial} | Meio: ${dev.meio_devolucao}`);
  });
} else {
  console.error(`Erro: ${resposta.status}`);
}

Resposta (200 OK)

json
{
  "success": true,
  "message": "3 registros encontrados",
  "data": {
    "resultados": [
      {
        "id": 25,
        "numero_devolucao": "DEV-2026-025",
        "venda_origem_id": 1023,
        "numero_pedido_origem": "PED-2026-1023",
        "status": "em_aberto",
        "cliente_id": 42,
        "cliente_nome": "Maria Silva Ltda",
        "meio_devolucao": "vale_troca",
        "devolucao_parcial": true,
        "total_devolver": "350.00",
        "data_criacao": "2026-02-12T10:00:00-03:00"
      },
      {
        "id": 24,
        "numero_devolucao": "DEV-2026-024",
        "venda_origem_id": 1018,
        "numero_pedido_origem": "PED-2026-1018",
        "status": "em_aberto",
        "cliente_id": 18,
        "cliente_nome": "Comércio ABC ME",
        "meio_devolucao": "dinheiro",
        "devolucao_parcial": false,
        "total_devolver": "1200.00",
        "data_criacao": "2026-02-11T15:30:00-03:00"
      }
    ],
    "paginacao": {
      "pagina_atual": 1,
      "total_paginas": 1,
      "total_registros": 3,
      "por_pagina": 25,
      "proxima": null,
      "anterior": null
    }
  }
}

Campos da Listagem

---

Obter Devolução

GET /v1/devolucoes/{id}/

Escopo necessário: devolucoes: read

Retorna os dados completos de uma devolução específica, incluindo itens devolvidos, chave da NF de origem, depósito e observações internas.

Exemplo com cURL

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

devolucao_id = 25
resposta = requests.get(f"{BASE_URL}/devolucoes/{devolucao_id}/", headers=headers)
dados = resposta.json()

if dados["success"]:
    dev = dados["data"]
    parcial = "Parcial" if dev["devolucao_parcial"] else "Total"
    print(f"Devolucao #{dev['numero_devolucao']} | Status: {dev['status']} | {parcial}")
    print(f"Cliente: {dev['cliente_nome']} | Meio: {dev['meio_devolucao']}")
    print(f"Venda de origem: #{dev['venda_origem_id']} ({dev['numero_pedido_origem']})")
    print(f"Total a devolver: R$ {dev['total_devolver']}")
    print(f"Itens ({len(dev['itens'])}):")
    for item in dev["itens"]:
        print(f"  - {item['produto_nome']} ({item['produto_codigo']}) | Qtd original: {item['quantidade_original']} | Qtd devolver: {item['quantidade_devolver']} | 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 devolucaoId = 25;

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

const dados = await resposta.json();

if (dados.success) {
  const dev = dados.data;
  const parcial = dev.devolucao_parcial ? "Parcial" : "Total";
  console.log(`Devolucao #${dev.numero_devolucao} | Status: ${dev.status} | ${parcial}`);
  console.log(`Cliente: ${dev.cliente_nome} | Meio: ${dev.meio_devolucao}`);
  console.log(`Total a devolver: R$ ${dev.total_devolver}`);
  console.log(`Itens (${dev.itens.length}):`);
  dev.itens.forEach((item) => {
    console.log(`  - ${item.produto_nome} | Qtd devolver: ${item.quantidade_devolver} | R$ ${item.preco_total}`);
  });
} else {
  console.error(`Erro: ${JSON.stringify(dados)}`);
}

Resposta (200 OK)

json
{
  "success": true,
  "message": "Registro encontrado",
  "data": {
    "id": 25,
    "numero_devolucao": "DEV-2026-025",
    "venda_origem_id": 1023,
    "numero_pedido_origem": "PED-2026-1023",
    "status": "em_aberto",
    "cliente_id": 42,
    "cliente_nome": "Maria Silva Ltda",
    "meio_devolucao": "vale_troca",
    "devolucao_parcial": true,
    "total_devolver": "350.00",
    "data_criacao": "2026-02-12T10:00:00-03:00",
    "chave_nf_origem": "35260212345678000190550010000010231000102301",
    "deposito_id": 1,
    "observacoes_internas": "Cliente solicitou troca por defeito no produto.",
    "itens": [
      {
        "id": 51,
        "produto_id": 15,
        "produto_codigo": "NB-DELL-15",
        "produto_nome": "Notebook Dell Inspiron 15",
        "quantidade_original": "2",
        "quantidade_devolver": "1",
        "preco_unitario": "3500.00",
        "preco_total": "350.00",
        "unidade": "UN"
      }
    ],
    "criado_em": "2026-02-12T10:00:00-03:00",
    "atualizado_em": "2026-02-12T10:00:00-03:00"
  }
}

Campos do Detalhe (adicionais à listagem)

Campos do Item

---

Criar Devolução

POST /v1/devolucoes/

Escopo necessário: devolucoes: write

Cria uma nova devolução de venda na empresa do token autenticado.

Campos do Request Body

Exemplo com cURL

bash
curl -X POST https://api-backend.bunto.com.br/v1/devolucoes/ \
  -H 'Authorization: Bearer bnt_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9t0U1v2W3x4' \
  -H 'Content-Type: application/json' \
  -d '{
    "venda_origem_id": 1023,
    "numero_pedido_origem": "PED-2026-1023",
    "cliente_id": 42,
    "cliente_nome": "Maria Silva Ltda",
    "meio_devolucao": "vale_troca",
    "devolucao_parcial": true,
    "total_devolver": "350.00",
    "deposito_id": 1,
    "observacoes_internas": "Cliente solicitou troca por defeito no produto."
  }'

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_devolucao = {
    "venda_origem_id": 1023,
    "numero_pedido_origem": "PED-2026-1023",
    "cliente_id": 42,
    "cliente_nome": "Maria Silva Ltda",
    "meio_devolucao": "vale_troca",
    "devolucao_parcial": True,
    "total_devolver": "350.00",
    "deposito_id": 1,
    "observacoes_internas": "Cliente solicitou troca por defeito no produto.",
}

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

if dados["success"]:
    dev = dados["data"]
    print(f"Devolucao criada com sucesso! ID: {dev['id']}")
    print(f"Numero: {dev['numero_devolucao']} | Status: {dev['status']}")
    print(f"Total a devolver: R$ {dev['total_devolver']}")
else:
    print(f"Erro ao criar devolucao: {dados}")

Exemplo com JavaScript

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

const novaDevolucao = {
  venda_origem_id: 1023,
  numero_pedido_origem: "PED-2026-1023",
  cliente_id: 42,
  cliente_nome: "Maria Silva Ltda",
  meio_devolucao: "vale_troca",
  devolucao_parcial: true,
  total_devolver: "350.00",
  deposito_id: 1,
  observacoes_internas: "Cliente solicitou troca por defeito no produto.",
};

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

const dados = await resposta.json();

if (dados.success) {
  console.log(`Devolucao criada com sucesso! ID: ${dados.data.id}`);
  console.log(`Numero: ${dados.data.numero_devolucao} | Status: ${dados.data.status}`);
} else {
  console.error(`Erro ao criar devolucao:`, dados);
}

Resposta (201 Created)

json
{
  "success": true,
  "message": "Devolucao criada com sucesso",
  "data": {
    "id": 26,
    "numero_devolucao": "DEV-2026-026",
    "venda_origem_id": 1023,
    "numero_pedido_origem": "PED-2026-1023",
    "status": "em_aberto",
    "cliente_id": 42,
    "cliente_nome": "Maria Silva Ltda",
    "meio_devolucao": "vale_troca",
    "devolucao_parcial": true,
    "total_devolver": "350.00",
    "data_criacao": "2026-02-12T16:00:00-03:00",
    "chave_nf_origem": null,
    "deposito_id": 1,
    "observacoes_internas": "Cliente solicitou troca por defeito no produto.",
    "itens": [],
    "criado_em": "2026-02-12T16:00:00-03:00",
    "atualizado_em": "2026-02-12T16:00:00-03:00"
  }
}

---

Atualizar Devolução

PUT /v1/devolucoes/{id}/

PATCH /v1/devolucoes/{id}/

Escopo necessário: devolucoes: write

Atualiza uma devolução 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/devolucoes/26/ \
  -H 'Authorization: Bearer bnt_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9t0U1v2W3x4' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "em_andamento",
    "observacoes_internas": "Produto recebido, em análise de qualidade."
  }'

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

devolucao_id = 26

atualizacao = {
    "status": "em_andamento",
    "observacoes_internas": "Produto recebido, em análise de qualidade.",
}

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

dados = resposta.json()

if dados["success"]:
    dev = dados["data"]
    print(f"Devolucao atualizada! Status: {dev['status']}")
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 devolucaoId = 26;

const atualizacao = {
  status: "em_andamento",
  observacoes_internas: "Produto recebido, em análise de qualidade.",
};

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

const dados = await resposta.json();

if (dados.success) {
  console.log(`Devolucao atualizada! Status: ${dados.data.status}`);
} else {
  console.error(`Erro ao atualizar:`, dados);
}

Resposta (200 OK)

json
{
  "success": true,
  "message": "Devolucao atualizada com sucesso",
  "data": {
    "id": 26,
    "numero_devolucao": "DEV-2026-026",
    "venda_origem_id": 1023,
    "numero_pedido_origem": "PED-2026-1023",
    "status": "em_andamento",
    "cliente_id": 42,
    "cliente_nome": "Maria Silva Ltda",
    "meio_devolucao": "vale_troca",
    "devolucao_parcial": true,
    "total_devolver": "350.00",
    "data_criacao": "2026-02-12T16:00:00-03:00",
    "chave_nf_origem": null,
    "deposito_id": 1,
    "observacoes_internas": "Produto recebido, em análise de qualidade.",
    "itens": [],
    "criado_em": "2026-02-12T16:00:00-03:00",
    "atualizado_em": "2026-02-12T17:45:00-03:00"
  }
}

---

Cancelar Devolução (Soft Delete)

DELETE /v1/devolucoes/{id}/

Escopo necessário: devolucoes: delete

Cancela a devolução (soft delete). O registro não é removido permanentemente do banco de dados -- o status é alterado para cancelada, preservando o histórico de devoluções.

Exemplo com cURL

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

devolucao_id = 26
resposta = requests.delete(f"{BASE_URL}/devolucoes/{devolucao_id}/", headers=headers)
dados = resposta.json()

if dados["success"]:
    print("Devolucao 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 devolucaoId = 26;

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

const dados = await resposta.json();

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

Resposta (200 OK)

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

---

Meios de Devolução

---

Erros Comuns

Exemplo de Resposta de Erro (400)

json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Erro de validacao",
    "details": {
      "meio_devolucao": ["\"pix\" nao é um escolha valido. Escolha entre: sem_pagamento, dinheiro, vale_troca, contas_pagar."],
      "status": ["\"devolvido\" nao é um escolha valido. Escolha entre: em_aberto, em_andamento, finalizada, 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.

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 devoluções
• 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 status e período (data_inicio/data_fim) 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_devolucoes = []
url = f"{BASE_URL}/devolucoes/?por_pagina=100&status=em_aberto"

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

    if not dados["success"]:
        break

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

print(f"Total obtido: {len(todas_as_devolucoes)} devolucoes em aberto")