Listar Arquivos de Retorno

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

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

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

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));
    }
}

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())
    }
}

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());
    }
}

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();

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
$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";
}
?>

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'])

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

(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 RetornoConsultar retorno pelo token

Processar RetornoEnviar arquivo manualmente

Visão Geral RetornoConceitos sobre arquivos de retorno

Arquivos de RemessaGerar e enviar remessas ao banco

Anterior
Obter Retorno (GET)Próximo
Boleto com Pix