Obter PDF do Carnê

Buscar PDF do Carnê (GET)

Recupera o PDF consolidado do carnê com todos os boletos organizados (3 por página). Este é o segundo passo após criar o carnê.

O que este endpoint faz

Recebe o token do carnê
Recupera os boletos associados
Gera o PDF consolidado (3 boletos por página)
Retorna o arquivo PDF pronto para impressão

┌──────────────────┐      ┌──────────────────┐      ┌──────────────────┐
│  GET /carnes/    │─────▶│   Recuperar      │─────▶│   Gerar PDF      │
│  {token}         │      │   boletos        │      │   consolidado    │
└──────────────────┘      └──────────────────┘      └──────────────────┘
                                                             │
                                                             ▼
                                               ┌──────────────────────┐
                                               │  Retornar PDF        │
                                               │  (application/pdf)   │
                                               └──────────────────────┘

Quando Usar

Cenário	Descrição
Após criar carnê	Obter o PDF consolidado logo após POST /carnes
Reimpressão	Reimprimir carnê completo usando o token salvo
Download por demanda	Permitir que o cliente baixe o carnê via sistema

Endpoint

GET https://sandbox.boletocloud.com/api/v1/carnes/{token}

Ambiente	URL Base
Sandbox	`https://sandbox.boletocloud.com/api/v1/carnes/{token}`
Produção	`https://app.boletocloud.com/api/v1/carnes/{token}`

Requisição

Parâmetros de Path

Parâmetro	Tipo	Obrigatório	Descrição
`token`	string	Sim	Token do carnê retornado na criação (`batch.token` ou header `X-BoletoCloud-Token`)

Headers

Header	Valor	Obrigatório
`Authorization`	`Basic {credenciais_base64}`	Sim

Respostas

200 OK — Sucesso

O PDF do carnê foi gerado com sucesso.

Headers da Resposta (200)

Header	Descrição	Exemplo
`Content-Type`	Tipo do conteúdo	`application/pdf; charset=UTF-8`
`Content-Disposition`	Nome sugerido para download	`attachment; filename="carne.pdf"`
`X-BoletoCloud-Version`	Versão da plataforma	`2.0.0`

Body da Resposta (200)

O body contém o arquivo PDF binário do carnê, com 3 boletos por página, pronto para impressão.

404 Not Found — Token Não Encontrado

Retornado quando o token informado não corresponde a nenhum carnê.

{
  "erro": {
    "status": 404,
    "tipo": "nao_encontrado",
    "causas": [
      {
        "codigo": "XXXXXXXX",
        "mensagem": "Recurso não encontrado.",
        "suporte": "https://developers.boleto.cloud/"
      }
    ]
  }
}

401 Unauthorized — Autenticação Inválida

Retornado quando as credenciais de autenticação são inválidas.

Exemplos de Código

curl "https://sandbox.boletocloud.com/api/v1/carnes/TOKEN_DO_CARNE" \
  -u "api-key_SUA-API-KEY:token" \
  -o carne.pdf

echo "PDF do carne salvo com sucesso!"

import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.core.Response;
import org.glassfish.jersey.client.authentication.HttpAuthenticationFeature;
import java.io.InputStream;
import java.nio.file.Files;
import java.nio.file.Paths;
import static javax.ws.rs.core.MediaType.WILDCARD;
import static javax.ws.rs.core.Response.Status.OK;
import static java.nio.file.StandardCopyOption.REPLACE_EXISTING;

public class BuscarPdfCarne {
    public static void main(String[] args) throws Exception {
        String carneToken = "TOKEN_DO_CARNE";

        Response response = ClientBuilder.newClient()
            .target("https://sandbox.boletocloud.com/api/v1/carnes")
            .path("/" + carneToken)
            .register(HttpAuthenticationFeature.basic(
                "api-key_SUA-API-KEY", "token"))
            .request(WILDCARD)
            .get();

        if (response.getStatus() == OK.getStatusCode()) {
            Files.copy(response.readEntity(InputStream.class),
                Paths.get("carne.pdf"), REPLACE_EXISTING);
            System.out.println("PDF do carne salvo com sucesso!");
        } else if (response.getStatus() == 404) {
            System.out.println("Carne nao encontrado");
        } else {
            System.out.println("Erro: " + response.getStatus());
        }
    }
}

import okhttp3.*
import java.io.File

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

    val request = Request.Builder()
        .url("https://sandbox.boletocloud.com/api/v1/carnes/$carneToken")
        .header("Authorization", credential)
        .get()
        .build()

    client.newCall(request).execute().use { response ->
        when (response.code) {
            200 -> {
                File("carne.pdf").writeBytes(response.body!!.bytes())
                println("PDF do carne salvo com sucesso!")
            }
            404 -> println("Carne nao encontrado")
            else -> println("Erro: ${response.code}")
        }
    }
}

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

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 carneToken = "TOKEN_DO_CARNE";
        var response = await client.GetAsync(
            $"https://sandbox.boletocloud.com/api/v1/carnes/{carneToken}");

        if (response.IsSuccessStatusCode)
        {
            var bytes = await response.Content.ReadAsByteArrayAsync();
            await File.WriteAllBytesAsync("carne.pdf", bytes);
            Console.WriteLine("PDF do carne salvo com sucesso!");
        }
        else if ((int)response.StatusCode == 404)
        {
            Console.WriteLine("Carne nao encontrado");
        }
        else
        {
            Console.WriteLine($"Erro: {(int)response.StatusCode}");
        }
    }
}

const https = require('https');
const fs = require('fs');

const carneToken = 'TOKEN_DO_CARNE';

const options = {
  hostname: 'sandbox.boletocloud.com',
  path: '/api/v1/carnes/' + encodeURIComponent(carneToken),
  method: 'GET',
  auth: 'api-key_SUA-API-KEY:token'
};

const req = https.request(options, (res) => {
  if (res.statusCode === 200) {
    const file = fs.createWriteStream('carne.pdf');
    res.pipe(file);
    file.on('finish', () => {
      console.log('PDF do carne salvo com sucesso!');
    });
  } else if (res.statusCode === 404) {
    console.log('Carne nao encontrado');
  } else {
    console.log('Erro: ' + res.statusCode);
  }
});

req.end();

package main

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

func main() {
    carneToken := "TOKEN_DO_CARNE"
    url := "https://sandbox.boletocloud.com/api/v1/carnes/" + carneToken

    req, _ := http.NewRequest("GET", url, nil)
    req.SetBasicAuth("api-key_SUA-API-KEY", "token")

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

    if resp.StatusCode == 200 {
        file, _ := os.Create("carne.pdf")
        defer file.Close()
        io.Copy(file, resp.Body)
        fmt.Println("PDF do carne salvo com sucesso!")
    } else if resp.StatusCode == 404 {
        fmt.Println("Carne nao encontrado")
    } else {
        fmt.Printf("Erro: %d\n", resp.StatusCode)
    }
}

<?php
$carneToken = 'TOKEN_DO_CARNE';
$url = "https://sandbox.boletocloud.com/api/v1/carnes/$carneToken";

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

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

if ($httpCode == 200) {
    file_put_contents("carne.pdf", $response);
    echo "PDF do carne salvo com sucesso!\n";
} elseif ($httpCode == 404) {
    echo "Carne nao encontrado\n";
} else {
    echo "Erro: $httpCode\n";
}
?>

import requests
from requests.auth import HTTPBasicAuth

carne_token = 'TOKEN_DO_CARNE'

response = requests.get(
    f'https://sandbox.boletocloud.com/api/v1/carnes/{carne_token}',
    auth=HTTPBasicAuth('api-key_SUA-API-KEY', 'token')
)

if response.status_code == 200:
    with open('carne.pdf', 'wb') as f:
        f.write(response.content)
    print('PDF do carne salvo com sucesso!')
elif response.status_code == 404:
    print('Carne nao encontrado')
else:
    print(f'Erro: {response.status_code}')

require 'net/http'
require 'uri'

carne_token = 'TOKEN_DO_CARNE'
uri = URI("https://sandbox.boletocloud.com/api/v1/carnes/#{carne_token}")

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)

  case response.code
  when '200'
    File.write('carne.pdf', response.body)
    puts 'PDF do carne salvo com sucesso!'
  when '404'
    puts 'Carne nao encontrado'
  else
    puts "Erro: #{response.code}"
  end
end

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

(let [carne-token "TOKEN_DO_CARNE"
      response (client/get
                (str "https://sandbox.boletocloud.com/api/v1/carnes/"
                     carne-token)
                {:basic-auth ["api-key_SUA-API-KEY" "token"]
                 :as :byte-array
                 :throw-exceptions false})]
  (case (:status response)
    200 (do
          (clojure.java.io/copy (:body response)
                                (clojure.java.io/file "carne.pdf"))
          (println "PDF do carne salvo com sucesso!"))
    404 (println "Carne nao encontrado")
    (println "Erro:" (:status response))))

Boletos Individuais

Além do PDF consolidado, você pode acessar cada boleto individualmente usando o token retornado na criação:

Operação	Endpoint	Descrição
Segunda via	`GET /boletos/{token}`	PDF de um boleto específico
Status do registro	`GET /boletos/{token}/registro`	Verificar se foi registrado
Baixa	`PUT /boletos/{token}/baixa`	Cancelar boleto específico

Veja Também

Criar Carnê Primeira etapa: criar o carnê e receber os tokens

Buscar Boleto Individual Obter PDF de um boleto específico

Status do Registro Verificar se boleto foi registrado no banco

Criar em Lote Alternativa com 1 boleto por página

Anterior
Criar (POST) Próximo
Visão Geral