API de Vale Troca

Gerencie os vales troca do Bunto ERP. Este endpoint permite listar, consultar, criar, atualizar e excluir vales troca via API. Vales troca são créditos emitidos para clientes, geralmente originados de devoluções de venda.

Base URL

Produção:

https://api-backend.bunto.com.br/v1/vale-troca/

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: vale_troca com a ação correspondente (read, write ou delete).

Endpoints

Listar Vales Troca

GET /v1/vale-troca/

Escopo necessário: vale_troca: read

Retorna a lista paginada de vales troca da empresa. Por padrão, vales com status excluido são ocultados da listagem. Use ?status=excluido para visualizá-los.

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 código do vale
`status`	string	-	Filtrar por status: `aberto`, `utilizado`, `excluido`
`ordenar`	string	`criado_em`	Campo de ordenação: `criado_em`, `data_vale`, `valor`, `codigo`
`direcao`	string	`desc`	Direção da ordenação: `asc` ou `desc`

Nota: Quando o parâmetro status não é informado, a API automaticamente exclui vales com status excluido da listagem.

Exemplo com cURL

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

dados = resposta.json()

if dados["success"]:
    vales = dados["data"]["resultados"]
    paginacao = dados["data"]["paginacao"]
    print(f"Total de vales: {paginacao['total_registros']}")
    for vale in vales:
        print(f"  - Codigo: {vale['codigo']} | {vale['cliente_nome']} | R$ {vale['valor']} | Data: {vale['data_vale']} | Status: {vale['status']}")
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: "aberto",
  ordenar: "criado_em",
  direcao: "desc",
});

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

const dados = await resposta.json();

if (dados.success) {
  const vales = dados.data.resultados;
  const paginacao = dados.data.paginacao;
  console.log(`Total de vales: ${paginacao.total_registros}`);
  vales.forEach((vale) => {
    console.log(`  - Codigo: ${vale.codigo} | ${vale.cliente_nome} | R$ ${vale.valor} | Data: ${vale.data_vale} | Status: ${vale.status}`);
  });
} else {
  console.error(`Erro: ${resposta.status}`);
}

Resposta (200 OK)

json
{
  "success": true,
  "message": "5 registros encontrados",
  "data": {
    "resultados": [
      {
        "id": 12,
        "codigo":"VT-2026-0012",
        "data_vale": "2026-02-12",
        "valor": "350.00",
        "status": "aberto",
        "cliente_id": 42,
        "cliente_nome": "Maria Silva Ltda"
      },
      {
        "id": 11,
        "codigo":"VT-2026-0011",
        "data_vale": "2026-02-10",
        "valor": "120.00",
        "status": "aberto",
        "cliente_id": 18,
        "cliente_nome": "Comércio ABC ME"
      }
    ],
    "paginacao": {
      "pagina_atual": 1,
      "total_paginas": 1,
      "total_registros": 5,
      "por_pagina": 25,
      "proxima": null,
      "anterior": null
    }
  }
}

Campos da Listagem

Campo	Tipo	Descrição
`id`	integer	Identificador único do vale troca
`codigo`	string	Código único do vale troca (ex: "VT-2026-0012")
`data_vale`	string (date)	Data de emissão do vale (formato: YYYY-MM-DD)
`valor`	string (decimal)	Valor do vale troca (formato: "350.00")
`status`	string	Status do vale: `aberto`, `utilizado`, `excluido`
`cliente_id`	integer	ID do cliente titular do vale
`cliente_nome`	string / null	Nome do cliente

Obter Vale Troca

GET /v1/vale-troca/{id}/

Escopo necessário: vale_troca: read

Retorna os dados completos de um vale troca específico, incluindo observação e vínculos com vendas e devoluções de origem.

Exemplo com cURL

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

vale_id = 12
resposta = requests.get(f"{BASE_URL}/vale-troca/{vale_id}/", headers=headers)
dados = resposta.json()

if dados["success"]:
    vale = dados["data"]
    print(f"Vale Troca: {vale['codigo']} | Status: {vale['status']}")
    print(f"Cliente: {vale['cliente_nome']} (ID: {vale['cliente_id']})")
    print(f"Valor: R$ {vale['valor']} | Data: {vale['data_vale']}")
    if vale["venda_origem_id"]:
        print(f"Venda de origem: #{vale['venda_origem_id']}")
    if vale["devolucao_venda_origem_id"]:
        print(f"Devolucao de origem: #{vale['devolucao_venda_origem_id']}")
    if vale["observacao"]:
        print(f"Observacao: {vale['observacao']}")
else:
    print(f"Erro: {dados}")

Exemplo com JavaScript

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

const valeId = 12;

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

const dados = await resposta.json();

if (dados.success) {
  const vale = dados.data;
  console.log(`Vale Troca: ${vale.codigo} | Status: ${vale.status}`);
  console.log(`Cliente: ${vale.cliente_nome} (ID: ${vale.cliente_id})`);
  console.log(`Valor: R$ ${vale.valor} | Data: ${vale.data_vale}`);
  if (vale.venda_origem_id) {
    console.log(`Venda de origem: #${vale.venda_origem_id}`);
  }
  if (vale.devolucao_venda_origem_id) {
    console.log(`Devolucao de origem: #${vale.devolucao_venda_origem_id}`);
  }
} else {
  console.error(`Erro: ${JSON.stringify(dados)}`);
}

Resposta (200 OK)

json
{
  "success": true,
  "message": "Registro encontrado",
  "data": {
    "id": 12,
    "codigo":"VT-2026-0012",
    "data_vale": "2026-02-12",
    "valor": "350.00",
    "status": "aberto",
    "cliente_id": 42,
    "cliente_nome": "Maria Silva Ltda",
    "observacao":"Vale gerado a partir da devolucao DEV-2026-025.",
    "venda_origem_id": 1023,
    "devolucao_venda_origem_id": 25,
    "criado_em": "2026-02-12T10:30:00-03:00",
    "atualizado_em": "2026-02-12T10:30:00-03:00"
  }
}

Campos do Detalhe (adicionais à listagem)

Campo	Tipo	Descrição
`observacao`	string / null	Observação sobre o vale troca
`venda_origem_id`	integer / null	ID da venda que originou o vale troca
`devolucao_venda_origem_id`	integer / null	ID da devolução de venda que originou o vale troca
`criado_em`	datetime	Data e hora de criação
`atualizado_em`	datetime	Data e hora da última atualização

Criar Vale Troca

POST /v1/vale-troca/

Escopo necessário: vale_troca: write

Cria um novo vale troca na empresa do token autenticado.

Campos do Request Body

Campo	Tipo	Obrigatório	Descrição
`data_vale`	string (date)	Sim	Data de emissão do vale (formato: YYYY-MM-DD)
`valor`	decimal	Sim	Valor do vale troca (ex: "350.00", máximo 10 dígitos, 2 casas decimais)
`cliente_id`	integer	Sim	ID do cliente titular do vale
`observacao`	string	Não	Observação sobre o vale troca

Exemplo com cURL

bash
curl -X POST https://api-backend.bunto.com.br/v1/vale-troca/ \
  -H 'Authorization: Bearer bnt_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9t0U1v2W3x4' \
  -H 'Content-Type: application/json' \
  -d '{
    "data_vale": "2026-02-12",
    "valor": "250.00",
    "cliente_id": 42,
    "observacao":"Vale troca emitido como cortesia ao cliente."
  }'

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_vale = {
    "data_vale": "2026-02-12",
    "valor": "250.00",
    "cliente_id": 42,
    "observacao":"Vale troca emitido como cortesia ao cliente.",
}

resposta = requests.post(f"{BASE_URL}/vale-troca/", headers=headers, json=novo_vale)
dados = resposta.json()

if dados["success"]:
    vale = dados["data"]
    print(f"Vale troca criado com sucesso! ID: {vale['id']}")
    print(f"Codigo: {vale['codigo']} | Valor: R$ {vale['valor']}")
    print(f"Cliente: {vale['cliente_nome']}")
else:
    print(f"Erro ao criar vale troca: {dados}")

Exemplo com JavaScript

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

const novoVale = {
  data_vale: "2026-02-12",
  valor: "250.00",
  cliente_id: 42,
  observacao: "Vale troca emitido como cortesia ao cliente.",
};

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

const dados = await resposta.json();

if (dados.success) {
  console.log(`Vale troca criado com sucesso! ID: ${dados.data.id}`);
  console.log(`Codigo: ${dados.data.codigo} | Valor: R$ ${dados.data.valor}`);
} else {
  console.error(`Erro ao criar vale troca:`, dados);
}

Resposta (201 Created)

json
{
  "success": true,
  "message": "Vale troca criado com sucesso",
  "data": {
    "id": 13,
    "codigo":"VT-2026-0013",
    "data_vale": "2026-02-12",
    "valor": "250.00",
    "status": "aberto",
    "cliente_id": 42,
    "cliente_nome": "Maria Silva Ltda",
    "observacao":"Vale troca emitido como cortesia ao cliente.",
    "venda_origem_id": null,
    "devolucao_venda_origem_id": null,
    "criado_em": "2026-02-12T16:00:00-03:00",
    "atualizado_em": "2026-02-12T16:00:00-03:00"
  }
}

Atualizar Vale Troca

PUT /v1/vale-troca/{id}/

PATCH /v1/vale-troca/{id}/

Escopo necessário: vale_troca: write

Atualiza um vale troca 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/vale-troca/13/ \
  -H 'Authorization: Bearer bnt_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9t0U1v2W3x4' \
  -H 'Content-Type: application/json' \
  -d '{
    "valor": "300.00",
    "observacao":"Valor atualizado conforme negociacao com o cliente."
  }'

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

vale_id = 13

atualizacao = {
    "valor": "300.00",
    "observacao":"Valor atualizado conforme negociacao com o cliente.",
}

resposta = requests.patch(
    f"{BASE_URL}/vale-troca/{vale_id}/",
    headers=headers,
    json=atualizacao,
)

dados = resposta.json()

if dados["success"]:
    vale = dados["data"]
    print(f"Vale troca atualizado! Valor: R$ {vale['valor']}")
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 valeId = 13;

const atualizacao = {
  valor: "300.00",
  observacao: "Valor atualizado conforme negociacao com o cliente.",
};

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

const dados = await resposta.json();

if (dados.success) {
  console.log(`Vale troca atualizado! Valor: R$ ${dados.data.valor}`);
} else {
  console.error(`Erro ao atualizar:`, dados);
}

Resposta (200 OK)

json
{
  "success": true,
  "message": "Vale troca atualizado com sucesso",
  "data": {
    "id": 13,
    "codigo":"VT-2026-0013",
    "data_vale": "2026-02-12",
    "valor": "300.00",
    "status": "aberto",
    "cliente_id": 42,
    "cliente_nome": "Maria Silva Ltda",
    "observacao":"Valor atualizado conforme negociacao com o cliente.",
    "venda_origem_id": null,
    "devolucao_venda_origem_id": null,
    "criado_em": "2026-02-12T16:00:00-03:00",
    "atualizado_em": "2026-02-12T17:15:00-03:00"
  }
}

Excluir Vale Troca (Soft Delete)

DELETE /v1/vale-troca/{id}/

Escopo necessário: vale_troca: delete

Exclui o vale troca (soft delete). O registro não é removido permanentemente do banco de dados -- o status é alterado para excluido, preservando o histórico.

Exemplo com cURL

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

vale_id = 13
resposta = requests.delete(f"{BASE_URL}/vale-troca/{vale_id}/", headers=headers)
dados = resposta.json()

if dados["success"]:
    print("Vale troca 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 valeId = 13;

const resposta = await fetch(`${BASE_URL}/vale-troca/${valeId}/`, {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${TOKEN}`,
  },
});

const dados = await resposta.json();

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

Resposta (200 OK)

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

Importante: Vales troca excluídos não são removidos do banco de dados. Por padrão, vales excluídos são ocultados da listagem. Para visualizá-los, filtre por status=excluido. Os vínculos com vendas e devoluções de origem são preservados para fins de auditoria.

Erros Comuns

Código	Erro	Causa	Solução
400	`VALIDATION_ERROR`	Dados enviados são inválidos (campo obrigatório ausente, formato de data incorreto, valor 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 `vale_troca` ou a ação necessária (`read`, `write`, `delete`)	Verifique os escopos do token no painel
404	`Nao encontrado`	Vale troca não existe ou pertence a outra empresa	Confirme o ID e se o vale 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": {
      "data_vale": ["Este campo é obrigatorio."],
      "valor": ["Este campo é obrigatorio."],
      "cliente_id": ["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.

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 vales troca
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 para reduzir o volume de dados retornados

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_vales = []
url = f"{BASE_URL}/vale-troca/?por_pagina=100&status=aberto"

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

    if not dados["success"]:
        break

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

print(f"Total obtido: {len(todos_os_vales)} vales troca abertos")

Base URL

Autenticação

Endpoints

Listar Vales Troca

Query Parameters

Exemplo com cURL

Exemplo com Python

Exemplo com JavaScript

Resposta (200 OK)

Campos da Listagem

Obter Vale Troca

Exemplo com cURL

Exemplo com Python

Exemplo com JavaScript

Resposta (200 OK)

Campos do Detalhe (adicionais à listagem)

Criar Vale Troca

Campos do Request Body

Exemplo com cURL

Exemplo com Python

Exemplo com JavaScript

Resposta (201 Created)

Atualizar Vale Troca

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

Exemplo com Python

Exemplo com JavaScript

Resposta (200 OK)

Excluir Vale Troca (Soft Delete)

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)

Objeto `paginacao` na resposta