API de Ocorrências

Gerencie ocorrências e eventos do sistema no Bunto ERP. Este endpoint permite listar, consultar, criar, atualizar e excluir ocorrências da sua empresa via API.

Base URL

Produção:

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

---

Autenticação

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

Authorization: Bearer bnt_seu_token_aqui

---

Endpoints

Listar Ocorrências

GET /v1/ocorrencias/

Escopo necessário: ocorrencias: read

Retorna a lista paginada de ocorrências ativas da empresa.

Query Parameters

Exemplo com cURL

bash
curl 'https://api-backend.bunto.com.br/v1/ocorrencias/?pagina=1&por_pagina=10&modulo=vendas&prioridade=alta&ordenar=data_registro&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 ocorrências com filtros
resposta = requests.get(
    f"{BASE_URL}/ocorrencias/",
    headers=headers,
    params={
        "pagina": 1,
        "por_pagina": 25,
        "modulo": "vendas",
        "prioridade": "alta",
        "ordenar": "data_registro",
        "direcao": "desc",
    },
)

dados = resposta.json()

if dados["success"]:
    ocorrencias = dados["data"]["resultados"]
    paginacao = dados["data"]["paginacao"]
    print(f"Total de ocorrências: {paginacao['total_registros']}")
    for oc in ocorrencias:
        print(f"  - [{oc['tipo']}] {oc['titulo']} ({oc['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",
  modulo: "vendas",
  prioridade: "alta",
  ordenar: "data_registro",
  direcao: "desc",
});

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

const dados = await resposta.json();

if (dados.success) {
  const ocorrencias = dados.data.resultados;
  const paginacao = dados.data.paginacao;
  console.log(`Total de ocorrências: ${paginacao.total_registros}`);
  ocorrencias.forEach((oc) => {
    console.log(`  - [${oc.tipo}] ${oc.titulo} (${oc.status})`);
  });
} else {
  console.error(`Erro: ${resposta.status}`);
}

Resposta (200 OK)

json
{
  "success": true,
  "message": "38 registros encontrados",
  "data": {
    "resultados": [
      {
        "id": 1,
        "modulo": "vendas",
        "titulo": "Pedido #1042 com divergência no valor total",
        "tipo": "warning",
        "status": "pendente",
        "prioridade": "alta",
        "data_registro": "2026-02-12T14:30:00-03:00"
      },
      {
        "id": 2,
        "modulo": "estoque",
        "titulo": "Estoque negativo detectado no produto CAM-001",
        "tipo": "error",
        "status": "em_andamento",
        "prioridade": "critica",
        "data_registro": "2026-02-11T09:15:00-03:00"
      }
    ],
    "paginacao": {
      "pagina_atual": 1,
      "total_paginas": 2,
      "total_registros": 38,
      "por_pagina": 25,
      "proxima": "https://api-backend.bunto.com.br/v1/ocorrencias/?pagina=2",
      "anterior": null
    }
  }
}

Campos da Listagem

---

Obter Ocorrência

GET /v1/ocorrencias/{id}/

Escopo necessário: ocorrencias: read

Retorna os dados completos de uma ocorrência específica, incluindo corpo da ocorrência, observações e dados de vinculação.

Exemplo com cURL

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

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

if dados["success"]:
    oc = dados["data"]
    print(f"Ocorrência: {oc['titulo']}")
    print(f"Módulo: {oc['modulo']}")
    print(f"Status: {oc['status']}")
    print(f"Prioridade: {oc['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 ocorrenciaId = 1;

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

const dados = await resposta.json();

if (dados.success) {
  const oc = dados.data;
  console.log(`Ocorrência: ${oc.titulo}`);
  console.log(`Módulo: ${oc.modulo}`);
  console.log(`Status: ${oc.status}`);
  console.log(`Prioridade: ${oc.prioridade}`);
} else {
  console.error(`Erro: ${JSON.stringify(dados)}`);
}

Resposta (200 OK)

json
{
  "success": true,
  "message": "Registro encontrado",
  "data": {
    "id": 1,
    "modulo": "vendas",
    "titulo": "Pedido #1042 com divergência no valor total",
    "tipo": "warning",
    "status": "pendente",
    "prioridade": "alta",
    "data_registro": "2026-02-12T14:30:00-03:00",
    "categoria": "financeiro",
    "ocorrencia": "O pedido #1042 apresenta divergência de R$ 15,00 entre o valor dos itens e o valor total registrado. Verificar se houve desconto aplicado manualmente.",
    "observacao_pessoal": "Verificar com o vendedor responsável",
    "objeto_id": 1042,
    "objeto_tipo": "pedido",
    "proximo_contato": "2026-02-13T10:00:00-03:00",
    "data_resolucao": null,
    "ativo": true,
    "criado_em": "2026-02-12T14:30:00-03:00",
    "atualizado_em": "2026-02-12T14:30:00-03:00"
  }
}

Campos do Detalhe (adicionais à listagem)

---

Criar Ocorrência

POST /v1/ocorrencias/

Escopo necessário: ocorrencias: write

Cria uma nova ocorrência na empresa do token autenticado.

Campos do Request Body

Exemplo com cURL

bash
curl -X POST https://api-backend.bunto.com.br/v1/ocorrencias/ \
  -H 'Authorization: Bearer bnt_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9t0U1v2W3x4' \
  -H 'Content-Type: application/json' \
  -d '{
    "modulo": "vendas",
    "titulo": "Cliente solicitou cancelamento do pedido #1055",
    "tipo": "action",
    "ocorrencia": "O cliente José Silva entrou em contato solicitando o cancelamento do pedido #1055. Motivo: comprou por engano. Verificar possibilidade de estorno.",
    "status": "pendente",
    "prioridade": "alta",
    "categoria": "cancelamento",
    "objeto_id": 1055,
    "objeto_tipo": "pedido",
    "proximo_contato": "2026-02-13T09:00: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",
}

nova_ocorrencia = {
    "modulo": "vendas",
    "titulo": "Cliente solicitou cancelamento do pedido #1055",
    "tipo": "action",
    "ocorrencia": (
        "O cliente José Silva entrou em contato solicitando o cancelamento "
        "do pedido #1055. Motivo: comprou por engano. Verificar possibilidade de estorno."
    ),
    "status": "pendente",
    "prioridade": "alta",
    "categoria": "cancelamento",
    "objeto_id": 1055,
    "objeto_tipo": "pedido",
    "proximo_contato": "2026-02-13T09:00:00",
}

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

if dados["success"]:
    oc = dados["data"]
    print(f"Ocorrência criada com sucesso! ID: {oc['id']}")
    print(f"Título: {oc['titulo']}")
else:
    print(f"Erro ao criar ocorrência: {dados}")

Exemplo com JavaScript

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

const novaOcorrencia = {
  modulo: "vendas",
  titulo: "Cliente solicitou cancelamento do pedido #1055",
  tipo: "action",
  ocorrencia:
    "O cliente José Silva entrou em contato solicitando o cancelamento do pedido #1055. Motivo: comprou por engano. Verificar possibilidade de estorno.",
  status: "pendente",
  prioridade: "alta",
  categoria: "cancelamento",
  objeto_id: 1055,
  objeto_tipo: "pedido",
  proximo_contato: "2026-02-13T09:00:00",
};

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

const dados = await resposta.json();

if (dados.success) {
  console.log(`Ocorrência criada com sucesso! ID: ${dados.data.id}`);
  console.log(`Título: ${dados.data.titulo}`);
} else {
  console.error(`Erro ao criar ocorrência:`, dados);
}

Resposta (201 Created)

json
{
  "success": true,
  "message": "Ocorrência criada com sucesso",
  "data": {
    "id": 39,
    "modulo": "vendas",
    "titulo": "Cliente solicitou cancelamento do pedido #1055",
    "tipo": "action",
    "status": "pendente",
    "prioridade": "alta",
    "data_registro": "2026-02-12T16:00:00-03:00",
    "categoria": "cancelamento",
    "ocorrencia": "O cliente José Silva entrou em contato solicitando o cancelamento do pedido #1055. Motivo: comprou por engano. Verificar possibilidade de estorno.",
    "observacao_pessoal": null,
    "objeto_id": 1055,
    "objeto_tipo": "pedido",
    "proximo_contato": "2026-02-13T09:00:00-03:00",
    "data_resolucao": null,
    "ativo": true,
    "criado_em": "2026-02-12T16:00:00-03:00",
    "atualizado_em": "2026-02-12T16:00:00-03:00"
  }
}

---

Atualizar Ocorrência

PUT /v1/ocorrencias/{id}/

PATCH /v1/ocorrencias/{id}/

Escopo necessário: ocorrencias: write

Atualiza uma ocorrência 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/ocorrencias/39/ \
  -H 'Authorization: Bearer bnt_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9t0U1v2W3x4' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "em_andamento",
    "observacao_pessoal": "Estorno autorizado pelo supervisor. Aguardando processamento."
  }'

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

ocorrencia_id = 39

# Atualização parcial (PATCH) - apenas os campos que mudaram
atualizacao = {
    "status": "em_andamento",
    "observacao_pessoal": "Estorno autorizado pelo supervisor. Aguardando processamento.",
}

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

dados = resposta.json()

if dados["success"]:
    oc = dados["data"]
    print(f"Ocorrência atualizada! Status: {oc['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 ocorrenciaId = 39;

const atualizacao = {
  status: "em_andamento",
  observacao_pessoal:
    "Estorno autorizado pelo supervisor. Aguardando processamento.",
};

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

const dados = await resposta.json();

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

Resposta (200 OK)

json
{
  "success": true,
  "message": "Ocorrência atualizada com sucesso",
  "data": {
    "id": 39,
    "modulo": "vendas",
    "titulo": "Cliente solicitou cancelamento do pedido #1055",
    "tipo": "action",
    "status": "em_andamento",
    "prioridade": "alta",
    "data_registro": "2026-02-12T16:00:00-03:00",
    "categoria": "cancelamento",
    "ocorrencia": "O cliente José Silva entrou em contato solicitando o cancelamento do pedido #1055. Motivo: comprou por engano. Verificar possibilidade de estorno.",
    "observacao_pessoal": "Estorno autorizado pelo supervisor. Aguardando processamento.",
    "objeto_id": 1055,
    "objeto_tipo": "pedido",
    "proximo_contato": "2026-02-13T09:00:00-03:00",
    "data_resolucao": null,
    "ativo": true,
    "criado_em": "2026-02-12T16:00:00-03:00",
    "atualizado_em": "2026-02-12T16:45:00-03:00"
  }
}

---

Excluir Ocorrência (Soft Delete)

DELETE /v1/ocorrencias/{id}/

Escopo necessário: ocorrencias: delete

Desativa a ocorrência (soft delete). O registro não é removido permanentemente do banco de dados -- o campo ativo é definido como false, preservando o histórico.

Exemplo com cURL

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

ocorrencia_id = 39
resposta = requests.delete(f"{BASE_URL}/ocorrencias/{ocorrencia_id}/", headers=headers)
dados = resposta.json()

if dados["success"]:
    print(f"Ocorrência excluída 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 ocorrenciaId = 39;

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

const dados = await resposta.json();

if (dados.success) {
  console.log("Ocorrência excluída 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": {
      "modulo": ["Este campo é obrigatório."],
      "tipo": ["\"invalido\" não é um valor válido."]
    }
  }
}

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 ocorrências
• 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

---

Paginação

Todos os endpoints de listagem retornam dados paginados.

Parâmetros

Objeto paginacao na resposta

---

Valores de Referência

Módulos

Tipos de Ocorrência

Status da Ocorrência

Prioridades