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://www.boletocloud.com/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://www.boletocloud.com/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://www.boletocloud.com/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://www.boletocloud.com/app/dev/api"
         },
         {
            "codigo": "29E52CCD",
            "mensagem": "Campo (boleto.documento) - O número do documento está ausente, mas é obrigatório.",
            "suporte": "http://www.boletocloud.com/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://www.boletocloud.com/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://www.boletocloud.com/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://www.boletocloud.com/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://www.boletocloud.com/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.

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.

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.