Obter Arquivo de Retorno

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

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

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 "https://sandbox.boletocloud.com/api/v1/arquivos/cnab/retornos/TOKEN_DO_ARQUIVO" \
  -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 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());
        }
    }
}

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

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

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

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

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

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

(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 RetornoEnviar arquivo manualmente

Listar RetornosDescobrir tokens disponíveis

Visão Geral RetornoConceitos sobre arquivos de retorno

Arquivos de RemessaGerar e enviar remessas ao banco

Anterior
Processar Retorno (POST)Próximo
Listar Retornos (GET)