API de Agenda

Gerencie eventos da agenda no Bunto ERP. Este endpoint permite listar, consultar, criar, atualizar e excluir eventos da sua empresa via API.

Base URL

Produção:

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

---

Autenticação

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

Authorization: Bearer bnt_seu_token_aqui

---

Endpoints

Listar Eventos

GET /v1/agenda/

Escopo necessário: agenda: read

Retorna a lista paginada de eventos da empresa.

Query Parameters

Exemplo com cURL

bash
curl 'https://api-backend.bunto.com.br/v1/agenda/?pagina=1&por_pagina=10&data_inicio=2026-02-01&data_fim=2026-02-28&prioridade=urgente&ordenar=data_inicio&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 eventos do mês com filtros
resposta = requests.get(
    f"{BASE_URL}/agenda/",
    headers=headers,
    params={
        "pagina": 1,
        "por_pagina": 25,
        "data_inicio": "2026-02-01",
        "data_fim": "2026-02-28",
        "ordenar": "data_inicio",
        "direcao": "asc",
    },
)

dados = resposta.json()

if dados["success"]:
    eventos = dados["data"]["resultados"]
    paginacao = dados["data"]["paginacao"]
    print(f"Total de eventos: {paginacao['total_registros']}")
    for ev in eventos:
        print(f"  - {ev['data_inicio']} | {ev['titulo']} ({ev['prioridade']})")
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",
  data_inicio: "2026-02-01",
  data_fim: "2026-02-28",
  ordenar: "data_inicio",
  direcao: "asc",
});

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

const dados = await resposta.json();

if (dados.success) {
  const eventos = dados.data.resultados;
  const paginacao = dados.data.paginacao;
  console.log(`Total de eventos: ${paginacao.total_registros}`);
  eventos.forEach((ev) => {
    console.log(`  - ${ev.data_inicio} | ${ev.titulo} (${ev.prioridade})`);
  });
} else {
  console.error(`Erro: ${resposta.status}`);
}

Resposta (200 OK)

json
{
  "success": true,
  "message": "15 registros encontrados",
  "data": {
    "resultados": [
      {
        "id": 1,
        "titulo": "Reunião com fornecedor Têxtil Norte",
        "data_inicio": "2026-02-14",
        "data_fim": null,
        "dia_inteiro": false,
        "prioridade": "importante",
        "cor": "#3b82f6",
        "data_criacao": "2026-02-10T09:00:00-03:00"
      },
      {
        "id": 2,
        "titulo": "Inventário mensal do depósito central",
        "data_inicio": "2026-02-28",
        "data_fim": "2026-02-28",
        "dia_inteiro": true,
        "prioridade": "normal",
        "cor": "#10b981",
        "data_criacao": "2026-02-05T14:30:00-03:00"
      }
    ],
    "paginacao": {
      "pagina_atual": 1,
      "total_paginas": 1,
      "total_registros": 15,
      "por_pagina": 25,
      "proxima": null,
      "anterior": null
    }
  }
}

Campos da Listagem

---

Obter Evento

GET /v1/agenda/{id}/

Escopo necessário: agenda: read

Retorna os dados completos de um evento específico, incluindo descrição, horários e dados de vinculação com outros módulos.

Exemplo com cURL

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

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

if dados["success"]:
    ev = dados["data"]
    print(f"Evento: {ev['titulo']}")
    print(f"Data: {ev['data_inicio']}")
    if ev["hora_inicio"]:
        print(f"Horário: {ev['hora_inicio']} - {ev['hora_fim']}")
    print(f"Prioridade: {ev['prioridade']}")
else:
    print(f"Erro: {dados}")

Exemplo com JavaScript

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

const eventoId = 1;

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

const dados = await resposta.json();

if (dados.success) {
  const ev = dados.data;
  console.log(`Evento: ${ev.titulo}`);
  console.log(`Data: ${ev.data_inicio}`);
  if (ev.hora_inicio) {
    console.log(`Horário: ${ev.hora_inicio} - ${ev.hora_fim}`);
  }
  console.log(`Prioridade: ${ev.prioridade}`);
} else {
  console.error(`Erro: ${JSON.stringify(dados)}`);
}

Resposta (200 OK)

json
{
  "success": true,
  "message": "Registro encontrado",
  "data": {
    "id": 1,
    "titulo": "Reunião com fornecedor Têxtil Norte",
    "data_inicio": "2026-02-14",
    "data_fim": null,
    "dia_inteiro": false,
    "prioridade": "importante",
    "cor": "#3b82f6",
    "data_criacao": "2026-02-10T09:00:00-03:00",
    "descricao": "Reunião para negociar preços da coleção outono/inverno 2026. Levar amostras e tabela de preços atualizada.",
    "hora_inicio": "14:00:00",
    "hora_fim": "15:30:00",
    "origem_modulo": "compras",
    "origem_tipo": "pedido_compra",
    "origem_id": 87,
    "link_origem": "/admin/compras/pedidos/87",
    "criado_por_id": 12
  }
}

Campos do Detalhe (adicionais à listagem)

---

Criar Evento

POST /v1/agenda/

Escopo necessário: agenda: write

Cria um novo evento na agenda da empresa do token autenticado.

Campos do Request Body

Exemplo com cURL

bash
curl -X POST https://api-backend.bunto.com.br/v1/agenda/ \
  -H 'Authorization: Bearer bnt_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9t0U1v2W3x4' \
  -H 'Content-Type: application/json' \
  -d '{
    "titulo": "Visita técnica ao cliente Loja Fashion",
    "data_inicio": "2026-02-20",
    "descricao": "Visita para instalação do leitor de código de barras e treinamento do PDV.",
    "hora_inicio": "09:00",
    "hora_fim": "12:00",
    "dia_inteiro": false,
    "prioridade": "importante",
    "cor": "#f59e0b"
  }'

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_evento = {
    "titulo": "Visita técnica ao cliente Loja Fashion",
    "data_inicio": "2026-02-20",
    "descricao": (
        "Visita para instalação do leitor de código de barras "
        "e treinamento do PDV."
    ),
    "hora_inicio": "09:00",
    "hora_fim": "12:00",
    "dia_inteiro": False,
    "prioridade": "importante",
    "cor": "#f59e0b",
}

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

if dados["success"]:
    ev = dados["data"]
    print(f"Evento criado com sucesso! ID: {ev['id']}")
    print(f"Título: {ev['titulo']}")
    print(f"Data: {ev['data_inicio']}")
else:
    print(f"Erro ao criar evento: {dados}")

Exemplo com JavaScript

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

const novoEvento = {
  titulo: "Visita técnica ao cliente Loja Fashion",
  data_inicio: "2026-02-20",
  descricao:
    "Visita para instalação do leitor de código de barras e treinamento do PDV.",
  hora_inicio: "09:00",
  hora_fim: "12:00",
  dia_inteiro: false,
  prioridade: "importante",
  cor: "#f59e0b",
};

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

const dados = await resposta.json();

if (dados.success) {
  console.log(`Evento criado com sucesso! ID: ${dados.data.id}`);
  console.log(`Título: ${dados.data.titulo}`);
  console.log(`Data: ${dados.data.data_inicio}`);
} else {
  console.error(`Erro ao criar evento:`, dados);
}

Resposta (201 Created)

json
{
  "success": true,
  "message": "Evento criado com sucesso",
  "data": {
    "id": 16,
    "titulo": "Visita técnica ao cliente Loja Fashion",
    "data_inicio": "2026-02-20",
    "data_fim": null,
    "dia_inteiro": false,
    "prioridade": "importante",
    "cor": "#f59e0b",
    "data_criacao": "2026-02-12T16:30:00-03:00",
    "descricao": "Visita para instalação do leitor de código de barras e treinamento do PDV.",
    "hora_inicio": "09:00:00",
    "hora_fim": "12:00:00",
    "origem_modulo": null,
    "origem_tipo": null,
    "origem_id": null,
    "link_origem": null,
    "criado_por_id": null
  }
}

---

Atualizar Evento

PUT /v1/agenda/{id}/

PATCH /v1/agenda/{id}/

Escopo necessário: agenda: write

Atualiza um evento 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/agenda/16/ \
  -H 'Authorization: Bearer bnt_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9t0U1v2W3x4' \
  -H 'Content-Type: application/json' \
  -d '{
    "hora_inicio": "10:00",
    "hora_fim": "13:00",
    "descricao": "Visita remarcada para as 10h. Instalação do leitor de código de barras e treinamento do PDV."
  }'

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

evento_id = 16

# Atualização parcial (PATCH) - apenas os campos que mudaram
atualizacao = {
    "hora_inicio": "10:00",
    "hora_fim": "13:00",
    "descricao": "Visita remarcada para as 10h. Instalação do leitor de código de barras e treinamento do PDV.",
}

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

dados = resposta.json()

if dados["success"]:
    ev = dados["data"]
    print(f"Evento atualizado! Novo horário: {ev['hora_inicio']}")
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 eventoId = 16;

const atualizacao = {
  hora_inicio: "10:00",
  hora_fim: "13:00",
  descricao:
    "Visita remarcada para as 10h. Instalação do leitor de código de barras e treinamento do PDV.",
};

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

const dados = await resposta.json();

if (dados.success) {
  console.log(`Evento atualizado! Novo horário: ${dados.data.hora_inicio}`);
} else {
  console.error(`Erro ao atualizar:`, dados);
}

Resposta (200 OK)

json
{
  "success": true,
  "message": "Evento atualizado com sucesso",
  "data": {
    "id": 16,
    "titulo": "Visita técnica ao cliente Loja Fashion",
    "data_inicio": "2026-02-20",
    "data_fim": null,
    "dia_inteiro": false,
    "prioridade": "importante",
    "cor": "#f59e0b",
    "data_criacao": "2026-02-12T16:30:00-03:00",
    "descricao": "Visita remarcada para as 10h. Instalação do leitor de código de barras e treinamento do PDV.",
    "hora_inicio": "10:00:00",
    "hora_fim": "13:00:00",
    "origem_modulo": null,
    "origem_tipo": null,
    "origem_id": null,
    "link_origem": null,
    "criado_por_id": null
  }
}

---

Excluir Evento (Permanente)

DELETE /v1/agenda/{id}/

Escopo necessário: agenda: delete

Exclui permanentemente o evento da agenda. Esta operação não pode ser desfeita -- o registro é removido definitivamente do banco de dados.

Exemplo com cURL

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

evento_id = 16
resposta = requests.delete(f"{BASE_URL}/agenda/{evento_id}/", headers=headers)
dados = resposta.json()

if dados["success"]:
    print(f"Evento 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 eventoId = 16;

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

const dados = await resposta.json();

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

Resposta (200 OK)

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

---

Erros Comuns

Exemplo de Resposta de Erro (400)

json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Erro de validação",
    "details": {
      "titulo": ["Este campo é obrigatório."],
      "data_inicio": ["Data com formato errado. Use o formato YYYY-MM-DD."]
    }
  }
}

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 eventos
• Implemente retry com backoff exponencial ao receber 429
• Use os filtros data_inicio e data_fim para buscar apenas o período necessário
• Para atualizações em lote, use PATCH apenas com os campos alterados para economizar requisições de escrita

---

Paginação

Todos os endpoints de listagem retornam dados paginados.

Parâmetros

Objeto paginacao na resposta

---

Valores de Referência

Prioridades

Cores Sugeridas