Visão Geral

Olá! Seja bem-vindo à página da documentação de referência da API Boleto Cloud.

ATENÇÃO! Este conteúdo é direcionado para desenvolvedores, programadores e pessoas da área de sistemas em geral :-) Aqui descrevemos como a Interface de Programação de Aplicativos (API) funciona.

Através da API Boleto Cloud você poderá integrar seu site, aplicativo, sistema, etc; independente da linguagem de programação. No momento não disponibilizamos nenhuma biblioteca específica para nenhuma linguagem de programação, entretanto é recomendado que siga os exemplos, através deles você provavelmente estará apto a adaptá-los a sua linguagem de programação de preferência.

A versão atual da plataforma Boleto Cloud conta com uma API baseada no protocolo HTTP seguindo em essência o estilo REST, onde o acesso a leitura e escrita de dados é disponibilizado de forma programática através de chamadas utilizando o protocolo HTTP. Dessa forma, para API não há distinção quanto a natureza das chamadas, seja ela originada de um aplicativo mobile, desktop ou um servidor; todas as chamadas são igualmente atendidas pela API.

Visão Geral

Com a API você poderá:

  • Criar boletos;
  • Enviar boletos por email;
  • Disponibilizar a segunda via online.

NOTA: No momento você poderá apenas criar boletos, acessar boletos criados e disponibilizar a segunda via online através da Plataforma. Estamos disponibilizando essa primeira versão da API para que você possa nos ajudar a desenvolvê-la em função das suas necessidades. Isso quer dizer que as funcionalidades serão adicionadas, e quando adicionadas não serão modificas, o que significa que a API é estável e pode ser utilizada normalmente. Contamos com seu feedback e esperamos que todos os interessados na plataforma colaborem para que essa seja apenas a primeira de muitas funcionalidades.

Protocolo

O protocolo utilizado pela API é de fato HTTPS, porém, toda a semântica relacionada a arquitetura REST é pertinente ao HTTP versão 1.1. Base da implementação leva em consideração sua RFC principal: RFC2616, entretanto, alguns aspectos podem utilizar atualizações como a RFC7231.

URL

Todos os serviços disponibilizados através da API em ambiente de produção, por questões de segurança, são realizados através do protocolo HTTPS, onde a URL base de acesso é https://app.boletocloud.com/api.

Como já dissemos, a API segue o estilo REST e sendo desta maneira, para que fique claro, os serviços são compostos e formados da seguinte forma:

Composição da url de chamadas a api

Onde:

  • Hostname - é o endereço principal dos serviços https://app.boletocloud.com/api/v1/boletos;
  • Versão - é a versão da API/serviço https://app.boletocloud.com/api/v1/boletos;
  • Recurso - é o nome do serviço https://app.boletocloud.com/api/v1/boletos.

Portanto, existem apenas dois endpoints para acessar a API:

  • PRODUÇÃO: https://app.boletocloud.com/api
  • SANDBOX: https://sandbox.boletocloud.com/api

ATENÇÃO: Enquanto sua aplicação estiver em desenvolvimento, você deve utilizar somente o endpoint Sandbox em https://sandbox.boletocloud.com, isso evitará maiores problemas como bloqueio de chamadas, inconsistência de dados e até o bloqueio total da conta na plataforma.

Charset

O Charset padrão utilizado para todas as chamadas à API é o UTF-8, em caso de dúvidas consulte a RFC3629.

Content Type

O tráfego de dados na API, utiliza os formatos FORM, JSON e o PDF, dependendo do serviço consumido. Respectivamente a negociação de conteúdo deve levar em consideração o content type application/x-www-form-urlencoded para input, application/json para retorno de erros e application/pdf para os boletos gerados.

Dados

Para o correto funcionamento do serviço alguns dados são padronizados como:

Tipo Formato Exemplo
Datas "aaaa-mm-dd" "2014-07-01" Todas as datas devem ser informadas seguindo esse padrão.
Valores Monetários "0000.00" "1.83",
"3095.72",
"5200459.37"
Todos os valores devem possuir apenas duas casas decimais, sendo assim no exemplo ao lado: "5200459.37"; que normalmente é representado como R$ 5.200.459,37, não deve conter vírgula e no lugar dela apenas um ponto representa a parte fracionária. Todos os valores, são, por padrão, considerados como valores em Real R$.

Sobre os exemplos

ATENÇÃO: Enquanto sua aplicação estiver em desenvolvimento, você deve utilizar somente o endpoint Sandbox em https://sandbox.boletocloud.com, isso evitará maiores problemas como bloqueio de chamadas, inconsistência de dados e até o bloqueio total da conta na plataforma.

Os exemplos são disponibilizados em três maneiras:

  • Interface Gráfica: onde mostramos um printscreen apenas dos casos mais gerais e em exemplos específicos apenas será preciso adaptar os dados.
  • Linha de Comando: utilizamos como a forma primária de exemplificação, servindo portanto como a especificação do exemplo.
  • Linguagem de Programação: tentamos exemplificar como seria a execução de um dado exemplo em uma linguagem de programação específica.

Interface gráfica - Postman

Caso prefira, é possível executar os exemplos direto do browser, para isso, indicamos o plugin Postman do Google Chrome. Com esse plugin você poderá adaptar os exemplos colocando os valores de parâmetros descritos nos respectivos campos da interface gráfica, exemplo:



Linha de comando - cURL

Utilizaremos o cURL como o principal meio de exemplificação das chamadas a API e para fazer a demonstração da execução dos exemplos, já que é uma ferramenta de linha de comando largamente utilizada e disponível em diversos sistemas operacionais. Você pode utilizar esses exemplos como um guia rápido para ver os serviços em ação e como uma base para adaptar o exemplo para sua linguagem de programação de preferência, caso ainda não tenha um exemplo para essa linguagem.

Linguagens de Programação

No momento não disponibilizamos nenhuma biblioteca, DLL ou SDK específico para uma linguagem de programação, mas tentamos adaptar os exemplos em algumas linguagens de forma a utilizar as APIs, libs, framworks, etc, providos por cada linguagem e caso deseje, você pode adaptar os exemplos da forma que quiser, seja utilizando uma outra API ou de uma outra forma.

Java

Para a execução dos exemplos recomendamos as versões mais recentes como Java 7 ou 8, porém com pequenas ou em algumas vezes nenhuma adaptação, é possível executar os exemplos utilizando Java 5. Para realizar chamadas a API utilizamos as versões 2.x da Java API for RESTful Services (JAX-RS) e da sua implementação de referência Jersey, também em versões 2.x.

PHP

Para a execução dos exemplos recomendamos as versões mais recentes como 5.4.x e superiores, porém é possível executar todos os exemplos em versões anteriores desde que a biblioteca cURL esteja presente no ambiente de execução.

Outras Linguagens

Estamos trabalhando no aprimoramento da API e da Plataforma como um todo, com isso, ainda não foi possível elaborar exemplos em outras linguagens, mas achamos que você pode encontrar o caminho para exemplos em sua linguagem de preferência tendo como base os exemplos em cURL e através de uma breve pesquisa no google por rest client "linguagem", por exemplo: "rest client ruby", "rest client python", "rest client c#", "rest client delphi", etc. Já que o estilo REST e as tecnologias envolvidas atualmente são amplamente difundidos, será uma tarefa simples :-)

Caso queira colaborar com exemplos em alguma linguagem, pode entrar em contato conosco, a comunidade Boleto Cloud ficará feliz com sua colaboração :-)

Dados Gerados - Ambiente Sandbox

Dados gerados pela API podem ser visualizados via interface gráfica no ambiente Sandbox, entretanto os dados são apagados de tempos e tempos, portanto não conte com uma vida prolongada dos dados gerados, exceto os dados de acesso referente a conta do usuário.

Acesso

ATENÇÃO: Enquanto sua aplicação estiver em desenvolvimento, você deve utilizar somente o endpoint Sandbox em https://sandbox.boletocloud.com, isso evitará maiores problemas como bloqueio de chamadas, inconsistência de dados e até o bloqueio total da conta na plataforma.

Para acessar a API você precisa ter uma conta cadastrada na Plataforma Boleto Cloud, não se preocupe, o plano free já fornece o acesse a API.

Para evitar maiores problemas e evitar de ter a conta Boleto Cloud Bloqueada por uso incorreto da API, recomendamos fortemente que primeiro crie seu acesso no ambiente Sandbox em https://sandbox.boletocloud.com, para executar os testes com a API ou outros testes que deseje realizar.

Criando o Token de Acesso - Sandbox

Crie sua conta no ambiente Sandbox em https://sandbox.boletocloud.com ou caso já tenha criado, efetue o login, você deve visualizar algo como a imagem abaixo:

Ambiente sandbox após login

Dentro da área de dados do usuário, você terá disponível o botão para gerar o token da API, como na imagem abaixo:

Área do usuário no ambiente sandbox

Com o seu token criado, ele deverá ser algo similar á o que disponibilizamos nos exemplos aqui na documentação: api-key_vJxqRj_8ZIu7850rCC3R-lDRcedJ40l4KuMlLH-Kjxs. Com o token em mãos agora você poderá utilizá-lo para realizar a autenticação na API.

NOTA:Para executar os exemplos já fornecemos um token de teste para você, com ele você poderá executar os exemplos diretamente na linha de comando ou interface gráfica.

Criando o Token de Acesso - PRODUÇÃO

Para criar o token de acesso a API no ambiente de produção os passos são os mesmos que mostramos aqui para o ambiente sandbox. Porém, é fortemente recomendável que você utilize o ambiente de produção após experimentar, testar e homologar sua aplicação utilizando o ambiente sandbox, caso contrário, inconsistências e erros gerados em produção podem levar ao bloqueio total da sua conta Boleto Cloud.

Autenticação

ATENÇÃO: Enquanto sua aplicação estiver em desenvolvimento, você deve utilizar somente o endpoint Sandbox em https://sandbox.boletocloud.com, isso evitará maiores problemas como bloqueio de chamadas, inconsistência de dados e até o bloqueio total da conta na plataforma.

A autenticação é realizada através do uso da API Key (Token da API) do usuário cadastrado na plataforma, onde toda chamada a API deve informar o token de acesso do usuário. Lembrando que o token de acesso é obtido através dos dados da sua conta como já explicamos anteriormente.

Sua API Key é única e secreta, ela possui os privilégios atribuídos a sua conta, portanto, certifique-se de mantê-la secreta. Caso julgue necessário você poderá gerar uma nova através da sua conta Boleto Cloud.

Como já dissemos antes, todas as requisições são feitas via HTTPS (exceto em modo teste). A autenticação de fato é feita utilizando HTTP Basic Auth. Para consumir qualquer serviço da API, todas e quaisquer requisições devem realizar esse tipo de autenticação.

A autenticação básica fornecida pelo protocolo HTTP é bem simples, consiste em passar o header HTTP Authorization obedecendo ao seguinte algoritmo:


"Authorization: Basic" + Base64("{#usuário}:{#senha}")

Por exemplo, executando esse algoritmo para o usuário "api" e senha "basic-key-test" teríamos o seguinte Header HTTP:


Authorization: Basic YXBpOmJhc2ljLWtleS10ZXN0

Para realizar a autenticação na API Boleto Cloud é preciso informar o campo usuário com a API Key da sua conta, já no campo password, apenas por padronização e conveniência (certas implementações podem exigir que não seja vazio), coloque a palavra "token".

O algoritmo anterior portanto seria:


"Authorization: Basic" + Base64("api-key_123:token")

Lembrando que a autenticação deve ser feita para cada requisição, seguem alguns exemplos de uma requisição do tipo GET de um boleto:

Exemplo - Interface Gráfica

Para realizar a requisição com autenticação via Postman, faça como na imagem abaixo:

  • Defina a url da sandbox para o serviço e o token (neste caso o token é 1) /boletos/1;
  • Defina o Header Authorization na aba com este nome e escolha o tipo Basic Auth;
  • Defina então o username como api-key_123 e o password como token;
  • Em seguida clique no botão amarelo Update Request, feito isso o Authorization Header irá aparecer na seção específica com o valor Basic YXBpLWtleV8xMjM6dG9rZW4=
  • Por fim, selecione no botão azul Send, para enviar os dados e visualizar o resultado na seção Body.

Para saber mais sobre o uso do postman, veja a seção sobre os exemplos.

Exemplo - Linha de Comando

Para executar uma chamada GET com autenticação utilizando o cURL sugerimos os seguintes parâmetros:

  • -v Indicando que a execução deve ser verbosa e os detalhes dela devem ser exibidos na tela;
  • -u Informando o usuário e também senha, neste caso o formato é user:password, ou seja: api-key_123:token;
  • URL informando diretamente sem definir um parâmetro formal, ou seja: https://sandbox.boletocloud.com/api/v1/boletos/1.

$ curl -v -u api-key_123:token https://sandbox.boletocloud.com/api/v1/boletos/1

Para saber mais sobre o uso do cURL, veja a seção sobre os exemplos.

Exemplo - Código Java

Para executar uma chamada GET com autenticação em Java utilizamos a API da linguagem própria para serviços REST, a (JAX-RS):


import static javax.ws.rs.core.MediaType.WILDCARD;

import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.core.Response;

import org.glassfish.jersey.client.authentication.HttpAuthenticationFeature;

/**
 * Exemplo de autenticação na busca de um boleto utilizando o método HTTP GET.
 * Como o token de acesso fornecido não existe o um erro 401 (Não Autorizado) é retornado.
 * 
 *
 *	Para executar o exemplo é preciso:
 *  # Java 6 ou superior
 *  # JAX-RS 2.x ou superior
 *  # Jersey Client 2.x ou superior
 */
public class ApiAutenticar {

	public static void main(String[] args) throws Exception {
		/*
		 * Requisição para buscar boleto
		 */
		Response response = ClientBuilder
				.newClient()
				.target("https://sandbox.boletocloud.com/api/v1/boletos")
				.path("/1")//Token do boleto inexistente
				.register(
						//Define o tipo de autenticação HTTP Basic 
						HttpAuthenticationFeature.basic(
								"api-key_123",//Substitua pelo seu token de teste e veja outro tipo de erro.
								"token"
						)
				)
				.request(WILDCARD)//Aceita qualquer resposta
				.get();
		/*
		 * Dados da resposta
		 */
		System.out.println("HTTP Status Code: "+response.getStatus());
		System.out.println("Boleto Cloud Version: "+response.getHeaderString("X-BoletoCloud-Version"));
		System.err.println("Erro retornado em json: "+response.readEntity(String.class));
		//Para saber mais sobre tratamento de erros veja a seção Status & Erros
	}
}

Para saber mais sobre uso do Java, veja a seção sobre os exemplos.

Exemplo - Código PHP

Para executar uma chamada GET com autenticação em PHP utilizamos a biblioteca cURL da seguinte forma:


<?php

/*
 * Exemplo de autenticação na busca de um boleto utilizando o método HTTP GET.
 * Como o token de acesso fornecido não existe o um erro 401 (Não Autorizado) é retornado.
 *
 * cURL - http://php.net/manual/pt_BR/book.curl.php
**/

//URL do serviço /boleto + /token
$url = 'https://sandbox.boletocloud.com/api/v1/boletos/1';

// curl - http://php.net/manual/pt_BR/book.curl.php
#Inicializa a sessão
$ch = curl_init(); 

//Opções relacionadas a requisição: http://php.net/manual/pt_BR/function.curl-setopt.php
#Define a url
curl_setopt($ch, CURLOPT_URL, $url);
#Define o tipo de autenticação HTTP Basic 
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
#Define o API Token para realizar o acesso ao serviço
curl_setopt($ch, CURLOPT_USERPWD, "api-key_123:token");
#True para enviar o conteúdo do arquivo direto para o navegador
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
#Define que os headers estarão na resposta
curl_setopt($ch, CURLOPT_HEADER, true);

//Necessário para requisição HTTPS
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);

#Executa a chamada
$response = curl_exec($ch);

#Principais meta-dados da resposta
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE); 
$header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);

#Encerra a sessão
curl_close($ch);

#Separando header e body contidos na resposta
$header = substr($response, 0, $header_size);
$body = substr($response, $header_size);
$header_array = explode("\r\n", $header);

#Principais headers deste exemplo
$boleto_cloud_version = '';

foreach($header_array as $h) {
    if(preg_match('/X-BoletoCloud-Version:/i', $h)) {
        $boleto_cloud_version = $h;
    }
}

#Visualizando erro no navegador
echo '<p> Status Code: '.$http_code.'</p>';
echo '<p>'.$boleto_cloud_version.'</p>'; #Header X-BoletoCloud-Version
echo '<pre>'.$body.'</pre>'; #Erro JSON como resposta:

/*
 * Para saber mais sobre tratamento de erros veja a seção Status & Erros 
**/

?>

Para saber mais sobre uso do PHP, veja a seção sobre os exemplos.

Se a API Key existisse e se o token do boleto fosse o de um boleto também existente, um PDF seria retornado, mas como se trata de um API Key inexistente, a resposta da API define que a requisição não é autorizada:


HTTP/1.1 401 Unauthorized
Server: Apache-Coyote/1.1
X-BoletoCloud-Version: 0.4.1
Content-Type: application/json;charset=utf-8
Content-Length: 214
Date: Mon, 07 Jul 2014 23:07:10 GMT
{
  "erro": {
    "status": 401,
    "tipo": "autenticacao",
    "causas": [
      {
        "codigo": "2CD228EA",
        "mensagem": "O token de acesso fornecido (api-key_123) está incorreto ou inválido.",
        "suporte": "http://boleto.cloud/app/dev/api"
      }
    ]
  }
}

Para executar os exemplos acima, não é preciso que já tenha o seu token de acesso de teste, mas caso esteja curioso de como o exemplo se comporta com o seu token, veja como criá-lo na seção de acesso. Caso esteja curioso a respeito do tratamento de erros como esse, veja a próxima seção sobre status e erros.

Status e Erros

ATENÇÃO: Enquanto sua aplicação estiver em desenvolvimento, você deve utilizar somente o endpoint Sandbox em https://sandbox.boletocloud.com, isso evitará maiores problemas como bloqueio de chamadas, inconsistência de dados e até o bloqueio total da conta na plataforma.

Uma das vantagens da abordagem REST é a padronização adquirida com o protocolo HTTP, que por sua vez, traz um conjunto de códigos de status definido. Utilizamos desse conjunto de status retornado em cada requisição para indicar situações de sucesso ou falha dos serviços e detalharmos o erro. Caso exista algum erro, o mesmo será retornado no corpo resposta em formato JSON.

Por convenção, os status são divididos em "famílias":

  • 1xx: Info
  • 2xx: Sucesso
  • 3xx: Redirecionamento
  • 4xx: Erro do cliente
  • 5xx: Erro do servidor

A seguir alguns exemplos de status retornados pela API:

100 Continue
Continue a requisição, parte do request foi recebido.
200 Ok
Requisição OK, tudo ocorreu como esperado.
300 Not Modified
O recurso requisitado não foi modificado desde da última solicitação.
400 Bad Request
A requisição não foi atendida por parâmetro obrigatório não informado ou inválido.
500 Internal Server Error
A requisição não foi atendida por algum erro ocorrido no servidor.

Como dito anteriormente, em caso de falha de um dado serviço, o erro poderá ser detalhado no corpo da mensagem de resposta em formato JSON. Você deve ter notado a presença do JSON na mensagem de erro da seção de autenticação, a mensagem exibida foi:


{
   "erro": {
      "status": 401,
      "tipo": "autenticacao",
      "causas": [
         {
            "codigo": "2CD228EA",
            "mensagem": "O token de acesso fornecido (api-key_123) está incorreto ou inválido.",
            "suporte": "http://boleto.cloud/app/dev/api"
         }
      ]
   }
}

Na API as mensagens de erros são detalhadas da seguinte forma:

Objeto: erro, nome raiz: "erro"
Nome da propriedade Tipo Exemplo
status integer 401 Representa o mesmo que o staus code HTTP.
tipo string "autenticacao" Representa o tipo do erro que tem mais significado do ponto de vista da API.
causas array [{},{},{}] Contém as várias causas de um erro e uma possível solução pra o erro.
Objeto: causa, nome raiz: "causas"
Nome da propriedade Tipo Exemplo
codigo string "2CD228EA" Representa o erro classificado e atribuído pela API.
mensagem string "Token inválido." Mensagem identificando a causa ou uma das causas responsáveis pelo erro.
suporte string "http://boleto.cloud/app/dev/api" Link ou mensagem para ajudar a solucionar o erro.

Um exemplo de um erro com múltiplas mensagem retornado pela API:


{
   "erro": {
      "status": 400,
      "tipo": "requisicao",
      "causas": [
         {
            "codigo": "CEBDAF6F",
            "mensagem": "Campo (boleto.beneficiario) - O beneficiário do boleto está ausente, mas é obrigatório.",
            "suporte": "http://boleto.cloud/app/dev/api"
         },
         {
            "codigo": "29E52CCD",
            "mensagem": "Campo (boleto.documento) - O número do documento está ausente, mas é obrigatório.",
            "suporte": "http://boleto.cloud/app/dev/api"
         }
      ]
   }
}

Tratamento de Erros

ATENÇÃO: Enquanto sua aplicação estiver em desenvolvimento, você deve utilizar somente o endpoint Sandbox em https://sandbox.boletocloud.com, isso evitará maiores problemas como bloqueio de chamadas, inconsistência de dados e até o bloqueio total da conta na plataforma.

Agora que você já conhece a estrutura de uma mensagem de erro você já deve ter percebido que é bastante simples fazer o tratamento de um erro quando ele ocorre. Para tratar um erro ocorrido você pode primeiro categorizá-lo pelo status code (status) e em seguida detalhar o erro através do processamento das causas (causas) e cada causa pode possui um código (codigo) que é fixo e também pode ser identificado para tratar uma causa específica dentro do seu sistema.

Exemplo - Interface Gráfica

Aconselhamos utilizar o Postman apenas para depurar erros, assim é possível ver os erros numa interface amigável e testar valores para as situações em que o erro ocorre.

Para saber mais sobre o uso do postman, veja a seção sobre os exemplos.

Exemplo - Linha de Comando

Apesar de não ser tão prático, é possível também fazer o tratamento de erros na abordagem da solução abaixo utilizando cURL em bash em um ambiente unix.


#/bin/bash

#Tenta baixar o arquivo pdf e no final do arquivo adiciona o código de status da requisição
curl -u "api-key_vJxqRj_8ZIu7850rCC3R-lDRcedJ40l4KuMlLH-Kjxs=:token" \
--silent \
--write-out \\n%{http_code}  \
--output - "https://sandbox.boletocloud.com/api/v1/boletos/ACin7NWnpRVC-dpjKqu4b5LVR7T1vcbE9UmhAm-Qa9g=" > result-file

#Lê o status code na última linha
status_code=$(tail -n 1 result-file)

if [ $status_code = 200 ]; then #Se retornou com sucesso escreve arquivo em pdf sem status code

	lines_with_status_code=$(wc -l result-file | tr -dc '0-9')
	
	lines_pdf=$((lines_with_status_code-1)) 
	
	head result-file -n $lines_pdf > boleto.pdf

	echo 'Boleto pdf baixado com sucesso.'

	exit 0

else #Caso contrário, mostra o erro na tela

	echo 'Erro - Status Code: ${status_code}'

	cat result-file

	exit 1
fi

Para saber mais sobre o uso do cURL, veja a seção sobre os exemplos.

Exemplo - Código Java

Para fazer o tratamento de erros em Java utilizamos a API da linguagem própria para serviços REST, a (JAX-RS) e processamos o status code junto com os dados da mensagem de erro em JSON:


import static java.nio.file.StandardCopyOption.REPLACE_EXISTING;
import static javax.ws.rs.core.MediaType.WILDCARD;
import static javax.ws.rs.core.Response.Status.BAD_REQUEST;
import static javax.ws.rs.core.Response.Status.INTERNAL_SERVER_ERROR;
import static javax.ws.rs.core.Response.Status.OK;

import java.io.InputStream;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Iterator;

import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.core.Response;

import org.glassfish.jersey.client.authentication.HttpAuthenticationFeature;

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;

/**
 * Exemplo de busca de um boleto já existente utilizando o método HTTP GET.
 * Após obter o PDF do boleto o arquivo é aberto utilizando o leitor de PDF do sistema operacional.
 *
 *	Para executar o exemplo é preciso:
 *  # Java 6 ou superior
 *  # JAX-RS 2.x ou superior
 *  # Jersey Client 2.x ou superior
 */
public class TratarErros {

	public static void main(String[] args) throws Exception {
		final String tokenInexistente = "XPTO";
		/*
		 * Requisição para buscar boleto
		 */
		Response response = ClientBuilder
				.newClient()
				.target("https://sandbox.boletocloud.com/api/v1/boletos")
				.path("/"+tokenInexistente)
				.register(
						//Define o tipo de autenticação HTTP Basic 
						HttpAuthenticationFeature.basic(
								"api-key_vJxqRj_8ZIu7850rCC3R-lDRcedJ40l4KuMlLH-Kjxs=",
								"token"
						)
				)
				.request(WILDCARD)//Aceita qualquer resposta
				.get();
		/*
		 * Identifica se o boleto foi retornado ou houve erro
		 */
		if(response.getStatus() == OK.getStatusCode()){			
		
			//Salva o arquivo do diretório corrente.
			Files.copy(response.readEntity(InputStream.class), Paths.get("arquivo-api-boleto-get-teste.pdf"), REPLACE_EXISTING);

		}else{
			
			System.err.println("Boleto Cloud Version: "+response.getHeaderString("X-BoletoCloud-Version"));

			String entityResponse = response.readEntity(String.class);
			JsonNode jsonNode = new ObjectMapper().readTree(entityResponse);
			
			//Dados errados 400
			if(response.getStatus() == BAD_REQUEST.getStatusCode()){
				//Mostre todas as causas do erro
				Iterator<JsonNode> causas = jsonNode.get("erro").get("causas").elements();
				while(causas.hasNext()){
					JsonNode causa = causas.next();
					System.err.println("Código: "+causa.get("codigo").asText());
					System.err.println("Mensagem: "+causa.get("mensagem").asText());
				}
			}
			
			//Erro do tipo 500
			if(response.getStatus() == INTERNAL_SERVER_ERROR.getStatusCode()){
				//Mostre a primeira causa do erro
				System.err.println(jsonNode.get("erro").get("causas").elements().next());
			}
		}
	}
}

Para saber mais sobre uso do Java, veja a seção sobre os exemplos.

Exemplo - Código PHP

Para fazer o tratamento de erros em PHP utilizamos a biblioteca cURL e processamos o status code junto com os dados da mensagem de erro em JSON:


<?php

/*
 * Exemplo de tratamento de erros em função do tipo e da causa do erro.
 *
 * cURL - http://php.net/manual/pt_BR/book.curl.php
**/

//URL do serviço /boleto + /token
$url = 'https://sandbox.boletocloud.com/api/v1/boletos/XPTO';

// curl - http://php.net/manual/pt_BR/book.curl.php
#Inicializa a sessão
$ch = curl_init(); 

//Opções relacionadas a requisição: http://php.net/manual/pt_BR/function.curl-setopt.php
#Define a url
curl_setopt($ch, CURLOPT_URL, $url);
#Define o tipo de autenticação HTTP Basic 
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
#Define o API Token para realizar o acesso ao serviço
curl_setopt($ch, CURLOPT_USERPWD, "api-key_vJxqRj_8ZIu7850rCC3R-lDRcedJ40l4KuMlLH-Kjxs=:token");
#True para enviar o conteúdo do arquivo direto para o navegador
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
#Define que os headers estarão na resposta
curl_setopt($ch, CURLOPT_HEADER, true);

//Necessário para requisição HTTPS
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);

#Executa a chamada
$response = curl_exec($ch);

#Principais meta-dados da resposta
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE); 
$header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);

#Encerra a sessão
curl_close($ch);

#Separando header e body contidos na resposta
$header = substr($response, 0, $header_size);
$body = substr($response, $header_size);
$header_array = explode("\r\n", $header);

#Principais headers deste exemplo
$boleto_cloud_version = '';

foreach($header_array as $h) {
    if(preg_match('/X-BoletoCloud-Version:/i', $h)) {
        $boleto_cloud_version = $h;
    }
}

#Processando sucesso ou falha

if($http_code == 200){#OK - SUCESSO
	
	#Enviando boleto como resposta:
	header('Content-type: application/pdf');
	header('Content-Disposition: inline; filename=arquivo-api-boleto-get-teste.pdf');
	echo $body; #Visualização no navegador

}else{//ERRO

	echo $boleto_cloud_version.'<br />';

	$erro_array = json_decode($body, true);
	$causas_array = $erro_array['erro']['causas'];

	if($http_code == 400){//BAD REQUEST
		
		#Mostre todas as causas do erro
		foreach ($causas_array as $causa) {
			echo $causa['codigo'].' - '.$causa['mensagem'].'<br />';
		}
	}

	if($http_code == 500){//INTERNAL SERVER ERROR
		#Mostre a primeira causa do erro
		echo $causas_array[0]['codigo'].' - '.$causas_array[0]['mensagem'];
	}
}

?>

Para saber mais sobre uso do PHP, veja a seção sobre os exemplos.

Boletos

O boleto é o serviço principal da plataforma, sendo assim, o endpoint para os boletos não poderia ser outro: https://sandbox.boletocloud.com/api/v1/boletos.

FLUXO BÁSICO: a seguir mostramos o caso mais comum de uso da API, que é a criação do boleto na plataforma e obtenção posterior do mesmo.

Visão Geral

Criar (POST)

ATENÇÃO: Enquanto sua aplicação estiver em desenvolvimento, você deve utilizar somente o endpoint Sandbox em https://sandbox.boletocloud.com, isso evitará maiores problemas como bloqueio de chamadas, inconsistência de dados e até o bloqueio total da conta na plataforma.

Todos os boletos são criados na API através do método POST. Os boletos são identificados de forma única na plataforma, seja pelo Token, que é retornado como HEADER no retorno da requisição POST ou através do Número Identificador Bancário. Caso em uma requisição seja enviado um boleto com um Número Identificador Bancário já existente, então um erro 409 (Conflito) será retornado e o boleto não será criado. Caso não exista nenhuma inconsistência na requisição, o código 201 (Criado) será retornado juntamente com o PDF do boleto.

INPUT REQUEST

Client

Request

API Boleto Cloud

URL /boletos

Header Authorization: Basic

Header Content-Type: application/x-www-form-urlencoded; charset=utf-8

Body Dados do boleto

OUTPUT RESPONSE

API Boleto Cloud

Response

Client

Header X-BoletoCloud-Version


HTTP Status Code 201 - Criado

Header Content-Type: application/pdf; charset=UTF-8

Header Location: /api/v1/boletos/{TOKEN}

Header X-BoletoCloud-Token: {TOKEN}

Body Boleto PDF


HTTP Status Code XXX - Falha

Header Content-Type: application/json; charset=UTF-8

Body Erro JSON

Requisição

Para se criar um boleto padrão e obter seu retorno em formato PDF, tudo que você precisa fazer é realizar uma chamada POST a URL https://sandbox.boletocloud.com/api/v1/boletos e informar os dados do boleto.

NOTA: O boleto com os dados exibidos nos exemplos já foi criado e já existe no ambiente sandbox, então se você tentar executar o exemplo com os mesmos dados receberá uma mensagem de erro informando que o boleto com um mesmo número já existe, que no caso é o número que está sendo informado no parâmetro boleto.numero="12345678901-P".

Para criar um boleto como no exemplo, basta criar seu token de acesso no ambiente sandbox como mostramos aqui na seção de acesso.

Veja alguns exemplos:

Exemplo - Interface Gráfica

Para criar o boleto e obter o arquivo PDF via Postman, faça como na imagem abaixo:

  • Defina a url da sandbox para o serviço /boletos;
  • Defina o Header Authorization na aba com este nome e escolha o tipo Basic Auth, caso tenha dúvidas veja um exemplo de autenticação;
  • Na aba Body escolha o tipo x-www-form-urlencoded;
  • Na aba Body defina os dados da requisição:
    
    boleto.conta.banco="237" 
    boleto.conta.agencia="1234-5" 
    boleto.conta.numero="123456-0" 
    boleto.conta.carteira="12" 
    boleto.beneficiario.nome="DevAware Solutions" 
    boleto.beneficiario.cprf="15.719.277/0001-46" 
    boleto.beneficiario.endereco.cep="59020-000" 
    boleto.beneficiario.endereco.uf="RN" 
    boleto.beneficiario.endereco.localidade="Natal" 
    boleto.beneficiario.endereco.bairro="Petrópolis" 
    boleto.beneficiario.endereco.logradouro="Avenida Hermes da Fonseca" 
    boleto.beneficiario.endereco.numero="384" 
    boleto.beneficiario.endereco.complemento="Sala 2A, segundo andar" 
    boleto.emissao="2014-07-11" 
    boleto.vencimento="2020-05-30" 
    boleto.documento="EX1" 
    boleto.numero="12345678901-P" 
    boleto.titulo="DM" 
    boleto.valor="1250.43" 
    boleto.pagador.nome="Alberto Santos Dumont" 
    boleto.pagador.cprf="111.111.111-11" 
    boleto.pagador.endereco.cep="36240-000" 
    boleto.pagador.endereco.uf="MG" 
    boleto.pagador.endereco.localidade="Santos Dumont" 
    boleto.pagador.endereco.bairro="Casa Natal" 
    boleto.pagador.endereco.logradouro="BR-499" 
    boleto.pagador.endereco.numero="s/n" 
    boleto.pagador.endereco.complemento="Sítio - Subindo a serra da Mantiqueira" 
    boleto.instrucao="Atenção! NÃO RECEBER ESTE BOLETO." 
    boleto.instrucao="Este é apenas um teste utilizando a API Boleto Cloud" 
    boleto.instrucao="Mais info em http://boleto.cloud/app/dev/api"
    
    
  • Por fim, selecione no botão azul Send a opção Send and download para enviar os dados e já realizar o download do arquivo PDF.

Para saber mais sobre o uso do postman, veja a seção sobre os exemplos.

Exemplo - Linha de Comando

Para executar uma chamada POST utilizando o cURL sugerimos os seguintes parâmetros:

  • -v Indicando que a execução deve ser verbosa e os detalhes dela devem ser exibidos na tela;
  • -H Indicando que um parâmetro Header está sendo informado;
  • -X Informando qual o método HTTP utilizado, no caso um POST;
  • -u Informando o usuário utilizado na autenticação, como já explicado na seção autenticação;
  • -d Definindo os campos de informação da requisição, no formato chave-valor;
  • -o Definindo que o arquivo pdf retornado será salvo em um arquivo chamado arquivo-api-boleto-post-teste.pdf no diretório atual.

curl -v "https://sandbox.boletocloud.com/api/v1/boletos" \
-H "Content-Type: application/x-www-form-urlencoded; charset=utf-8" \
-X "POST" \
-u "api-key_vJxqRj_8ZIu7850rCC3R-lDRcedJ40l4KuMlLH-Kjxs=:token" \
-d boleto.conta.banco="237" \
-d boleto.conta.agencia="1234-5" \
-d boleto.conta.numero="123456-0" \
-d boleto.conta.carteira="12" \
-d boleto.beneficiario.nome="DevAware Solutions" \
-d boleto.beneficiario.cprf="15.719.277/0001-46" \
-d boleto.beneficiario.endereco.cep="59020-000" \
-d boleto.beneficiario.endereco.uf="RN" \
-d boleto.beneficiario.endereco.localidade="Natal" \
-d boleto.beneficiario.endereco.bairro="Petrópolis" \
-d boleto.beneficiario.endereco.logradouro="Avenida Hermes da Fonseca" \
-d boleto.beneficiario.endereco.numero="384" \
-d boleto.beneficiario.endereco.complemento="Sala 2A, segundo andar" \
-d boleto.emissao="2014-07-11" \
-d boleto.vencimento="2020-05-30" \
-d boleto.documento="EX1" \
-d boleto.numero="12345678901-P" \
-d boleto.titulo="DM" \
-d boleto.valor="1250.43" \
-d boleto.pagador.nome="Alberto Santos Dumont" \
-d boleto.pagador.cprf="111.111.111-11" \
-d boleto.pagador.endereco.cep="36240-000" \
-d boleto.pagador.endereco.uf="MG" \
-d boleto.pagador.endereco.localidade="Santos Dumont" \
-d boleto.pagador.endereco.bairro="Casa Natal" \
-d boleto.pagador.endereco.logradouro="BR-499" \
-d boleto.pagador.endereco.numero="s/n" \
-d boleto.pagador.endereco.complemento="Sítio - Subindo a serra da Mantiqueira" \
-d boleto.instrucao="Atenção! NÃO RECEBER ESTE BOLETO." \
-d boleto.instrucao="Este é apenas um teste utilizando a API Boleto Cloud" \
-d boleto.instrucao="Mais info em http://boleto.cloud/app/dev/api" \
-o arquivo-api-boleto-post-teste.pdf

Para saber mais sobre o uso do cURL, veja a seção sobre os exemplos.

Exemplo - Código Java

Para executar uma chamada POST em Java utilizamos a API da linguagem própria para serviços REST, a (JAX-RS):


import static java.nio.file.StandardCopyOption.REPLACE_EXISTING;
import static javax.ws.rs.core.MediaType.WILDCARD;
import static javax.ws.rs.core.Response.Status.CREATED;

import java.io.InputStream;
import java.nio.file.Files;
import java.nio.file.Paths;

import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.core.Form;
import javax.ws.rs.core.Response;

import org.glassfish.jersey.client.authentication.HttpAuthenticationFeature;

/**
 * Exemplo de criação de um boleto inexistente utilizando o método HTTP POST.
 * Após enviar os dados e obter o PDF do boleto como resposta, o arquivo é
 * aberto utilizando o leitor de PDF do sistema operacional.
 *
 * Para executar o exemplo é preciso: # Java 6 ou superior #JAX-RS 2.x ou
 * superior # Jersey Client 2.x ou superior
 */
public class CriarBoleto {

	public static void main(String[] args) throws Exception {
		/*
		 * Dados para criação do boleto
		 */
		Form formData = new Form();
		formData.param("boleto.conta.banco","237");
		formData.param("boleto.conta.agencia","1234-5");
		formData.param("boleto.conta.numero","123456-0");
		formData.param("boleto.conta.carteira","12");
		formData.param("boleto.beneficiario.nome","DevAware Solutions");
		formData.param("boleto.beneficiario.cprf","15.719.277/0001-46");
		formData.param("boleto.beneficiario.endereco.cep","59020-000");
		formData.param("boleto.beneficiario.endereco.uf","RN");
		formData.param("boleto.beneficiario.endereco.localidade","Natal");
		formData.param("boleto.beneficiario.endereco.bairro","Petrópolis");
		formData.param("boleto.beneficiario.endereco.logradouro","Avenida Hermes da Fonseca");
		formData.param("boleto.beneficiario.endereco.numero","384");
		formData.param("boleto.beneficiario.endereco.complemento","Sala 2A, segundo andar");
		formData.param("boleto.emissao","2014-07-11");
		formData.param("boleto.vencimento","2020-05-30");
		formData.param("boleto.documento","EX1");
		formData.param("boleto.numero","12345678901-P");
		formData.param("boleto.titulo","DM");
		formData.param("boleto.valor","1250.43");
		formData.param("boleto.pagador.nome","Alberto Santos Dumont");
		formData.param("boleto.pagador.cprf","111.111.111-11");
		formData.param("boleto.pagador.endereco.cep","36240-000");
		formData.param("boleto.pagador.endereco.uf","MG");
		formData.param("boleto.pagador.endereco.localidade","Santos Dumont");
		formData.param("boleto.pagador.endereco.bairro","Casa Natal");
		formData.param("boleto.pagador.endereco.logradouro","BR-499");
		formData.param("boleto.pagador.endereco.numero","s/n");
		formData.param("boleto.pagador.endereco.complemento","Sítio - Subindo a serra da Mantiqueira");
		formData.param("boleto.instrucao","Atenção! NÃO RECEBER ESTE BOLETO.");
		formData.param("boleto.instrucao","Este é apenas um teste utilizando a API Boleto Cloud");
		formData.param("boleto.instrucao","Mais info em http://boleto.cloud/app/dev/api");
		/*
		 * Requisição para criação do boleto
		 */
		Response response = ClientBuilder
				.newClient()
				.target("https://sandbox.boletocloud.com/api/v1")
				.path("/boletos")
				.register(
						//Define o tipo de autenticação HTTP Basic 
						HttpAuthenticationFeature.basic(
								"api-key_vJxqRj_8ZIu7850rCC3R-lDRcedJ40l4KuMlLH-Kjxs=",
								"token"
						)
				)
				.request(WILDCARD)//Aceita qualquer resposta
				.post(Entity.form(formData));
		/*
		 * Dados da resposta
		 */
		System.out.println("HTTP Status Code: "+response.getStatus());
		System.out.println("Boleto Cloud Version: "+response.getHeaderString("X-BoletoCloud-Version"));
		System.out.println("Boleto Cloud Token: "+response.getHeaderString("X-BoletoCloud-Token"));
		/*
		 * Identifica se o boleto foi criado ou houve erro
		 */		
		if(response.getStatus() == CREATED.getStatusCode()){
			
			//Salva o arquivo do diretório corrente.
			Files.copy(response.readEntity(InputStream.class), Paths.get("arquivo-api-boleto-post-teste.pdf"), REPLACE_EXISTING);
			
			//Caso tenha leitor pdf no sistema..
			//Abrirá o arquivo PDF utilizando o leitor de PDF do sistema operacional
			//java.awt.Desktop.getDesktop().open(new File("arquivo-api-boleto-post-teste.pdf"));
			
		}else{
			System.err.println("Erro retornado em json: "+response.readEntity(String.class));
		}
		//Para saber mais sobre tratamento de erros veja a seção Status & Erros
	}
}

Para saber mais sobre uso do Java, veja a seção sobre os exemplos.

Exemplo - Código PHP

Para executar uma chamada POST em PHP utilizamos a biblioteca cURL da seguinte forma:


<?php

/*
 * Exemplo de criação de um boleto utilizando o método HTTP POST. e exibe o conteúdo PDF retornado no navegador.
 * Após obter o PDF do boleto o arquivo é enviado como resposta para visualização no navegador.
 *
 * cURL - http://php.net/manual/pt_BR/book.curl.php
**/

#Dados do boleto

$fields = array(
'boleto.conta.banco'=> '237',
'boleto.conta.agencia'=> '1234-5',
'boleto.conta.numero'=> '123456-0',
'boleto.conta.carteira'=> '12',
'boleto.beneficiario.nome'=> 'DevAware Solutions',
'boleto.beneficiario.cprf'=> '15.719.277/0001-46',
'boleto.beneficiario.endereco.cep'=> '59020-000',
'boleto.beneficiario.endereco.uf'=> 'RN',
'boleto.beneficiario.endereco.localidade'=> 'Natal',
'boleto.beneficiario.endereco.bairro'=> 'Petrópolis',
'boleto.beneficiario.endereco.logradouro'=> 'Avenida Hermes da Fonseca',
'boleto.beneficiario.endereco.numero'=> '384',
'boleto.beneficiario.endereco.complemento'=> 'Sala 2A, segundo andar',
'boleto.emissao'=> '2014-07-11',
'boleto.vencimento'=> '2020-05-30',
'boleto.documento'=> 'EX1',
'boleto.numero'=> '12345678901-P',
'boleto.titulo'=> 'DM',
'boleto.valor'=> '1250.43',
'boleto.pagador.nome'=> 'Alberto Santos Dumont',
'boleto.pagador.cprf'=> '111.111.111-11',
'boleto.pagador.endereco.cep'=> '36240-000',
'boleto.pagador.endereco.uf'=> 'MG',
'boleto.pagador.endereco.localidade'=> 'Santos Dumont',
'boleto.pagador.endereco.bairro'=> 'Casa Natal',
'boleto.pagador.endereco.logradouro'=> 'BR-499',
'boleto.pagador.endereco.numero'=> 's/n',
'boleto.pagador.endereco.complemento'=> 'Sítio - Subindo a serra da Mantiqueira',
'boleto.instrucao'=> array(
							'Atenção! NÃO RECEBER ESTE BOLETO.',
							'Este é apenas um teste utilizando a API Boleto Cloud',
							'Mais info em http://boleto.cloud/app/dev/api'
					)
);

#Aplicando formato de formulário

$fields_string = '';

foreach($fields as $key=>$value) {
	if(is_array($value)){
		foreach($value as $v){
			$fields_string .= urlencode($key).'='.urlencode($v).'&';
		}
	}else{
		$fields_string .= urlencode($key).'='.urlencode($value).'&';	
	}
}

$data = rtrim($fields_string, '&');

#Definindo conteúdo da requisição e tipos de respostas aceitas
 
#Pode responder com o boleto ou mensagem de erro
$accept_header = 'Accept: application/pdf, application/json';
 
#Estou enviando esse formato de dados
$content_type_header = 'Content-Type: application/x-www-form-urlencoded; charset=utf-8';

$headers = array($accept_header, $content_type_header);

#Configurações do envio

$url = 'https://sandbox.boletocloud.com/api/v1/boletos';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true); 
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_USERPWD, "api-key_vJxqRj_8ZIu7850rCC3R-lDRcedJ40l4KuMlLH-Kjxs=:token"); #API TOKEN
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);# Basic Authorization
curl_setopt($ch, CURLOPT_HEADER, true);#Define que os headers estarão na resposta
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false); #Para uso com https
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); #Para uso com https
 
#Envio

$response = curl_exec($ch);

#Principais meta-dados da resposta

$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE); 
$header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);

#Fechar processo de comunicação
curl_close($ch);

#Processando a resposta

$created = 201; #Constante que indica recurso criado (Boleto Criado)

#Separando header e body na resposta

$header = substr($response, 0, $header_size);
$body = substr($response, $header_size);
$header_array = explode("\r\n", $header);

#Principais headers
$boleto_cloud_version = '';
$boleto_cloud_token = '';
$location = '';

foreach($header_array as $h) {
    if(preg_match('/X-BoletoCloud-Version:/i', $h)) {
        $boleto_cloud_version = $h;
    }
    if(preg_match('/X-BoletoCloud-Token:/i', $h)) {
        $boleto_cloud_token = $h;
    }
    if(preg_match('/Location:/i', $h)) {
        $location = $h;
    }
}

#Processando sucesso ou falha

if($http_code == $created){
	#Versão da plataforma: $boleto_cloud_version 
	#Token do boleto disponibilizado: $boleto_cloud_token
	#Localização do boleto na plataforma: $location
	#Enviando boleto como resposta:
	header('Content-type: application/pdf');
	header('Content-Disposition: inline; filename=arquivo-api-boleto-post-teste.pdf');
	echo $body; #Visualização no navegador
}else{
	#Versão da plataforma: $boleto_cloud_version 
	#Códgio de erro HTTP: $http_code
	#Enviando erro como resposta:
	header('Content-Type: application/json; charset=utf-8');
	echo $body; #Visualização no navegador
}

/*
 * Para saber mais sobre tratamento de erros veja a seção Status & Erros 
**/

?>

Para saber mais sobre uso do PHP, veja a seção sobre os exemplos.

O retorno da requisição, além de ter o PDF no body da resposta, também contém os seguintes Headers:


Content-Type: application/pdf;charset=UTF-8
Location: /api/v1/boletos/ACin7NWnpRVC-dpjKqu4b5LVR7T1vcbE9UmhAm-Qa9g=
X-BoletoCloud-Token: ACin7NWnpRVC-dpjKqu4b5LVR7T1vcbE9UmhAm-Qa9g=
X-BoletoCloud-Version: 0.4.5

Detalhando esses Headers, temos que:

  • Content-Type É referente ao tipo de conteúdo do retorno;
  • Location Informa onde o boleto criado pode ser recuperado (mostramos como fazer isso na seção Buscar)
  • X-BoletoCloud-Token É o identificador do boleto na plataforma.
  • X-BoletoCloud-Version É a versão atual da plataforma em execução.

Além disso, todo boleto gerado também pode ser obtido através do site, na página de segunda via, que nesse caso é:

https://sandbox.boletocloud.com/boleto/2via/ACin7NWnpRVC-dpjKqu4b5LVR7T1vcbE9UmhAm-Qa9g=

Ou seja, basta substituir o token do boleto para obter a segunda via de qualquer boleto em https://sandbox.boletocloud.com/boleto/2via/. Esse é o mesmo princípio utilizado para se Buscar os boletos criados via API utilizando o método GET.

NOTA: Lembre-se que cada chamada utilizando o método POST cria um novo boleto (um novo recurso), portanto, se deseja acessar um boleto já criado você deve utilizar o método GET. Ao tentar criar um boleto com a mesma numeração um erro 409 (Conflito) será retornado. Caso tenha dúvidas de como utilizar a numeração dos boletos veja a próxima seção sobre numeração.

Nova forma de geração de boletos

A forma de gerar os boletos apresentada acima utiliza os dados da conta bancária como parâmetros da requisição e permite que você gere boletos sem precisar ter contas bancárias cadastradas na plataforma. Porém, foi necessário realizar algumas mudanças na API para suportar a nova realidade dos boletos com registros, devido a nova plataforma de cobrança e o fim do boletos sem registro. Além disso, essa mudança também dá suporte ao uso das configurações atribuídas a uma conta bancária, como a personalização do boleto ou a configuração de mensagem padrão, e a geração do arquivo remessa, uma vez que apenas o processamento do arquivo retorno é possível ser utilizado quando o boleto é gerado da forma apresentada até agora.

O que muda nessa nova forma é o como a conta bancária é informada, que agora será através do token de acesso da conta. Para criar o token de uma conta bancária para acesso a API você deve seguir o caminho:

Conta --> Consultar --> Clicar no nome da conta --> Clica em editar dados --> Clica em "Gerar Token" Geração do token da API da conta bancária

Após gerar o token da conta bancária (token com prefixo api-key), você deve agora usá-lo na requisição de criação do boleto. Ao invés de informar todos os dados da conta bancária nos parâmetros, basta agora informar o parâmetro referente ao token. Veja abaixo a diferença:

Forma atual (antiga):
boleto.conta.banco = "104" 
boleto.conta.agencia = "1111"
boleto.conta.convenio = "605789-1"
boleto.conta.carteira = "1"
boleto.conta.registro = "true"
Nova Forma com o token de acesso da conta:
boleto.conta.token="api-key_123-exemplo-do-token-da-conta-bancaria" 

Todos os parâmetros com nome boleto.conta.* devem ser removidos. Agora você deverá informar apenas o parâmetro boleto.conta.token="api-key***"

Todos os parâmetros boleto.beneficario.* também devem ser removidos. Os dados do beneficiário utilizados serão os da conta cadastrada.

Os parâmetros boleto.numero ou boleto.sequencial também não devem ser informados, pois a numeração será controlada pela conta bancária cadastrada.

Atenção! O uso do token do usuário na autenticação permanece da mesma forma. A criação do token da conta bancária em nada modifica a autenticação via API.

Numeração

Como já foi dito, caso ocorra uma tentativa de se criar um boleto com um número de um boleto já existente na plataforma, um erro 409 (Conflito) será retornado. Isso acontece porque os boletos devem ter um Número Identificador Bancário (NIB, definido pelo banco como "Nosso Número") único. Então fica a pergunta, como saber qual número utilizar?

Existem duas formas de se informar a numeração do boleto através da API:

  1. Campo boleto.sequencial
  2. Campo boleto.numero

O campo boleto.sequencial é referente a parte sequencial do NIB, ou seja, ele é usado como base para gerar o NIB. Utilizando esse campo você precisa informar um número sequencial que será utilizado pela API para gerar o NIB, dessa maneira você não precisa se preocupar com o formato e regras de composição do NIB, basta apenas que você informe números únicos e em sequência, por exemplo: 1, 2, 3, 4, 5, etc.

O campo boleto.numero é o NIB já gerado. Provavelmente você utilizará este campo se estiver gerando um boleto com o NIB gerado pelo Banco (possivelmente na utilização do serviço bancário de em uma cobrança registrada), ou se você mesmo tiver gerado o NIB por algum outro motivo, o que indica que você obedeceu todas as regras exigidas pelo Banco para compor e gerar esse número.

Campos da Requisição

O boleto é um documento que representa um título de cobrança, que pode ser do tipo duplicata, nota promissória, fatura, etc. Basicamente essa representação é composta pelas seguintes partes:

  • Dados do Pagador - O que paga o boleto, dados: CPRF, nome, endereço, etc;
  • Dados do Beneficiário - O que recebe o pagamento, dados: CPRF, nome, endereço, etc;
  • Dados do Banco - Instituição recebedora final do pagamento, dados: Código de compensação, agência, conta, etc;
  • Dados do Título - O documento de cobrança, dados: tipo do documento, emissão do documento, número do documento, valor do documento, etc;
  • Dados do Boleto - O instrumento de pagamento, dados: número bancário (nosso número), código de barras, linha digitável, instruções ao caixa, etc;

NOTA: Na API e na plataforma em geral nos referimos ao CPRF como sendo o Cadastro de Pessoa na Receita Federal, que atualmente pode ser um CPF (Pessoa Física) ou CNPJ (Pessoa Jurídica).

Campos do Boleto
Nome do campo Tipo Obrigatório Exemplo
boleto.titulo string Sim "FAT" Sigla que identifica o tipo de título de cobrança. Valores: AP, CC, CH, CPR, DAE, DAM, DAU, DD, DM, DMI, DR, DS, DSI, EC, FAT, LC, ME, NCC, NCE, NCI, NCR, ND, NF, NP, NPR, NS, O, PC, RC, TM, TS, W.
boleto.aceite boolean Não false False por padrão. O campo aceite indica se o pagador reconheceu ou não o título de cobrança como sendo dele (contra ele).
boleto.documento string Sim "DOC-XPTO-1/A" Número do documento: geralmente é um número de controle do sistema de informação do beneficiário, usado para identificar o documento de origem do beneficiário.
boleto.numero string Sim se campo boleto.sequencial ausente "123456789-0" Número Identificador Bancário(NIB), denominado pelo banco como "Nosso Número" utilizado para identificar o título de forma única no sistema de cobrança. Esse número tem sua composição baseada em regras que variam em função do banco e do serviço de cobrança, caso deseje que esse número seja gerado pela API utilize o campo boleto.sequencial.
boleto.sequencial integer Sim se campo boleto.numero ausente 12345 Número sequencial utilizado como base para gerar o NIB, este deve ser um número sequencial e único informado pelo seu sistema. O número de dígitos permitidos para esse campo pode variar dependendo do banco. Se esse campo for informado, então o campo boleto.numero não deve ser informado.
boleto.emissao date Sim 2014-07-23 Data na qual o documento de cobrança foi emitido. Sempre deve ser uma data igual a atual ou anterior (no passado) a data atual. Obs: Essa data não é a mesma do campo "Data de Processamento" do boleto, pois a última é gerada pela API.
boleto.vencimento date Sim 2015-07-23 Data limite definida para pagamento do boleto. Sempre deve ser uma data igual a atual ou posterior (futuro) a data atual.
boleto.valor decimal Sim 50207.93 Valor nominal do documento de cobrança, ou seja, o valor do boleto.
boleto.juros decimal Não 3.33 Porcentagem de juros a ser calculada por dia, com base no valor do documento, campo boleto.valor.
boleto.multa decimal Não 2.10 Porcentagem de multa a ser calculada com base no valor do documento, campo boleto.valor.
boleto.instrucao string Não "Não receber após o vencimento" Instrução ao caixa, até 8 campos desse podem estar presentes em uma única requisição, o que corresponde as 8 linhas presentes no campo instruções ao caixa na ficha de compensação do boleto padrão.
Campos do Beneficiário
Nome do campo Tipo Obrigatório Exemplo
boleto.beneficiario.nome string Sim "DevAware Solutions" Nome, nome fantasia, razão social
boleto.beneficiario.cprf string Sim "15.719.277/0001-46"
"111.111.111-11"
Cadastro de Pessoa na Receita Federal: CPF ou CNPJ
boleto.beneficiario.endereco.cep string Sim "59020-000" CEP - Código de Endereçamento Postal
boleto.beneficiario.endereco.uf string Sim "RN" UF - Unidade Federativa
boleto.beneficiario.endereco.localidade string Sim "Natal" Nome da localidade/cidade
boleto.beneficiario.endereco.bairro string Sim "Petrópolis" Bairro
boleto.beneficiario.endereco.logradouro string Sim "Avenida Hermes da Fonseca" Avenida, rodovia, rua, etc
boleto.beneficiario.endereco.numero string Sim "384" Número
boleto.beneficiario.endereco.complemento string Não "Sala 2A, segundo andar" Complemento, referência, etc
Campos do Pagador
Nome do campo Tipo Obrigatório Exemplo
boleto.pagador.nome string Sim "Alberto Santos Dumont" Nome, nome fantasia, razão social
boleto.pagador.cprf string Sim "15.719.277/0001-46"
"111.111.111-11"
Cadastro de Pessoa na Receita Federal: CPF ou CNPJ
boleto.pagador.endereco.cep string Sim "36240-000" CEP - Código de Endereçamento Postal
boleto.pagador.endereco.uf string Sim "MG" UF - Unidade Federativa
boleto.pagador.endereco.localidade string Sim "Santos Dumont" Nome da localidade/cidade
boleto.pagador.endereco.bairro string Sim "Casa Natal" Bairro
boleto.pagador.endereco.logradouro string Sim "BR-499" Avenida, rodovia, rua, etc
boleto.pagador.endereco.numero string Sim "s/n" Número
boleto.pagador.endereco.complemento string Não "Sítio - Subindo a serra da Mantiqueira" Complemento, referência, etc
Campos da Conta - Dependem do Banco utilizado.
Nome do campo Tipo Obrigatório Exemplo
boleto.conta.banco string Sim "237" Código de compensação BACEN do banco.
boleto.conta.? ? ? ?
NOTA: Com exceção do código do Banco que é obrigatório para todos os casos, outros campos como: agência, conta, carteira, etc; podem ser utilizados ou não dependendo do Banco. Além disso, outros campos ainda mais específicos de cada Banco podem ser adicionados. Para criar um boleto de um dado Banco consulte a seção específica relacionada ao Banco desejado.

Banco

Até agora vimos os campos e dados comuns para se criar um boleto, porém, alguns campos variam e até são adicionados dependendo do Banco em questão. A variação principal acontece na conta bancária, mas os campos já vistos até este ponto que variam em função do Banco são:

  • boleto.sequencial
  • boleto.numero
  • boleto.conta.*

A seguir listamos os campos específicos para a criação do boleto em função do Banco.

237 - Bradesco
Campos do Boleto Bradesco
Nome do campo Tipo Obrigatório Exemplo
boleto.numero string Sim se campo boleto.sequencial ausente "00123456789-4"
"50000987654-P"
Banco Bradesco - O NIB deve ser informado no formato padrão ("99999999999-D"), onde "9" corresponde a um dígito de zero a nove e "D", que representa o dígito verificador, corresponde a um dígito de zero a nove ou a letra "P". Portanto, o NIB Bradesco é um campo de 11 dígitos mais um dígito verificador que pode ser um número ou a letra "P".
boleto.sequencial integer Sim se campo boleto.numero ausente 123 Banco Bradesco - O Número Sequencial deve ser um número entre 1 a 99.999.999.999, ou seja um número inteiro positivo com no mínimo 1 dígito e no máximo 11 dígitos.
Campos da Conta Bradesco
Nome do campo Tipo Obrigatório Exemplo
boleto.conta.banco string Sim "237" Banco Bradesco - Fixo 237, que é o código de compensação BACEN do banco .
boleto.conta.agencia string Sim "8764-2"
"321-P"
Banco Bradesco - O número da agência deve ser informado no formato padrão ("9999-D"), onde "9" corresponde a um dígito de zero a nove e "D", que representa o dígito verificador, corresponde a um dígito de zero a nove ou a letra "P". Portanto, o número da agência Bradesco é um campo de 1 a 4 dígitos mais um dígito verificador que pode ser um número ou a letra "P".
boleto.conta.numero string Sim "56789-0"
"1234567-P"
Banco Bradesco - O número da conta deve ser informado no formato padrão ("9999999-D"), onde "9" corresponde a um dígito de zero a nove e "D", que representa o dígito verificador, corresponde a um dígito de zero a nove ou a letra "P". Portanto, o número da conta Bradesco é um campo de 1 a 7 dígitos mais um dígito verificador que pode ser um número ou a letra "P".
boleto.conta.carteira integer Sim 11 Banco Bradesco - O número da carteira de cobrança deve ser um número entre 1 e 99.


Outros Bancos? Deseja ver mais Bancos descritos na API? Entre em contato conosco.

Buscar (GET)

ATENÇÃO: Enquanto sua aplicação estiver em desenvolvimento, você deve utilizar somente o endpoint Sandbox em https://sandbox.boletocloud.com, isso evitará maiores problemas como bloqueio de chamadas, inconsistência de dados e até o bloqueio total da conta na plataforma.

INPUT REQUEST

Client

Request

API Boleto Cloud

URL /boletos/{TOKEN}

Header Authorization: Basic

OUTPUT RESPONSE

API Boleto Cloud

Response

Client

Header X-BoletoCloud-Version


HTTP Status Code 200 - Sucesso

Header Content-Type: application/pdf; charset=UTF-8

Body Boleto PDF


HTTP Status Code XXX - Falha

Header Content-Type: application/json; charset=UTF-8

Body Erro JSON

Para se buscar um boleto já criado na plataforma (em que foi criado utilizado o método POST) utilizamos o método GET, que retorna um arquivo no formato PDF. Para isso, tudo que você precisa fazer é realizar uma chamada GET a URL https://sandbox.boletocloud.com/api/v1/boletos e informar o token do boleto obtido após a criação do mesmo via POST.

Veja alguns exemplos:

Exemplo - Interface Gráfica

Para obter o boleto PDF via Postman, faça como na imagem abaixo:

  • Defina a url da sandbox para o serviço e o token /boletos/ACin7NWnpRVC-dpjKqu4b5LVR7T1vcbE9UmhAm-Qa9g=;
  • Defina o Header Authorization na aba com este nome e escolha o tipo Basic Auth, caso tenha dúvidas veja um exemplo de autenticação;
  • Por fim, selecione no botão azul Send a opção Send and download para enviar os dados e já realizar o download do arquivo PDF.

Para saber mais sobre o uso do postman, veja a seção sobre os exemplos.

Exemplo - Linha de Comando

Para executar uma chamada GET utilizando o cURL sugerimos os seguintes parâmetros:

  • -v Indicando que a execução deve ser verbosa e os detalhes dela devem ser exibidos na tela;
  • -u Informando o usuário utilizado na autenticação, como já explicado na seção autenticação;
  • -o Definindo que o arquivo pdf retornado será salvo em um arquivo chamado arquivo-api-boleto-get-teste.pdf no diretório atual.

$ curl -v "https://sandbox.boletocloud.com/api/v1/boletos/ACin7NWnpRVC-dpjKqu4b5LVR7T1vcbE9UmhAm-Qa9g=" \
-u "api-key_vJxqRj_8ZIu7850rCC3R-lDRcedJ40l4KuMlLH-Kjxs=:token" \
-o arquivo-api-boleto-get-teste.pdf

Para saber mais sobre o uso do cURL, veja a seção sobre os exemplos.

Exemplo - Código Java

Para executar uma chamada GET em Java utilizamos a API da linguagem própria para serviços REST, a (JAX-RS):


import static java.nio.file.StandardCopyOption.REPLACE_EXISTING;
import static javax.ws.rs.core.MediaType.WILDCARD;
import static javax.ws.rs.core.Response.Status.OK;

import java.io.InputStream;
import java.nio.file.Files;
import java.nio.file.Paths;

import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.core.Response;

import org.glassfish.jersey.client.authentication.HttpAuthenticationFeature;

/**
 * Exemplo de busca de um boleto já existente utilizando o método HTTP GET.
 * Após obter o PDF do boleto o arquivo é aberto utilizando o leitor de PDF do sistema operacional.
 *
 *	Para executar o exemplo é preciso:
 *  # Java 6 ou superior
 *  # JAX-RS 2.x ou superior
 *  # Jersey Client 2.x ou superior
 */
public class BuscarBoleto {

	public static void main(String[] args) throws Exception {
		/*
		 * Requisição para buscar boleto
		 */
		Response response = ClientBuilder
				.newClient()
				.target("https://sandbox.boletocloud.com/api/v1/boletos")
				.path("/ACin7NWnpRVC-dpjKqu4b5LVR7T1vcbE9UmhAm-Qa9g=")//Token do boleto
				.register(
						//Define o tipo de autenticação HTTP Basic 
						HttpAuthenticationFeature.basic(
								"api-key_vJxqRj_8ZIu7850rCC3R-lDRcedJ40l4KuMlLH-Kjxs=",
								"token"
						)
				)
				.request(WILDCARD)//Aceita qualquer resposta
				.get();
		/*
		 * Dados da resposta
		 */
		System.out.println("HTTP Status Code: "+response.getStatus());
		System.out.println("Boleto Cloud Version: "+response.getHeaderString("X-BoletoCloud-Version"));
		/*
		 * Identifica se o boleto foi retornado ou houve erro
		 */
		if(response.getStatus() == OK.getStatusCode()){
			
			//Salva o arquivo do diretório corrente.
			Files.copy(response.readEntity(InputStream.class), Paths.get("arquivo-api-boleto-get-teste.pdf"), REPLACE_EXISTING);
			
			//Caso tenha leitor pdf no sistema..
			//Abrirá o arquivo PDF utilizando o leitor de PDF do sistema operacional
			//java.awt.Desktop.getDesktop().open(new File("arquivo-api-boleto-get-teste.pdf"));
			
		}else{
			System.err.println("Erro retornado em json: "+response.readEntity(String.class));
		}
		//Para saber mais sobre tratamento de erros veja a seção Status & Erros
	}
}

Para saber mais sobre uso do Java, veja a seção sobre os exemplos.

Exemplo - Código PHP

Para executar uma chamada GET em PHP utilizamos a biblioteca cURL da seguinte forma:


<?php

/*
 * Exemplo de busca de um boleto já existente utilizando o método HTTP GET.
 * Após obter o PDF do boleto o arquivo é enviado como resposta para visualização no navegador.
 *
 * cURL - http://php.net/manual/pt_BR/book.curl.php
**/

//URL do serviço /boleto + /token
$url = 'https://sandbox.boletocloud.com/api/v1/boletos/ACin7NWnpRVC-dpjKqu4b5LVR7T1vcbE9UmhAm-Qa9g=';

// curl - http://php.net/manual/pt_BR/book.curl.php
#Inicializa a sessão
$ch = curl_init(); 

//Opções relacionadas a requisição: http://php.net/manual/pt_BR/function.curl-setopt.php
#Define a url
curl_setopt($ch, CURLOPT_URL, $url);
#Define o tipo de autenticação HTTP Basic 
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
#Define o API Token para realizar o acesso ao serviço
curl_setopt($ch, CURLOPT_USERPWD, "api-key_vJxqRj_8ZIu7850rCC3R-lDRcedJ40l4KuMlLH-Kjxs=:token");
#True para enviar o conteúdo do arquivo direto para o navegador
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
#Define que os headers estarão na resposta
curl_setopt($ch, CURLOPT_HEADER, true);

//Necessário para requisição HTTPS
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);

#Executa a chamada
$response = curl_exec($ch);

#Principais meta-dados da resposta
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE); 
$header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);

#Encerra a sessão
curl_close($ch);

#Separando header e body contidos na resposta
$header = substr($response, 0, $header_size);
$body = substr($response, $header_size);
$header_array = explode("\r\n", $header);

#Principais headers deste exemplo
$boleto_cloud_version = '';

foreach($header_array as $h) {
    if(preg_match('/X-BoletoCloud-Version:/i', $h)) {
        $boleto_cloud_version = $h;
    }
}

#Processando sucesso ou falha

if($http_code == 200){#OK - SUCESSO
	#Versão da plataforma: $boleto_cloud_version 
	#Enviando boleto como resposta:
	header('Content-type: application/pdf');
	header('Content-Disposition: inline; filename=arquivo-api-boleto-get-teste.pdf');
	echo $body; #Visualização no navegador
}else{//ERRO
	#Versão da plataforma: $boleto_cloud_version 
	#Códgio de erro HTTP: $http_code
	#Enviando erro JSON como resposta:
	header('Content-Type: application/json; charset=utf-8');
	echo $body; #Visualização no navegador
}

/*
 * Para saber mais sobre tratamento de erros veja a seção Status & Erros 
**/

?>

Para saber mais sobre uso do PHP, veja a seção sobre os exemplos.

O retorno da requisição, além de ter o PDF no body da resposta, também contém os seguintes Headers:


Content-Type: application/pdf;charset=UTF-8
X-BoletoCloud-Version: 0.4.5

Detalhando esses Headers, temos que:

  • Content-Type É referente ao tipo de conteúdo do retorno;
  • X-BoletoCloud-Version É a versão atual da plataforma em execução.

Além disso, todo boleto também pode ser obtido no site, na página de segunda via, que nesse caso é:

https://sandbox.boletocloud.com/boleto/2via/ACin7NWnpRVC-dpjKqu4b5LVR7T1vcbE9UmhAm-Qa9g=

Ou seja, basta substituir o token do boleto para obter a segunda via de qualquer boleto em https://sandbox.boletocloud.com/boleto/2via/.

Se você deseja criar um novo boleto via API, então utilize o método POST.

Arquivo CNAB Remessa

O arquivo remessa é o responsável por registrar os boletos no sistema do Banco. Desde 2017, com implantação da nova plataforma de cobrança pela febraban e a Rede Bancária, todos os boletos devem ser registrados.

Para exportar o arquivo remessa via API, é necessário usar a nova forma de geração de boletos através do token da conta bancária. Portanto, caso não saiba como funciona ou ainda não tenha gerado o token de acesso da conta bancária, acesse a seção Nova forma de geração de boletos para mais informações.

A geração do arquivo remessa é simples, após ter gerados os boletos que se deseja exportar, realiza-se uma chamada post ao endpoint https://sandbox.boletocloud.com/api/v1/arquivos/cnab/remessas.

Além da autenticação (descrita na seção Autenticação, da mesma forma que é usada na emissão de boletos), o único parâmetro necessário utilizado para gerar o arquivo remessa é o token da conta bancária. Por exemplo:

remessa.conta.token="api-key_i2vY-t8RcRxqdiRF_H3RVj4PYH1Ns10xf63pCmnyl5A="

Caso ainda não exista remessa para os boletos gerados, um novo arquivo será retornado contendo como headers:

"X-BoletoCloud-Token" = "EX-123.."
"Location" = "/api/v1/arquivos/cnab/remessas/EX-123.." 
"Content-Type"="text/plain;charset=utf-8"

O nome do arquivo pode ser obtido via header:

"Content-Disposition"="inline; filename=CB070402.REM"

Caso não exista nenhum boleto para remessa, o código de status 204 (NO CONTENT) será retornado.

Veja alguns exemplos:

Exemplo - Código Java

Para executar uma chamada POST em Java utilizamos a API da linguagem própria para serviços REST, a (JAX-RS):


package com.boletocloud.app._temp.api.exemplos;

import static java.nio.file.StandardCopyOption.REPLACE_EXISTING;
import static javax.ws.rs.core.MediaType.WILDCARD;
import static javax.ws.rs.core.Response.Status.CREATED;

import java.io.InputStream;
import java.nio.file.Files;
import java.nio.file.Paths;

import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.core.Form;
import javax.ws.rs.core.Response;

import org.glassfish.jersey.client.authentication.HttpAuthenticationFeature;

/**
 * Exemplo de criação de um arquivo remessa inexistente utilizando o método HTTP POST.
 * Caso exista boletos criados no sistema e ainda não constem em uma remessa em progresso, 
 * o retorno será um arquivo txt remessa como resposta.
 *
 * Para executar o exemplo é preciso: # Java 6 ou superior #JAX-RS 2.x ou
 * superior # Jersey Client 2.x ou superior
 */
public class CriarRemessa {

	public static void main(String[] args) throws Exception {
		/*
		 * Dados para criação do arquivo remessa
		 */
		Form formData = new Form();
		formData.param("remessa.conta.token","api-key_conta_bancaria-abc=");
		/*
		 * Requisição para criação do boleto
		 */
		Response response = ClientBuilder
				.newClient()
				.target("https://sandbox.boletocloud.com/api/v1")
				.path("/arquivos/cnab/remessas")
				.register(
						//Define o tipo de autenticação HTTP Basic 
						HttpAuthenticationFeature.basic(
								"api-key_usuario-123=",
								"token"
						)
				)
				.request(WILDCARD)//Aceita qualquer resposta
				.post(Entity.form(formData));
		/*
		 * Dados da resposta
		 */
		System.out.println("HTTP Status Code: "+response.getStatus());
		System.out.println("Boleto Cloud Version: "+response.getHeaderString("X-BoletoCloud-Version"));
		//Poderá ser usado para buscar o arquivo criado via GET posteriormente 
		System.out.println("Boleto Cloud Token do arquivo criado: "+response.getHeaderString("X-BoletoCloud-Token"));
		/*
		 * Identifica se o arquivo remessa foi criado ou houve erro
		 */		
		if(response.getStatus() == CREATED.getStatusCode()){
			
			String contentDisposition = response.getHeaderString("Content-Disposition");
			String fileName = contentDisposition.replaceAll(".*filename=", "").trim();

			System.out.println("Nome do arquivo: "+fileName);
			
			//Salva o arquivo do diretório corrente.
			Files.copy(response.readEntity(InputStream.class), Paths.get(fileName), REPLACE_EXISTING);
			
			//Caso tenha leitor pdf no sistema..
			//Abrirá o arquivo PDF utilizando o leitor de PDF do sistema operacional
			//java.awt.Desktop.getDesktop().open(new File(fileName));
			
		}else{
			System.err.println("Erro retornado em json: "+response.readEntity(String.class));
		}
		//Para saber mais sobre tratamento de erros veja a seção Status & Erros
	}
}

Para saber mais sobre uso do Java, veja a seção sobre os exemplos.

Exemplo - Código PHP

Para executar uma chamada POST em PHP utilizamos a biblioteca cURL da seguinte forma:


<?php

#Token da conta bancária cadastrada
$fields = array(
'remessa.conta.token'=> 'api-key_123456789012345678901234567890='
);


$fields_string = '';

foreach($fields as $key=>$value) {
    if(is_array($value)){
        foreach($value as $v){
            $fields_string .= urlencode($key).'='.urlencode($v).'&';
        }
    }else{
        $fields_string .= urlencode($key).'='.urlencode($value).'&';
    }
}

$data = rtrim($fields_string, '&');
$accept_header = 'Accept: application/pdf, application/json';
$content_type_header = 'Content-Type: application/x-www-form-urlencoded; charset=utf-8';
$headers = array($accept_header, $content_type_header);

$url = 'https://sandbox.boletocloud.com/api/v1/arquivos/cnab/remessas';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_USERPWD, "api-key_123456789012345678901234567890=:token"); #TOKEN do usuário
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);# Basic Authorization
curl_setopt($ch, CURLOPT_HEADER, true);#Define que os headers estarão na resposta
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false); #Para uso com https
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); #Para uso com https

$response = curl_exec($ch);

$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);

curl_close($ch);

$created = 201;

$header = substr($response, 0, $header_size);
$body = substr($response, $header_size);
$header_array = explode("\r\n", $header);

$boleto_cloud_version = '';
$boleto_cloud_token = '';
$location = '';
$file_name = '';

foreach($header_array as $h) {
    if(preg_match('/X-BoletoCloud-Version:/i', $h)) {
        $boleto_cloud_version = $h;
    }
    if(preg_match('/X-BoletoCloud-Token:/i', $h)) {
        $boleto_cloud_token = $h;
    }
    if(preg_match('/Location:/i', $h)) {
        $location = $h;
    }
    if(preg_match('/Content-Disposition: .*filename=([^ ]+)/i', $h)) {
        $file_name = preg_replace('/Content-Disposition:.*filename=/i', '', $h);
    }
}

if($http_code == $created){
    
    header('Content-type: application/text');
    header('Content-Disposition: attachment; filename="'.$file_name.'"' );
    header('Content-Length: ' . strlen($body));

    echo $body;
    
}else{
    header('Content-Type: application/text; charset=utf-8');
    echo "NENHUMA REMESSA DISPONÍVEL.";
}

?>

Para saber mais sobre uso do PHP, veja a seção sobre os exemplos.

Arquivo CNAB Retorno

O processamento do arquivo retorno cria o arquivo no sistema Boleto Cloud. Por isso, a chamada ao endpoint é através do método post, devendo ser feita apenas uma vez para cada arquivo.

O endpoint do processamento do arquivo retorno é o https://sandbox.boletocloud.com/api/v1/arquivos/cnab/retornos. O input desse endpoint é apenas o arquivo retorno via http post e o retorno é um json contendo os dados do títulos/boletos processados com liquidados.

Importante! Serão retornados no json apenas os boletos que existirem na plataforma Boleto Cloud. Portanto, se no arquivo retorno existirem títulos/boletos que não existam na plataforma Boleto Cloud, esses, mesmo que informados como liquidados no arquivo, não serão retornados no json.

Erros 500 provavelmente ocorrerão caso não se tenha uma conta bancária cadastrada na plataforma de testes ou produção com os mesmos dados da conta bancária informada no arquivo, principalmente o número do convênio.

Veja alguns exemplos:

Exemplo - Código Java

Para executar uma chamada POST em Java utilizamos a API da linguagem própria para serviços REST, a (JAX-RS):


package com.boletocloud.app._temp.api.exemplos;

import static java.nio.file.StandardCopyOption.REPLACE_EXISTING;
import static javax.ws.rs.core.MediaType.APPLICATION_JSON;
import static javax.ws.rs.core.Response.Status.CREATED;

import java.io.File;
import java.io.InputStream;
import java.nio.file.Files;
import java.nio.file.Paths;

import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.core.Response;

import org.glassfish.jersey.client.authentication.HttpAuthenticationFeature;
import org.glassfish.jersey.media.multipart.FormDataMultiPart;
import org.glassfish.jersey.media.multipart.MultiPart;
import org.glassfish.jersey.media.multipart.MultiPartFeature;
import org.glassfish.jersey.media.multipart.file.FileDataBodyPart;

/**
 * Exemplo de processamento de um arquivo retorno CNAB utilizando o método HTTP POST.
 * Após enviar o arquivo e obter o json resultante do processamento como resposta, o arquivo é
 * aberto utilizando algum programa padrão do sistema operacional.
 *
 * Para executar o exemplo é preciso: # Java 6 ou superior #JAX-RS 2.x ou
 * superior # Jersey Client 2.x ou superior
 */
public class ProcessarRetornoCNAB {

	public static void main(String[] args) throws Exception {
		
		/*
		 * Dados de input: arquivo retorno
		 */
		final FileDataBodyPart filePart = new FileDataBodyPart("arquivo", new File("/CB270200.RET"));
		final MultiPart multipart = new FormDataMultiPart().bodyPart(filePart);
			    
		/*
		 * Requisição para processamento
		 */
		Response response = ClientBuilder
				.newClient()
				.target("https://sandbox.boletocloud.com/api/v1")
				.path("/arquivos/cnab/retornos")
				.register(
						//Define o tipo de autenticação HTTP Basic 
						HttpAuthenticationFeature.basic(
								"api-key_usuário-123=",
								"token"
						)
				)
				.register(MultiPartFeature.class)
				.request(APPLICATION_JSON)//Pode ser o resultado do processamento do arquivo em json ou uma mensagem de erro em json
				.post(Entity.entity(multipart, multipart.getMediaType()));
		/*
		 * Dados da resposta
		 */
		System.out.println("HTTP Status Code: "+response.getStatus());
		System.out.println("Boleto Cloud Version: "+response.getHeaderString("X-BoletoCloud-Version"));
		System.out.println("Boleto Cloud Token para Arquivo: "+response.getHeaderString("X-BoletoCloud-Token"));
		/*
		 * Identifica se o processamento do retorno foi criado ou houve erro
		 */		
		if(response.getStatus() == CREATED.getStatusCode()){
			
			//Salva o arquivo do diretório corrente.
			Files.copy(response.readEntity(InputStream.class), Paths.get("retorno.json"), REPLACE_EXISTING);
			
			//Caso tenha algum programa no sistema ligado a arquivos json (editor de texto ou browser por exemplo)..
			//Abrirá o arquivo json utilizando o programa padrão do sistema operacional
			java.awt.Desktop.getDesktop().open(new File("retorno.json"));
			
		}else{
			System.err.println("Erro retornado em json: "+response.readEntity(String.class));
		}
	}
}

Para saber mais sobre uso do Java, veja a seção sobre os exemplos.

Exemplo - Código PHP

Apesar de ser uma chamada post, para o envio do arquivo não é necessário definir o método:


<?php

#Definindo conteúdo da requisição e tipos de respostas aceitas
 
$accept_header = 'Accept: application/json';
 
#Estou enviando esse formato de dados
$headers = array($accept_header);

#Configurações do envio

$url = 'https://sandbox.boletocloud.com/api/v1/arquivos/cnab/retornos';

$data = array(
    'arquivo' => '@/tmp/ret001457.ret',
);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SAFE_UPLOAD, false);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_USERPWD, "api-key_Seu-Token:token"); #API TOKEN 
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);# Basic Authorization
curl_setopt($ch, CURLOPT_HEADER, true);#Define que os headers estarão na resposta
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false); #Para uso com https
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); #Para uso com https
 
#Envio

$response = curl_exec($ch);

#Principais meta-dados da resposta

$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE); 
$header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);

#Fechar processo de comunicação
curl_close($ch);

#Processando a resposta

$created = 201; #Constante que indica recurso criado (Retorno criado na Plataforma)

#Separando header e body na resposta

$header = substr($response, 0, $header_size);
$body = substr($response, $header_size);
$header_array = explode("\r\n", $header);

#Principais headers
$boleto_cloud_version = '';
$boleto_cloud_token = '';
$location = '';

foreach($header_array as $h) {
    if(preg_match('/X-BoletoCloud-Version:/i', $h)) {
        $boleto_cloud_version = $h;
    }
    if(preg_match('/X-BoletoCloud-Token:/i', $h)) {
        $boleto_cloud_token = $h;
    }
    if(preg_match('/Location:/i', $h)) {
        $location = $h;
    }
}

#Processando sucesso ou falha

if($http_code == $created){
    #Versão da plataforma: $boleto_cloud_version 
    #Token do boleto disponibilizado: $boleto_cloud_token
    #Localização do boleto na plataforma: $location
    #Enviando boleto como resposta:
    header('Content-Type: application/json; charset=utf-8');
    echo $body; #Visualização no navegador
}else{
#EM CASO DE ERRO 500 ---> LEMBRE-SE QUE É PRECISO TER UMA CONTA BANCÁRIA CADASTRADA!! 
#E COM CONVÊNIO E DADOS IGUAIS AO DA CONTA BANCÁRIA DO ARQUIVO RELACIONADO
    #Versão da plataforma: $boleto_cloud_version 
    #Códgio de erro HTTP: $http_code
    #Enviando erro como resposta:
    header('Content-Type: application/json; charset=utf-8');
    echo $body; #Visualização no navegador
}

?>

Para saber mais sobre uso do PHP, veja a seção sobre os exemplos.

Veja abaixo um exemplo do retorno do processamento no formato json:

{
  arquivo: {
    meta: {
      token: "m1pKbdCyI9T9qJPC4nUSE8-qLu0UbwWRQv6xcQqMa98=",
      criado: "2015-12-09T00:06:37.380Z"
    },
    protocolo: {
      banco: {
        codigo: "104",
        nome: "C ECON FEDERAL"
      },
      numero: 1457,
      gravacao: "2015-09-11"
    },
    titulos: [{
        token: "_NctQTmnGihkyIUhQasUNOM1m-O0TaUO8yoo8eoX-v8=",
        numero: "000000000045539-7",
        documento: "45539",
        valor: 133.19,
        vencimento: "2015-09-22",
        ocorrencias: [{
          situacao: "LIQUIDACAO",
          codigo: 6,
          descricao: "Liquidação",
          motivos: [],
          info: {
            valorPago: 133.19,
            jurosMora: 0,
            dataDeCredito: "2015-09-14",
            situacao: "LIQUIDACAO"
          }
        }]
      },
      {
        token: "vn2eRfP3bbDjE7aW_BcGcUjDv2phDi8763Usdg0x0g0=",
        numero: "000000000045173-1",
        documento: "45173",
        valor: 603.86,
        vencimento: "2015-09-22",
        ocorrencias: [{
          situacao: "LIQUIDACAO",
          codigo: 6,
          descricao: "Liquidação",
          motivos: [],
          info: {
            valorPago: 603.86,
            jurosMora: 0,
            dataDeCredito: "2015-09-14",
            situacao: "LIQUIDACAO"
          }
        }]
      },
    ]
  }
}

Suporte

Já falamos anteriormente, queremos mesmo ouvir seu feedback, o que achou da API?

Está atendendo suas necessidades? Está faltando algo?

Você tem alguma sugestão?

Entre em contato conosco.