API de Cobranças Bancárias

Consulte remessas e retornos bancários do Bunto ERP. Estes endpoints permitem listar e consultar arquivos de remessa e retorno de cobranças bancárias de forma somente leitura via API.

Base URL

Produção:

code
https://api-backend.bunto.com.br/v1/remessas/
https://api-backend.bunto.com.br/v1/retornos/

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

Endpoints - Remessas

Listar Remessas

GET /v1/remessas/

Escopo necessário: cobrancas_bancarias: read

Retorna a lista paginada de remessas bancárias da empresa, ordenadas pela data de geração mais recente.

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)
`status`	string	-	Filtrar por status: `gerada`, `enviada`, `processada` ou `erro`
`conta_bancaria_id`	integer	-	Filtrar remessas de uma conta bancária específica
`data_inicio`	string	-	Data inicial do período (formato: `YYYY-MM-DD`)
`data_fim`	string	-	Data final do período (formato: `YYYY-MM-DD`)

Exemplo com cURL

bash
curl 'https://api-backend.bunto.com.br/v1/remessas/?pagina=1&por_pagina=10&status=gerada' \
  -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 remessas geradas no periodo
resposta = requests.get(
    f"{BASE_URL}/remessas/",
    headers=headers,
    params={
        "pagina": 1,
        "por_pagina": 25,
        "status": "gerada",
        "data_inicio": "2026-01-01",
        "data_fim": "2026-02-12",
    },
)

dados = resposta.json()

if dados["success"]:
    remessas = dados["data"]["resultados"]
    paginacao = dados["data"]["paginacao"]
    print(f"Total de remessas: {paginacao['total_registros']}")
    for remessa in remessas:
        print(f"  - Remessa #{remessa['numero']} | {remessa['nome_arquivo']} | {remessa['quantidade_titulos']} titulos | R$ {remessa['valor_total']}")
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: "gerada",
  data_inicio: "2026-01-01",
  data_fim: "2026-02-12",
});

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

const dados = await resposta.json();

if (dados.success) {
  const remessas = dados.data.resultados;
  const paginacao = dados.data.paginacao;
  console.log(`Total de remessas: ${paginacao.total_registros}`);
  remessas.forEach((remessa) => {
    console.log(`  - Remessa #${remessa.numero} | ${remessa.nome_arquivo} | ${remessa.quantidade_titulos} titulos | R$ ${remessa.valor_total}`);
  });
} else {
  console.error(`Erro: ${resposta.status}`);
}

Resposta (200 OK)

json
{
  "success": true,
  "message": "5 registros encontrados",
  "data": {
    "resultados": [
      {
        "id": 10,
        "numero":42,
        "data_geracao": "2026-02-10T14:30:00-03:00",
        "conta_bancaria_id": 1,
        "nome_arquivo": "CB100226.REM",
        "quantidade_titulos": 15,
        "valor_total": "4520.75",
        "status": "gerada"
      },
      {
        "id": 9,
        "numero":41,
        "data_geracao": "2026-02-05T10:15:00-03:00",
        "conta_bancaria_id": 1,
        "nome_arquivo": "CB050226.REM",
        "quantidade_titulos": 8,
        "valor_total": "2100.00",
        "status": "gerada"
      }
    ],
    "paginacao": {
      "pagina_atual": 1,
      "total_paginas": 1,
      "total_registros": 5,
      "por_pagina": 25,
      "proxima": null,
      "anterior": null
    }
  }
}

Campos da Listagem de Remessas

Campo	Tipo	Descrição
`id`	integer	Identificador único da remessa
`numero`	integer	Número sequencial da remessa
`data_geracao`	datetime	Data e hora em que a remessa foi gerada
`conta_bancaria_id`	integer	ID da conta bancária associada
`nome_arquivo`	string	Nome do arquivo de remessa gerado
`quantidade_titulos`	integer	Quantidade de títulos (boletos) na remessa
`valor_total`	decimal	Valor total dos títulos na remessa
`status`	string	Status da remessa: `gerada`, `enviada`, `processada` ou `erro`

Obter Remessa

GET /v1/remessas/{id}/

Escopo necessário: cobrancas_bancarias: read

Retorna os dados completos de uma remessa bancária específica, incluindo a data de criação do registro.

Exemplo com cURL

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

remessa_id = 10
resposta = requests.get(f"{BASE_URL}/remessas/{remessa_id}/", headers=headers)
dados = resposta.json()

if dados["success"]:
    remessa = dados["data"]
    print(f"Remessa #{remessa['numero']}")
    print(f"Arquivo: {remessa['nome_arquivo']}")
    print(f"Titulos: {remessa['quantidade_titulos']}")
    print(f"Valor total: R$ {remessa['valor_total']}")
    print(f"Status: {remessa['status']}")
else:
    print(f"Erro: {dados}")

Exemplo com JavaScript

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

const remessaId = 10;

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

const dados = await resposta.json();

if (dados.success) {
  const remessa = dados.data;
  console.log(`Remessa #${remessa.numero}`);
  console.log(`Arquivo: ${remessa.nome_arquivo}`);
  console.log(`Titulos: ${remessa.quantidade_titulos}`);
  console.log(`Valor total: R$ ${remessa.valor_total}`);
  console.log(`Status: ${remessa.status}`);
} else {
  console.error(`Erro: ${JSON.stringify(dados)}`);
}

Resposta (200 OK)

json
{
  "success": true,
  "message": "Registro encontrado",
  "data": {
    "id": 10,
    "numero":42,
    "data_geracao": "2026-02-10T14:30:00-03:00",
    "conta_bancaria_id": 1,
    "nome_arquivo": "CB100226.REM",
    "quantidade_titulos": 15,
    "valor_total": "4520.75",
    "status": "gerada",
    "data_criacao": "2026-02-10T14:30:00-03:00"
  }
}

Campos do Detalhe de Remessa (adicionais à listagem)

Campo	Tipo	Descrição
`data_criacao`	datetime	Data e hora de criação do registro

Endpoints - Retornos

Listar Retornos

GET /v1/retornos/

Escopo necessário: cobrancas_bancarias: read

Retorna a lista paginada de retornos bancários da empresa, ordenados pela data de processamento mais recente.

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)
`status`	string	-	Filtrar por status: `processando`, `processado` ou `erro`
`conta_bancaria_id`	integer	-	Filtrar retornos de uma conta bancária específica
`data_inicio`	string	-	Data inicial do período (formato: `YYYY-MM-DD`)
`data_fim`	string	-	Data final do período (formato: `YYYY-MM-DD`)

Exemplo com cURL

bash
curl 'https://api-backend.bunto.com.br/v1/retornos/?pagina=1&por_pagina=10&status=processado' \
  -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 retornos processados no periodo
resposta = requests.get(
    f"{BASE_URL}/retornos/",
    headers=headers,
    params={
        "pagina": 1,
        "por_pagina": 25,
        "status": "processado",
        "data_inicio": "2026-01-01",
        "data_fim": "2026-02-12",
    },
)

dados = resposta.json()

if dados["success"]:
    retornos = dados["data"]["resultados"]
    paginacao = dados["data"]["paginacao"]
    print(f"Total de retornos: {paginacao['total_registros']}")
    for retorno in retornos:
        print(f"  - Retorno #{retorno['id']} | Liquidados: {retorno['quantidade_liquidados']} | Rejeitados: {retorno['quantidade_rejeitados']} | Recebido: R$ {retorno['valor_total_recebido']}")
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: "processado",
  data_inicio: "2026-01-01",
  data_fim: "2026-02-12",
});

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

const dados = await resposta.json();

if (dados.success) {
  const retornos = dados.data.resultados;
  const paginacao = dados.data.paginacao;
  console.log(`Total de retornos: ${paginacao.total_registros}`);
  retornos.forEach((retorno) => {
    console.log(`  - Retorno #${retorno.id} | Liquidados: ${retorno.quantidade_liquidados} | Rejeitados: ${retorno.quantidade_rejeitados} | Recebido: R$ ${retorno.valor_total_recebido}`);
  });
} else {
  console.error(`Erro: ${resposta.status}`);
}

Resposta (200 OK)

json
{
  "success": true,
  "message": "4 registros encontrados",
  "data": {
    "resultados": [
      {
        "id": 7,
        "data_processamento": "2026-02-11T09:45:00-03:00",
        "conta_bancaria_id": 1,
        "quantidade_titulos": 15,
        "quantidade_liquidados": 12,
        "quantidade_rejeitados": 3,
        "valor_total_recebido": "3850.50",
        "valor_total_tarifas": "45.00",
        "status": "processado"
      },
      {
        "id": 6,
        "data_processamento": "2026-02-06T08:30:00-03:00",
        "conta_bancaria_id": 1,
        "quantidade_titulos": 8,
        "quantidade_liquidados": 8,
        "quantidade_rejeitados": 0,
        "valor_total_recebido": "2100.00",
        "valor_total_tarifas": "24.00",
        "status": "processado"
      }
    ],
    "paginacao": {
      "pagina_atual": 1,
      "total_paginas": 1,
      "total_registros": 4,
      "por_pagina": 25,
      "proxima": null,
      "anterior": null
    }
  }
}

Campos da Listagem de Retornos

Campo	Tipo	Descrição
`id`	integer	Identificador único do retorno
`data_processamento`	datetime	Data e hora em que o retorno foi processado
`conta_bancaria_id`	integer	ID da conta bancária associada
`quantidade_titulos`	integer	Quantidade total de títulos no retorno
`quantidade_liquidados`	integer	Quantidade de títulos liquidados (pagos)
`quantidade_rejeitados`	integer	Quantidade de títulos rejeitados
`valor_total_recebido`	decimal	Valor total recebido (líquido)
`valor_total_tarifas`	decimal	Valor total de tarifas cobradas pelo banco
`status`	string	Status do retorno: `processando`, `processado` ou `erro`

Obter Retorno

GET /v1/retornos/{id}/

Escopo necessário: cobrancas_bancarias: read

Retorna os dados completos de um retorno bancário específico, incluindo o nome do arquivo e a data de criação do registro.

Exemplo com cURL

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

retorno_id = 7
resposta = requests.get(f"{BASE_URL}/retornos/{retorno_id}/", headers=headers)
dados = resposta.json()

if dados["success"]:
    retorno = dados["data"]
    print(f"Retorno #{retorno['id']}")
    print(f"Arquivo: {retorno['nome_arquivo']}")
    print(f"Titulos: {retorno['quantidade_titulos']} (liquidados: {retorno['quantidade_liquidados']}, rejeitados: {retorno['quantidade_rejeitados']})")
    print(f"Valor recebido: R$ {retorno['valor_total_recebido']}")
    print(f"Tarifas: R$ {retorno['valor_total_tarifas']}")
    print(f"Status: {retorno['status']}")
else:
    print(f"Erro: {dados}")

Exemplo com JavaScript

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

const retornoId = 7;

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

const dados = await resposta.json();

if (dados.success) {
  const retorno = dados.data;
  console.log(`Retorno #${retorno.id}`);
  console.log(`Arquivo: ${retorno.nome_arquivo}`);
  console.log(`Titulos: ${retorno.quantidade_titulos} (liquidados: ${retorno.quantidade_liquidados}, rejeitados: ${retorno.quantidade_rejeitados})`);
  console.log(`Valor recebido: R$ ${retorno.valor_total_recebido}`);
  console.log(`Tarifas: R$ ${retorno.valor_total_tarifas}`);
  console.log(`Status: ${retorno.status}`);
} else {
  console.error(`Erro: ${JSON.stringify(dados)}`);
}

Resposta (200 OK)

json
{
  "success": true,
  "message": "Registro encontrado",
  "data": {
    "id": 7,
    "data_processamento": "2026-02-11T09:45:00-03:00",
    "conta_bancaria_id": 1,
    "quantidade_titulos": 15,
    "quantidade_liquidados": 12,
    "quantidade_rejeitados": 3,
    "valor_total_recebido": "3850.50",
    "valor_total_tarifas": "45.00",
    "status": "processado",
    "nome_arquivo": "CB110226.RET",
    "data_criacao": "2026-02-11T09:45:00-03:00"
  }
}

Campos do Detalhe de Retorno (adicionais à listagem)

Campo	Tipo	Descrição
`nome_arquivo`	string	Nome do arquivo de retorno processado
`data_criacao`	datetime	Data e hora de criação do registro

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 `cobrancas_bancarias` ou a ação `read`	Verifique os escopos do token no painel
404	`Nao encontrado`	Registro não existe ou pertence a outra empresa	Confirme o ID e se o registro 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 registros
Implemente retry com backoff exponencial ao receber 429
Armazene dados em cache local quando possível
Use 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 de remessas (Python)

python
import requests

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

headers = {"Authorization": f"Bearer {TOKEN}"}

todas_as_remessas = []
url = f"{BASE_URL}/remessas/?por_pagina=100"

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

    if not dados["success"]:
        break

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

print(f"Total obtido: {len(todas_as_remessas)} remessas")

Base URL

Autenticação

Endpoints - Remessas

Listar Remessas

Query Parameters

Exemplo com cURL

Exemplo com Python

Exemplo com JavaScript

Resposta (200 OK)

Campos da Listagem de Remessas

Obter Remessa

Exemplo com cURL

Exemplo com Python

Exemplo com JavaScript

Resposta (200 OK)

Campos do Detalhe de Remessa (adicionais à listagem)

Endpoints - Retornos

Listar Retornos

Query Parameters

Exemplo com cURL

Exemplo com Python

Exemplo com JavaScript

Resposta (200 OK)

Campos da Listagem de Retornos

Obter Retorno

Exemplo com cURL

Exemplo com Python

Exemplo com JavaScript

Resposta (200 OK)

Campos do Detalhe de Retorno (adicionais à listagem)

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 de remessas (Python)

Objeto `paginacao` na resposta