Listar Arquivos de Retorno

Listar Retornos Disponíveis

Lista os arquivos de retorno disponíveis para uma conta bancária em uma determinada data.

Plano Personalizado

Este endpoint está disponível apenas para contas no plano personalizado com integração automatizada.

O Que Faz

• Lista os arquivos de retorno recepcionados para uma conta bancária
• Filtra por data de gravação do arquivo
• Retorna os tokens para consulta via Obter Retorno

Múltiplos arquivos por dia

Dependendo da configuração junto ao banco, podem haver múltiplos arquivos de retorno disponíveis para uma mesma data. Recomenda-se consultar este endpoint periodicamente ao longo do dia para garantir o processamento de todas as ocorrências.

---

Quando Usar

Cenário	Descrição
Integração VAN	Conta automatizada onde retornos são recepcionados via VAN
Integração API Bancária	Informações recebidas via API do banco
Consulta diária	Descobrir quais arquivos de retorno estão disponíveis para uma data
Conciliação automática	Rotina que consulta periodicamente novos retornos

---

Fluxo de Requisição

Endpoint

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

Parâmetros de Query

Parâmetro	Tipo	Obrigatório	Formato	Descrição
data	string	Sim	YYYY-MM-DD	Data de gravação do arquivo
conta	string	Sim	api-key_{base64}	Token da conta bancária

Headers da Requisição

Header	Valor	Obrigatório
Accept	application/json	Sim
Authorization	Basic {credenciais}	Sim

---

Respostas

Sucesso: 200 OK

Com Arquivos

{
  "retornos": {
    "meta": {
      "conta": "api-key_xYz123AbCdEfGhIjKlMnOpQrStUvWxYz-A1B2C3D4E5F=",
      "data": "2024-01-15"
    },
    "arquivos": [
      {
        "token": "XkO8mgHJYQ8NW7FcWds8PuDKyTKCIJIaOH0a0BfxMIQ="
      }
    ]
  }
}

Sem Arquivos

{
  "retornos": {
    "meta": {
      "conta": "api-key_xYz123AbCdEfGhIjKlMnOpQrStUvWxYz-A1B2C3D4E5F=",
      "data": "2024-01-15"
    },
    "arquivos": []
  }
}

Campos da Resposta

Campo	Tipo	Descrição
retornos.meta.conta	string	Token da conta consultada
retornos.meta.data	string	Data da consulta
retornos.arquivos	array	Lista de arquivos disponíveis
retornos.arquivos[].token	string	Token para Obter Retorno

Erros

Código	Status	Causa
400	Bad Request	Parâmetros data ou conta ausentes ou inválidos
401	Unauthorized	API Key inválida
403	Forbidden	Plano não permite acesso a este endpoint
404	Not Found	Conta bancária não encontrada

---

Exemplos de Código

cURL

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

Java

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

public class ListarRetornos {
    public static void main(String[] args) {
        Response response = ClientBuilder.newClient()
            .target("https://sandbox.boletocloud.com/api/v1/arquivos/cnab/retornos")
            .queryParam("data", "2024-01-15")
            .queryParam("conta", "api-key_SEU-TOKEN-DA-CONTA")
            .register(HttpAuthenticationFeature.basic("api-key_SUA-API-KEY", "token"))
            .request("application/json")
            .get();

        System.out.println("Retornos: " + response.readEntity(String.class));
    }
}

Kotlin

import okhttp3.*

fun main() {
    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/retornos")
        .addQueryParameter("data", "2024-01-15")
        .addQueryParameter("conta", "api-key_SEU-TOKEN-DA-CONTA")
        .build()

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

    client.newCall(request).execute().use { response ->
        println("Retornos: " + response.body?.string())
    }
}

C#

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)
    {
        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"] = "2024-01-15";
        query["conta"] = "api-key_SEU-TOKEN-DA-CONTA";

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

        Console.WriteLine(await response.Content.ReadAsStringAsync());
    }
}

Node

const https = require('https');

const options = {
  hostname: 'sandbox.boletocloud.com',
  path: '/api/v1/arquivos/cnab/retornos?data=2024-01-15&conta=api-key_SEU-TOKEN-DA-CONTA',
  method: 'GET',
  auth: 'api-key_SUA-API-KEY:token'
};

const req = https.request(options, (res) => {
  let data = '';
  res.on('data', chunk => data += chunk);
  res.on('end', () => {
    const dados = JSON.parse(data);
    console.log('Arquivos:', dados.retornos.arquivos.length);
    dados.retornos.arquivos.forEach(a => console.log('Token:', a.token));
  });
});
req.end();

Go

package main

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

func main() {
    baseURL := "https://sandbox.boletocloud.com/api/v1/arquivos/cnab/retornos"
    params := url.Values{}
    params.Add("data", "2024-01-15")
    params.Add("conta", "api-key_SEU-TOKEN-DA-CONTA")

    req, _ := http.NewRequest("GET", baseURL+"?"+params.Encode(), nil)
    req.SetBasicAuth("api-key_SUA-API-KEY", "token")

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

PHP

<?php
$url = 'https://sandbox.boletocloud.com/api/v1/arquivos/cnab/retornos?' .
    http_build_query(['data' => '2024-01-15', 'conta' => 'api-key_SEU-TOKEN-DA-CONTA']);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_USERPWD, "api-key_SUA-API-KEY:token");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$dados = json_decode($response, true);
echo "Arquivos: " . count($dados['retornos']['arquivos']) . "\n";
foreach ($dados['retornos']['arquivos'] as $arq) {
    echo "Token: {$arq['token']}\n";
}
?>

Python

import requests
from requests.auth import HTTPBasicAuth

response = requests.get(
    'https://sandbox.boletocloud.com/api/v1/arquivos/cnab/retornos',
    auth=HTTPBasicAuth('api-key_SUA-API-KEY', 'token'),
    params={'data': '2024-01-15', 'conta': 'api-key_SEU-TOKEN-DA-CONTA'}
)

dados = response.json()
print('Arquivos:', len(dados['retornos']['arquivos']))
for arq in dados['retornos']['arquivos']:
    print('Token:', arq['token'])

Ruby

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

uri = URI('https://sandbox.boletocloud.com/api/v1/arquivos/cnab/retornos')
uri.query = URI.encode_www_form(data: '2024-01-15', conta: 'api-key_SEU-TOKEN-DA-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')

  response = http.request(request)
  dados = JSON.parse(response.body)
  puts "Arquivos: #{dados['retornos']['arquivos'].length}"
end

Clojure

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

(let [response (client/get
                "https://sandbox.boletocloud.com/api/v1/arquivos/cnab/retornos"
                {:basic-auth ["api-key_SUA-API-KEY" "token"]
                 :query-params {:data "2024-01-15"
                                :conta "api-key_SEU-TOKEN-DA-CONTA"}
                 :as :json})]
  (println "Arquivos:" (count (get-in response [:body :retornos :arquivos]))))

---

Veja Também

Obter Retorno Consultar retorno pelo token

Processar Retorno Enviar arquivo manualmente

Visão Geral Retorno Conceitos sobre arquivos de retorno

Arquivos de Remessa Gerar e enviar remessas ao banco