Listar Arquivos de Remessa

Lista os arquivos de remessa disponíveis para uma conta bancária em uma determinada data. Retorna os tokens dos arquivos que podem ser recuperados posteriormente.

O Que Faz

Este endpoint:

Lista os arquivos de remessa gerados para uma conta bancária
Filtra por data de geração
Retorna os tokens dos arquivos em formato JSON
Permite descobrir tokens de remessas para recuperação posterior

Quando Usar

Cenários Recomendados

Cenário	Descrição
Token perdido	Você gerou uma remessa mas não guardou o token retornado
Auditoria	Verificar quais remessas foram geradas em um determinado dia
Reconciliação	Listar remessas para conferência com registros internos
Recuperação	Descobrir o token para usar no endpoint Obter Remessa

Pré-requisitos

Possuir o token da conta bancária
Estar em um plano personalizado
Saber a data aproximada da geração da remessa

Posição no Ciclo de Vida

  ┌──────────────────┐
  │  Criar Remessa   │  POST /arquivos/cnab/remessas
  │  (token perdido) │
  └────────┬─────────┘
           │
           ▼
  ┌──────────────────┐
  │ ★ LISTAR         │  ◄── VOCÊ ESTÁ AQUI
  │   REMESSAS       │
  └────────┬─────────┘
           │
           ▼
  ┌──────────────────┐
  │  Obter Remessa   │  GET /arquivos/cnab/remessas/{token}
  │  com token       │
  └────────┬─────────┘
           │
           ▼
  ┌──────────────────┐
  │  Enviar arquivo  │  Internet Banking
  │    ao banco      │  ou VAN
  └──────────────────┘

Fluxo de Requisição

Endpoint

GET https://sandbox.boletocloud.com/api/v1/arquivos/cnab/remessas?data={data}&conta={token_conta}

Produção:

GET https://app.boletocloud.com/api/v1/arquivos/cnab/remessas?data={data}&conta={token_conta}

Parâmetros de Query

Parâmetro	Tipo	Obrigatório	Formato	Exemplo	Descrição
`data`	string	Sim	`YYYY-MM-DD`	`2024-01-15`	Data de geração das remessas
`conta`	string	Sim	`api-key_{base64}`	`api-key_abc123...`	Token da conta bancária

Headers da Requisição

Header	Valor	Obrigatório	Descrição
`Content-Type`	`application/x-www-form-urlencoded; charset=utf-8`	Sim	Tipo do conteúdo
`Authorization`	`Basic {credenciais}`	Sim	Autenticação HTTP Basic com API Key

Validações

Validação	Regra	Código	Mensagem
Data obrigatória	Parâmetro `data` deve ser informado	`400`	Data é obrigatória
Formato de data	Data deve estar no formato `YYYY-MM-DD`	`400`	Formato de data inválido
Conta obrigatória	Parâmetro `conta` deve ser informado	`400`	Token da conta é obrigatório
Conta válida	Token deve corresponder a uma conta existente	`404`	Conta bancária não encontrada
Permissão	API Key deve ter acesso à conta	`401`	Não autorizado
Plano	Conta deve estar no plano personalizado	`403`	Recurso não disponível para seu plano

Respostas

Sucesso: `200 OK`

Indica que a consulta foi realizada com sucesso. Retorna um JSON com a lista de remessas.

Headers de Resposta

Header	Exemplo	Descrição
`Content-Type`	`application/json; charset=utf-8`	Tipo do conteúdo retornado
`X-BoletoCloud-Version`	`1.x.x`	Versão da plataforma

Corpo da Resposta

{
  "remessas": {
    "meta": {
      "conta": "api-key_xYz123AbCdEfGhIjKlMnOpQrStUvWxYz-A1B2C3D4E5F=",
      "data": "2024-01-15"
    },
    "arquivos": [
      {
        "token": "7kLmN2pQrStUvWxYz-A1B2C3D4E5FgHiJkLmNoPq=",
        "dataHoraCriacao": "2024-01-15T09:30:45Z",
        "numeroOrdemNoDia": 1,
        "numeroSequencial": 1,
        "quantidadeDeBoletos": 15
      },
      {
        "token": "9aBcDeFgHiJkLmNoPqRsTuVwXyZ-1234567890Ab=",
        "dataHoraCriacao": "2024-01-15T17:45:12Z",
        "numeroOrdemNoDia": 2,
        "numeroSequencial": 2,
        "quantidadeDeBoletos": 8
      }
    ]
  }
}

Campos da Resposta

Campo	Tipo	Descrição
`remessas`	object	Objeto contendo metadados e lista de arquivos
`remessas.meta`	object	Metadados da consulta
`remessas.meta.conta`	string	Token da conta bancária consultada
`remessas.meta.data`	string	Data da consulta no formato `YYYY-MM-DD`
`remessas.arquivos`	array	Lista de arquivos de remessa encontrados
`remessas.arquivos[].token`	string	Token identificador do arquivo (use para Obter Remessa)
`remessas.arquivos[].dataHoraCriacao`	string	Data e hora da criação no formato ISO 8601
`remessas.arquivos[].numeroOrdemNoDia`	number	Número de ordem do arquivo no dia
`remessas.arquivos[].numeroSequencial`	number	Número sequencial do arquivo
`remessas.arquivos[].quantidadeDeBoletos`	number	Quantidade de boletos incluídos no arquivo

Erros

Código	Status	Causa	Solução
`400`	Bad Request	Parâmetros ausentes ou inválidos	Verifique `data` e `conta`
`401`	Unauthorized	API Key inválida ou ausente	Verifique as credenciais
`403`	Forbidden	Plano não permite este recurso	Contate o suporte para upgrade
`404`	Not Found	Conta não encontrada	Verifique o token da conta
`500`	Internal Server Error	Erro interno	Tente novamente ou contate o suporte

Exemplo de Erro

{
  "erro": {
    "status": 400,
    "mensagem": "Formato de data inválido. Use YYYY-MM-DD"
  }
}

Exemplos de Código

curl "https://sandbox.boletocloud.com/api/v1/arquivos/cnab/remessas?data=2024-01-15&conta=api-key_SEU-TOKEN-DA-CONTA" \
  -H "Content-Type: application/x-www-form-urlencoded; charset=utf-8" \
  -u "api-key_SUA-API-KEY:token"

Resposta:

{
  "remessas": [
    {
      "token": "EX-abc123def456",
      "nome": "CB070401.REM",
      "dataCriacao": "2024-01-15T09:30:00Z",
      "quantidadeBoletos": 15
    }
  ]
}

import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.core.Response;
import org.glassfish.jersey.client.authentication.HttpAuthenticationFeature;
import static javax.ws.rs.core.MediaType.APPLICATION_JSON;

public class ListarRemessas {
    public static void main(String[] args) throws Exception {
        String data = "2024-01-15";
        String tokenConta = "api-key_SEU-TOKEN-DA-CONTA";

        Response response = ClientBuilder.newClient()
            .target("https://sandbox.boletocloud.com/api/v1/arquivos/cnab/remessas")
            .queryParam("data", data)
            .queryParam("conta", tokenConta)
            .register(HttpAuthenticationFeature.basic(
                "api-key_SUA-API-KEY",
                "token"
            ))
            .request(APPLICATION_JSON)
            .get();

        System.out.println("HTTP Status: " + response.getStatus());

        if (response.getStatus() == 200) {
            String json = response.readEntity(String.class);
            System.out.println("Remessas: " + json);
        } else {
            System.err.println("Erro: " + response.readEntity(String.class));
        }
    }
}

import okhttp3.*

fun main() {
    val data = "2024-01-15"
    val tokenConta = "api-key_SEU-TOKEN-DA-CONTA"
    val client = OkHttpClient()
    val credential = Credentials.basic("api-key_SUA-API-KEY", "token")

    val url = HttpUrl.Builder()
        .scheme("https")
        .host("sandbox.boletocloud.com")
        .addPathSegments("api/v1/arquivos/cnab/remessas")
        .addQueryParameter("data", data)
        .addQueryParameter("conta", tokenConta)
        .build()

    val request = Request.Builder()
        .url(url)
        .header("Authorization", credential)
        .get()
        .build()

    client.newCall(request).execute().use { response ->
        when (response.code) {
            200 -> println("Remessas: " + response.body?.string())
            else -> println("Erro: " + response.code + " - " + response.body?.string())
        }
    }
}

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using System.Web;

class Program
{
    static async Task Main(string[] args)
    {
        var data = "2024-01-15";
        var tokenConta = "api-key_SEU-TOKEN-DA-CONTA";

        using var client = new HttpClient();
        var credentials = Convert.ToBase64String(
            Encoding.ASCII.GetBytes("api-key_SUA-API-KEY:token"));
        client.DefaultRequestHeaders.Authorization =
            new AuthenticationHeaderValue("Basic", credentials);

        var query = HttpUtility.ParseQueryString(string.Empty);
        query["data"] = data;
        query["conta"] = tokenConta;

        var response = await client.GetAsync(
            "https://sandbox.boletocloud.com/api/v1/arquivos/cnab/remessas?"
            + query.ToString());

        var body = await response.Content.ReadAsStringAsync();

        if ((int)response.StatusCode == 200)
        {
            Console.WriteLine("Remessas: " + body);
        }
        else
        {
            Console.WriteLine("Erro: " + (int)response.StatusCode + " - " + body);
        }
    }
}

const https = require('https');

const data = '2024-01-15';
const tokenConta = 'api-key_SEU-TOKEN-DA-CONTA';

const options = {
  hostname: 'sandbox.boletocloud.com',
  path: '/api/v1/arquivos/cnab/remessas?data=' +
    encodeURIComponent(data) + '&conta=' + encodeURIComponent(tokenConta),
  method: 'GET',
  auth: 'api-key_SUA-API-KEY:token',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded; charset=utf-8'
  }
};

const req = https.request(options, (res) => {
  let body = '';
  res.on('data', chunk => body += chunk);
  res.on('end', () => {
    if (res.statusCode === 200) {
      console.log('Remessas:', JSON.parse(body));
    } else {
      console.log('Erro:', res.statusCode, '-', body);
    }
  });
});

req.end();

package main

import (
    "fmt"
    "io"
    "net/http"
    "net/url"
)

func main() {
    data := "2024-01-15"
    tokenConta := "api-key_SEU-TOKEN-DA-CONTA"

    baseURL := "https://sandbox.boletocloud.com/api/v1/arquivos/cnab/remessas"
    params := url.Values{}
    params.Add("data", data)
    params.Add("conta", tokenConta)

    req, _ := http.NewRequest("GET", baseURL+"?"+params.Encode(), nil)
    req.SetBasicAuth("api-key_SUA-API-KEY", "token")
    req.Header.Set("Content-Type",
        "application/x-www-form-urlencoded; charset=utf-8")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)

    if resp.StatusCode == 200 {
        fmt.Println("Remessas:", string(body))
    } else {
        fmt.Printf("Erro: %d - %s\n", resp.StatusCode, string(body))
    }
}

<?php
$data = '2024-01-15';
$tokenConta = 'api-key_SEU-TOKEN-DA-CONTA';
$api_key = 'api-key_SUA-API-KEY';

$url = 'https://sandbox.boletocloud.com/api/v1/arquivos/cnab/remessas?' .
    http_build_query([
        'data' => $data,
        'conta' => $tokenConta
    ]);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/x-www-form-urlencoded; charset=utf-8'
]);
curl_setopt($ch, CURLOPT_USERPWD, "$api_key:token");
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($http_code == 200) {
    $dados = json_decode($response, true);
    echo "Conta: {$dados['remessas']['meta']['conta']}\n";
    echo "Data: {$dados['remessas']['meta']['data']}\n";
    echo "Remessas encontradas:\n";
    foreach ($dados['remessas']['arquivos'] as $arquivo) {
        echo "- Token: {$arquivo['token']}\n";
        echo "  Data/Hora: {$arquivo['dataHoraCriacao']}\n";
        echo "  Boletos: {$arquivo['quantidadeDeBoletos']}\n";
    }
} else {
    echo "Erro ($http_code): $response\n";
}
?>

import requests
from requests.auth import HTTPBasicAuth

data = '2024-01-15'
token_conta = 'api-key_SEU-TOKEN-DA-CONTA'

response = requests.get(
    'https://sandbox.boletocloud.com/api/v1/arquivos/cnab/remessas',
    auth=HTTPBasicAuth('api-key_SUA-API-KEY', 'token'),
    params={
        'data': data,
        'conta': token_conta
    }
)

if response.status_code == 200:
    dados = response.json()
    meta = dados['remessas']['meta']
    print(f"Conta: {meta['conta']}")
    print(f"Data: {meta['data']}")
    print('Remessas encontradas:')
    for arquivo in dados['remessas']['arquivos']:
        print(f"- Token: {arquivo['token']}")
        print(f"  Data/Hora: {arquivo['dataHoraCriacao']}")
        print(f"  Boletos: {arquivo['quantidadeDeBoletos']}")
else:
    print('Erro:', response.status_code, '-', response.text)

require 'net/http'
require 'uri'
require 'json'

data = '2024-01-15'
token_conta = 'api-key_SEU-TOKEN-DA-CONTA'

uri = URI('https://sandbox.boletocloud.com/api/v1/arquivos/cnab/remessas')
uri.query = URI.encode_www_form(data: data, conta: token_conta)

Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
  request = Net::HTTP::Get.new(uri)
  request.basic_auth('api-key_SUA-API-KEY', 'token')
  request['Content-Type'] = 'application/x-www-form-urlencoded; charset=utf-8'

  response = http.request(request)

  if response.code == '200'
    dados = JSON.parse(response.body)
    meta = dados['remessas']['meta']
    puts "Conta: #{meta['conta']}"
    puts "Data: #{meta['data']}"
    puts 'Remessas encontradas:'
    dados['remessas']['arquivos'].each do |arquivo|
      puts "- Token: #{arquivo['token']}"
      puts "  Data/Hora: #{arquivo['dataHoraCriacao']}"
      puts "  Boletos: #{arquivo['quantidadeDeBoletos']}"
    end
  else
    puts "Erro: #{response.code} - #{response.body}"
  end
end

(require '[clj-http.client :as client])
(require '[clojure.data.json :as json])

(let [data "2024-01-15"
      token-conta "api-key_SEU-TOKEN-DA-CONTA"
      response (client/get
                "https://sandbox.boletocloud.com/api/v1/arquivos/cnab/remessas"
                {:basic-auth ["api-key_SUA-API-KEY" "token"]
                 :query-params {:data data :conta token-conta}
                 :throw-exceptions false})]

  (if (= 200 (:status response))
    (let [dados (json/read-str (:body response) :key-fn keyword)
          meta (get-in dados [:remessas :meta])
          arquivos (get-in dados [:remessas :arquivos])]
      (println "Conta:" (:conta meta))
      (println "Data:" (:data meta))
      (println "Remessas encontradas:")
      (doseq [arquivo arquivos]
        (println (str "- Token: " (:token arquivo)))
        (println (str "  Data/Hora: " (:dataHoraCriacao arquivo)))
        (println (str "  Boletos: " (:quantidadeDeBoletos arquivo)))))
    (println "Erro:" (:status response) "-" (:body response))))

Exemplo Prático

Cenário: Descobrir Token de Remessa Perdido

Um operador gerou uma remessa pela manhã mas não guardou o token. Agora precisa reenviar o arquivo ao banco.

Listar remessas do dia usando este endpoint
Identificar a remessa correta pelo horário e quantidade de boletos
Copiar o token da remessa desejada
Usar o token no endpoint Obter Remessa
Baixar o arquivo e enviar ao banco

Requisição

curl "https://sandbox.boletocloud.com/api/v1/arquivos/cnab/remessas?data=2024-01-15&conta=api-key_SEU-TOKEN-DA-CONTA" \
  -u "api-key_SUA-API-KEY:token"

Resposta

{
  "remessas": {
    "meta": {
      "conta": "api-key_xYz123AbCdEfGhIjKlMnOpQrStUvWxYz-A1B2C3D4E5F=",
      "data": "2024-01-15"
    },
    "arquivos": [
      {
        "token": "7kLmN2pQrStUvWxYz-A1B2C3D4E5FgHiJkLmNoPq=",
        "dataHoraCriacao": "2024-01-15T09:30:45Z",
        "numeroOrdemNoDia": 1,
        "numeroSequencial": 1,
        "quantidadeDeBoletos": 15
      },
      {
        "token": "9aBcDeFgHiJkLmNoPqRsTuVwXyZ-1234567890Ab=",
        "dataHoraCriacao": "2024-01-15T17:45:12Z",
        "numeroOrdemNoDia": 2,
        "numeroSequencial": 2,
        "quantidadeDeBoletos": 8
      }
    ]
  }
}

O operador identifica que a remessa da manhã (09:30) é a que precisa e usa o token 7kLmN2pQrStUvWxYz-A1B2C3D4E5FgHiJkLmNoPq= para recuperar o arquivo.

Veja Também

Criar RemessaGerar novo arquivo de remessa

Obter RemessaRecuperar arquivo pelo token

Visão Geral RemessaConceitos sobre arquivos de remessa

Arquivos de RetornoProcessar retornos bancários

Anterior
Obter Remessa (GET)Próximo
Visão Geral