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.
Com a API você poderá:
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.
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.
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:
Onde:
Portanto, existem apenas dois endpoints para acessar a 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.
O Charset padrão utilizado para todas as chamadas à API é o UTF-8, em caso de dúvidas consulte a RFC3629.
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.
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$. |
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:
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:
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.
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.
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.
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.
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 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.
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.
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:
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:
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.
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.
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:
Para realizar a requisição com autenticação via Postman, faça como na imagem abaixo:
Para saber mais sobre o uso do postman, veja a seção sobre os exemplos.
Para executar uma chamada GET com autenticação utilizando o cURL sugerimos os seguintes parâmetros:
$ 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.
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.
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.
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":
A seguir alguns exemplos de status retornados pela API:
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:
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. |
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"
}
]
}
}
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.
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.
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.
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.
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.
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.
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
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.
Veja alguns exemplos:
Para criar o boleto e obter o arquivo PDF via Postman, faça como na imagem abaixo:
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"
Para saber mais sobre o uso do postman, veja a seção sobre os exemplos.
Para executar uma chamada POST utilizando o cURL sugerimos os seguintes parâmetros:
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.
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.
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:
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.
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"
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:
boleto.conta.banco = "104" boleto.conta.agencia = "1111" boleto.conta.convenio = "605789-1" boleto.conta.carteira = "1" boleto.conta.registro = "true"
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.
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:
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.
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:
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).
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. |
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 |
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 |
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.
|
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:
A seguir listamos os campos específicos para a criação do boleto em função do Banco.
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. |
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.
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:
Para obter o boleto PDF via Postman, faça como na imagem abaixo:
Para saber mais sobre o uso do postman, veja a seção sobre os exemplos.
Para executar uma chamada GET utilizando o cURL sugerimos os seguintes parâmetros:
$ 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.
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.
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:
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.
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:
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.
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.
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:
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.
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" } }] }, ] } }
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?