API de Notas Fiscais

Consulte as notas fiscais eletrônicas (NFe e NFCe) emitidas no Bunto ERP. Este endpoint permite listar e consultar notas fiscais via API.

Endpoint somente leitura. Não é possível criar, atualizar ou excluir notas fiscais por esta API. A emissão de notas fiscais é realizada exclusivamente pelo painel do Bunto ERP.

Base URL

Produção:

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

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: nf com a ação read.

Endpoints

Listar Notas Fiscais

GET /v1/nf/

Escopo necessário: nf: read

Retorna a lista paginada de notas fiscais (NFe e NFCe) da empresa.

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 número da nota ou chave de acesso
`tipo`	string	-	Filtrar por tipo: `NFE` ou `NFCE`
`status`	string	-	Filtrar por status: `RASCUNHO`, `REGISTRADO`, `VALIDANDO`, `EMITINDO`, `AUTORIZADO`, `REJEITADO`, `CANCELADO`, `DENEGADO`
`finalidade`	string	-	Filtrar por finalidade: `Saida` ou `ENTRADA`
`cliente_id`	integer	-	Filtrar por ID do cliente vinculado
`data_inicio`	date	-	Data inicial do período (formato: `AAAA-MM-DD`)
`data_fim`	date	-	Data final do período (formato: `AAAA-MM-DD`)
`ordenar`	string	`criado_em`	Campo de ordenação: `numero`, `criado_em`, `status`
`direcao`	string	`desc`	Direção da ordenação: `asc` ou `desc`

Exemplo com cURL

bash
curl 'https://api-backend.bunto.com.br/v1/nf/?pagina=1&por_pagina=10&tipo=NFE&status=AUTORIZADO&ordenar=criado_em&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 notas fiscais autorizadas do tipo NFE
resposta = requests.get(
    f"{BASE_URL}/nf/",
    headers=headers,
    params={
        "pagina": 1,
        "por_pagina": 25,
        "tipo": "NFE",
        "status": "AUTORIZADO",
        "ordenar": "criado_em",
        "direcao": "desc",
    },
)

dados = resposta.json()

if dados["success"]:
    notas = dados["data"]["resultados"]
    paginacao = dados["data"]["paginacao"]
    print(f"Total de notas: {paginacao['total_registros']}")
    for nota in notas:
        print(f"  - NF {nota['numero']} | {nota['status']} | R$ {nota['valor_total']} | {nota['cliente_nome']}")
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",
  tipo: "NFE",
  status: "AUTORIZADO",
  ordenar: "criado_em",
  direcao: "desc",
});

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

const dados = await resposta.json();

if (dados.success) {
  const notas = dados.data.resultados;
  const paginacao = dados.data.paginacao;
  console.log(`Total de notas: ${paginacao.total_registros}`);
  notas.forEach((nota) => {
    console.log(`  - NF ${nota.numero} | ${nota.status} | R$ ${nota.valor_total} | ${nota.cliente_nome}`);
  });
} else {
  console.error(`Erro: ${resposta.status}`);
}

Resposta (200 OK)

json
{
  "success": true,
  "message": "3 registros encontrados",
  "data": {
    "resultados": [
      {
        "id": 145,
        "tipo": "NFE",
        "finalidade": "Saida",
        "numero":"000001234",
        "serie": "1",
        "chave_acesso": "35260212345678000195550010001234561234567890",
        "status": "AUTORIZADO",
        "cliente_id": 42,
        "cliente_nome": "Loja Centro Ltda",
        "origem_tipo": "PEDIDO",
        "valor_total": "1580.00",
        "data_emissao": "2026-02-10T14:30:00-03:00",
        "data_autorizacao": "2026-02-10T14:31:15-03:00"
      },
      {
        "id": 138,
        "tipo": "NFE",
        "finalidade": "Saida",
        "numero":"000001233",
        "serie": "1",
        "chave_acesso": "35260212345678000195550010001233561234567891",
        "status": "AUTORIZADO",
        "cliente_id": 18,
        "cliente_nome": "Maria Silva Confecções ME",
        "origem_tipo": "PEDIDO",
        "valor_total": "3250.50",
        "data_emissao": "2026-02-08T10:15:00-03:00",
        "data_autorizacao": "2026-02-08T10:16:02-03:00"
      },
      {
        "id": 130,
        "tipo": "NFE",
        "finalidade": "ENTRADA",
        "numero":"000001232",
        "serie": "1",
        "chave_acesso": "35260212345678000195550010001232561234567892",
        "status": "AUTORIZADO",
        "cliente_id": null,
        "cliente_nome": null,
        "origem_tipo": "MANUAL",
        "valor_total": "750.00",
        "data_emissao": "2026-02-05T09:00:00-03:00",
        "data_autorizacao": "2026-02-05T09:01:30-03:00"
      }
    ],
    "paginacao": {
      "pagina_atual": 1,
      "total_paginas": 1,
      "total_registros": 3,
      "por_pagina": 25,
      "proxima": null,
      "anterior": null
    }
  }
}

Campos da Listagem

Campo	Tipo	Descrição
`id`	integer	Identificador único da nota fiscal
`tipo`	string	Tipo do documento: `NFE` ou `NFCE`
`finalidade`	string	Finalidade da nota: `Saida` ou `ENTRADA`
`numero`	string / null	Número da nota fiscal (null se ainda não emitida)
`serie`	string	Série da nota fiscal
`chave_acesso`	string / null	Chave de acesso de 44 dígitos (null se ainda não autorizada)
`status`	string	Status atual: `RASCUNHO`, `REGISTRADO`, `VALIDANDO`, `EMITINDO`, `AUTORIZADO`, `REJEITADO`, `CANCELADO`, `DENEGADO`
`cliente_id`	integer / null	ID do cliente vinculado (null se não houver)
`cliente_nome`	string / null	Nome do cliente vinculado
`origem_tipo`	string	Origem da nota: `PEDIDO`, `MANUAL`, etc.
`valor_total`	string	Valor total da nota em formato decimal (ex: `"1580.00"`)
`data_emissao`	datetime / null	Data e hora de emissão (extraída dos dados gerais)
`data_autorizacao`	datetime / null	Data e hora da autorização pela SEFAZ

Obter Nota Fiscal

GET /v1/nf/{id}/

Escopo necessário: nf: read

Retorna os dados completos de uma nota fiscal específica, incluindo dados gerais, totais e itens.

Exemplo com cURL

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

nota_id = 145
resposta = requests.get(f"{BASE_URL}/nf/{nota_id}/", headers=headers)
dados = resposta.json()

if dados["success"]:
    nota = dados["data"]
    print(f"NF {nota['numero']} - {nota['tipo']}")
    print(f"Status: {nota['status']}")
    print(f"Valor total: R$ {nota['valor_total']}")
    print(f"Chave de acesso: {nota['chave_acesso']}")
    if nota["itens"]:
        print("Itens:")
        for item in nota["itens"]:
            print(f"  - {item['produto_descricao']} | Qtd: {item['quantidade']} | R$ {item['valor_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 notaId = 145;

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

const dados = await resposta.json();

if (dados.success) {
  const nota = dados.data;
  console.log(`NF ${nota.numero} - ${nota.tipo}`);
  console.log(`Status: ${nota.status}`);
  console.log(`Valor total: R$ ${nota.valor_total}`);
  console.log(`Chave de acesso: ${nota.chave_acesso}`);
  if (nota.itens && nota.itens.length > 0) {
    console.log("Itens:");
    nota.itens.forEach((item) => {
      console.log(`  - ${item.produto_descricao} | Qtd: ${item.quantidade} | R$ ${item.valor_total}`);
    });
  }
} else {
  console.error(`Erro: ${JSON.stringify(dados)}`);
}

Resposta (200 OK)

json
{
  "success": true,
  "message": "Registro encontrado",
  "data": {
    "id": 145,
    "tipo": "NFE",
    "finalidade": "Saida",
    "numero":"000001234",
    "serie": "1",
    "chave_acesso": "35260212345678000195550010001234561234567890",
    "status": "AUTORIZADO",
    "cliente_id": 42,
    "cliente_nome": "Loja Centro Ltda",
    "origem_tipo": "PEDIDO",
    "origem_id": 89,
    "valor_total": "1580.00",
    "data_emissao": "2026-02-10T14:30:00-03:00",
    "data_autorizacao": "2026-02-10T14:31:15-03:00",
    "protocolo_autorizacao": "135260000123456",
    "dados_gerais": {
      "emissao": {
        "data_emissao": "2026-02-10T14:30:00-03:00",
        "tipo_emissao": "NORMAL"
      },
      "natureza_operacao": "Venda de mercadoria"
    },
    "totais": {
      "valor_total_nota": "1580.00",
      "valor_produtos": "1500.00",
      "valor_frete": "80.00",
      "valor_desconto": "0.00",
      "valor_icms": "270.00",
      "valor_pis": "24.75",
      "valor_cofins": "114.00"
    },
    "data_criacao": "2026-02-10T14:28:00-03:00",
    "data_atualizacao": "2026-02-10T14:31:15-03:00",
    "itens": [
      {
        "id": 301,
        "produto_descricao": "Camiseta Algodão Premium M",
        "quantidade": "10.000",
        "valor_unitario": "89.90",
        "valor_total": "899.00"
      },
      {
        "id": 302,
        "produto_descricao": "Calça Jeans Slim 42",
        "quantidade": "5.000",
        "valor_unitario": "120.20",
        "valor_total": "601.00"
      }
    ]
  }
}

Campos do Detalhe (adicionais à listagem)

Campo	Tipo	Descrição
`origem_id`	integer / null	ID do registro de origem (ex: ID do pedido, se `origem_tipo` for `PEDIDO`)
`protocolo_autorizacao`	string / null	Protocolo de autorização retornado pela SEFAZ
`dados_gerais`	object	Dados gerais da nota (emissão, natureza da operação, etc.)
`totais`	object	Valores totais da nota (produtos, frete, desconto, impostos)
`data_criacao`	datetime	Data e hora de criação do registro
`data_atualizacao`	datetime	Data e hora da última atualização
`itens`	array	Lista de itens da nota fiscal (máximo 100 itens na resposta)

Campos de cada item

Campo	Tipo	Descrição
`id`	integer	Identificador único do item
`produto_descricao`	string	Descrição do produto
`quantidade`	string	Quantidade em formato decimal
`valor_unitario`	string	Valor unitário em formato decimal
`valor_total`	string	Valor total do item em formato decimal

Erros Comuns

Código	Erro	Causa	Solução
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 `nf` ou a ação `read`	Verifique os escopos do token no painel
404	`Nao encontrado`	Nota fiscal não existe ou pertence a outra empresa	Confirme o ID e se a nota pertence à empresa do token
429	`Limite de requisicoes excedido`	Rate limit ultrapassado	Implemente retry com backoff exponencial

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).

Operação	Métodos HTTP	Limite
Leitura	GET, HEAD, OPTIONS	120 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 notas fiscais
Implemente retry com backoff exponencial ao receber 429
Armazene dados em cache local quando possível
Utilize os filtros data_inicio e data_fim para limitar 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}"}

todas_as_notas = []
url = f"{BASE_URL}/nf/?por_pagina=100&status=AUTORIZADO"

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

    if not dados["success"]:
        break

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

print(f"Total obtido: {len(todas_as_notas)} notas fiscais")

Base URL

Autenticação

Endpoints

Listar Notas Fiscais

Query Parameters

Exemplo com cURL

Exemplo com Python

Exemplo com JavaScript

Resposta (200 OK)

Campos da Listagem

Obter Nota Fiscal

Exemplo com cURL

Exemplo com Python

Exemplo com JavaScript

Resposta (200 OK)

Campos do Detalhe (adicionais à listagem)

Campos de cada item

Erros Comuns

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