Obter Arquivo de Retorno

Obter Arquivo de Retorno

Recupera o JSON de um arquivo de retorno já processado através do seu token.

Plano Personalizado

Este endpoint está disponível apenas para contas no plano personalizado com integração automatizada (VAN ou API Bancária).

O Que Faz

Este endpoint:

• Recupera o JSON de um arquivo de retorno pelo token
• Retorna a mesma estrutura do processamento original
• Permite consultar retornos recebidos automaticamente via VAN/API

---

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
Reprocessamento	Consultar novamente um retorno já processado
Falha de rede	Retorno foi processado mas resposta não chegou

---

Fluxo de Requisição

Endpoint

GET https://sandbox.boletocloud.com/api/v1/arquivos/cnab/retornos/{token}

Parâmetros de Path

Parâmetro	Tipo	Obrigatório	Descrição
token	string	Sim	Token do arquivo de retorno

Headers da Requisição

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

---

Respostas

Sucesso: 200 OK

{
  "arquivo": {
    "meta": {
      "token": "PEaenWxYddN6Q_NT1PiOYfz4EsZu7jRXRlpAsNpBU-A=",
      "criado": "2024-01-15T10:30:00Z"
    },
    "protocolo": {
      "banco": { "codigo": "237", "nome": "BRADESCO" },
      "numero": 12345,
      "gravacao": "2024-01-14"
    },
    "titulos": [
      {
        "token": "ulBx9quRyPkogs6rkvjO7SjqJb8ZnFmdyM0B5rasoDA=",
        "numero": "00000000001-0",
        "documento": "FAT-001",
        "valor": 250.00,
        "vencimento": "2024-01-20",
        "ocorrencias": [
          {
            "situacao": "LIQUIDACAO",
            "codigo": 6,
            "data": "2024-01-14",
            "descricao": "Liquidação Normal",
            "motivos": [],
            "info": {
              "valorPago": 252.00,
              "jurosMora": 2.00,
              "dataDePagamento": "2024-01-14",
              "dataDeCredito": "2024-01-16",
              "situacao": "LIQUIDACAO"
            }
          }
        ]
      }
    ]
  }
}

Token nulo

Títulos presentes no arquivo que não correspondam a boletos cadastrados na plataforma terão o campo token com valor null. Isso permite identificar pagamentos de boletos emitidos fora do Boleto Cloud.

Erros

Código	Status	Causa
401	Unauthorized	API Key inválida
403	Forbidden	Plano não permite
404	Not Found	Arquivo não encontrado

---

Exemplos de Código

cURL

curl "https://sandbox.boletocloud.com/api/v1/arquivos/cnab/retornos/TOKEN_DO_ARQUIVO" \
  -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 ObterRetorno {
    public static void main(String[] args) {
        String tokenArquivo = "TOKEN_DO_ARQUIVO";

        Response response = ClientBuilder.newClient()
            .target("https://sandbox.boletocloud.com/api/v1/arquivos/cnab/retornos/"
                + tokenArquivo)
            .register(HttpAuthenticationFeature.basic("api-key_SUA-API-KEY", "token"))
            .request("application/json")
            .get();

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

Kotlin

import okhttp3.*

fun main() {
    val tokenArquivo = "TOKEN_DO_ARQUIVO"
    val client = OkHttpClient()
    val credential = Credentials.basic("api-key_SUA-API-KEY", "token")

    val request = Request.Builder()
        .url("https://sandbox.boletocloud.com/api/v1/arquivos/cnab/retornos/$tokenArquivo")
        .header("Authorization", credential)
        .header("Accept", "application/json")
        .get()
        .build()

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

C#

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

class Program
{
    static async Task Main(string[] args)
    {
        var tokenArquivo = "TOKEN_DO_ARQUIVO";
        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 response = await client.GetAsync(
            "https://sandbox.boletocloud.com/api/v1/arquivos/cnab/retornos/"
            + tokenArquivo);

        var body = await response.Content.ReadAsStringAsync();
        Console.WriteLine(response.IsSuccessStatusCode ? body : "Erro: " + response.StatusCode);
    }
}

Node

const https = require('https');

const tokenArquivo = 'TOKEN_DO_ARQUIVO';
const options = {
  hostname: 'sandbox.boletocloud.com',
  path: '/api/v1/arquivos/cnab/retornos/' + encodeURIComponent(tokenArquivo),
  method: 'GET',
  auth: 'api-key_SUA-API-KEY:token',
  headers: { 'Accept': 'application/json' }
};

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

Go

package main

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

func main() {
    tokenArquivo := "TOKEN_DO_ARQUIVO"
    url := "https://sandbox.boletocloud.com/api/v1/arquivos/cnab/retornos/" + tokenArquivo

    req, _ := http.NewRequest("GET", url, nil)
    req.SetBasicAuth("api-key_SUA-API-KEY", "token")
    req.Header.Set("Accept", "application/json")

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

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

PHP

<?php
$tokenArquivo = 'TOKEN_DO_ARQUIVO';
$url = "https://sandbox.boletocloud.com/api/v1/arquivos/cnab/retornos/$tokenArquivo";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Accept: application/json'));
curl_setopt($ch, CURLOPT_USERPWD, "api-key_SUA-API-KEY:token");
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) {
    $retorno = json_decode($response, true);
    foreach ($retorno['arquivo']['titulos'] as $titulo) {
        echo "Boleto: {$titulo['numero']}\n";
    }
}
?>

Python

import requests
from requests.auth import HTTPBasicAuth

token_arquivo = 'TOKEN_DO_ARQUIVO'
response = requests.get(
    f'https://sandbox.boletocloud.com/api/v1/arquivos/cnab/retornos/{token_arquivo}',
    auth=HTTPBasicAuth('api-key_SUA-API-KEY', 'token'),
    headers={'Accept': 'application/json'}
)

if response.status_code == 200:
    for titulo in response.json()['arquivo']['titulos']:
        print(f"Boleto: {titulo['numero']}")

Ruby

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

token_arquivo = 'TOKEN_DO_ARQUIVO'
uri = URI("https://sandbox.boletocloud.com/api/v1/arquivos/cnab/retornos/#{token_arquivo}")

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['Accept'] = 'application/json'

  response = http.request(request)
  puts response.body if response.code == '200'
end

Clojure

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

(let [token-arquivo "TOKEN_DO_ARQUIVO"
      response (client/get
                (str "https://sandbox.boletocloud.com/api/v1/arquivos/cnab/retornos/"
                     token-arquivo)
                {:basic-auth ["api-key_SUA-API-KEY" "token"]
                 :headers {"Accept" "application/json"}
                 :as :json})]
  (println (get-in response [:body :arquivo :titulos])))

---

Veja Também

Processar Retorno Enviar arquivo manualmente

Listar Retornos Descobrir tokens disponíveis

Visão Geral Retorno Conceitos sobre arquivos de retorno

Arquivos de Remessa Gerar e enviar remessas ao banco