Autenticação HTTP Basic

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

Para a API Boleto Cloud, você deve usar:

• Username (usuário): Sua API Key (exemplo: api-key_123)
• Password (senha): A palavra literal token

Exemplo de valor do header para as credenciais api-key_123:token:

Authorization: Basic YXBpLWtleV8xMjM6dG9rZW4=

Exemplos de Autenticação

Postman

Para autenticar usando o Postman:

1. Defina a URL para o serviço e token
2. Configure o Header “Authorization” como tipo Basic Auth
3. Digite o username como sua API key e password como “token”
4. Clique no botão “Update Request”
5. Selecione “Send”

cURL

curl -v -u api-key_SUA-API-KEY:token \
  https://sandbox.boletocloud.com/api/v1/boletos/1

Parâmetro	Descrição
-v	Saída detalhada (verbose)
-u	Autenticação no formato user:password

Java

import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.core.Response;
import org.glassfish.jersey.client.authentication.HttpAuthenticationFeature;

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

public class Autenticacao {
    public static void main(String[] args) {
        Response response = ClientBuilder.newClient()
            .target("https://sandbox.boletocloud.com/api/v1/boletos")
            .path("/1")
            .register(HttpAuthenticationFeature.basic(
                "api-key_SUA-API-KEY", "token"))
            .request(WILDCARD)
            .get();

        System.out.println("Status: " + response.getStatus());
    }
}

Kotlin

import okhttp3.Credentials
import okhttp3.OkHttpClient
import okhttp3.Request

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

    val request = Request.Builder()
        .url("https://sandbox.boletocloud.com/api/v1/boletos/1")
        .header("Authorization", credential)
        .build()

    client.newCall(request).execute().use { response ->
        println("Status: ${response.code}")
    }
}

C#

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

class Program
{
    static async Task Main(string[] args)
    {
        using var client = new HttpClient();

        var credentials = Convert.ToBase64String(
            Encoding.ASCII.GetBytes("api-key_SUA-API-KEY:token"));
        client.DefaultRequestHeaders.Authorization =
            new AuthenticationHeaderValue("Basic", credentials);

        var response = await client.GetAsync(
            "https://sandbox.boletocloud.com/api/v1/boletos/1");

        Console.WriteLine($"Status: {(int)response.StatusCode}");
    }
}

Node

const https = require('https');

const options = {
  hostname: 'sandbox.boletocloud.com',
  path: '/api/v1/boletos/1',
  method: 'GET',
  auth: 'api-key_SUA-API-KEY:token'
};

const req = https.request(options, (res) => {
  console.log(`Status: ${res.statusCode}`);
});

req.on('error', (e) => console.error(e));
req.end();

Go

package main

import (
    "fmt"
    "net/http"
)

func main() {
    client := &http.Client{}
    req, _ := http.NewRequest("GET",
        "https://sandbox.boletocloud.com/api/v1/boletos/1", nil)
    req.SetBasicAuth("api-key_SUA-API-KEY", "token")

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

    fmt.Printf("Status: %d\n", resp.StatusCode)
}

PHP

<?php
$url = 'https://sandbox.boletocloud.com/api/v1/boletos/1';
$api_key = 'api-key_SUA-API-KEY';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, "$api_key:token");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

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

echo "Status: $http_code\n";
?>

Python

import requests
from requests.auth import HTTPBasicAuth

response = requests.get(
    'https://sandbox.boletocloud.com/api/v1/boletos/1',
    auth=HTTPBasicAuth('api-key_SUA-API-KEY', 'token')
)

print(f'Status: {response.status_code}')

Ruby

require 'net/http'
require 'uri'

uri = URI('https://sandbox.boletocloud.com/api/v1/boletos/1')

Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
  request = Net::HTTP::Get.new(uri)
  request.basic_auth('api-key_SUA-API-KEY', 'token')

  response = http.request(request)
  puts "Status: #{response.code}"
end

Clojure

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

(let [response (client/get
                "https://sandbox.boletocloud.com/api/v1/boletos/1"
                {:basic-auth ["api-key_SUA-API-KEY" "token"]})]
  (println "Status:" (:status response)))

Visão geral >> sobre os exemplos.

Este exemplo usa uma API Key inexistente. Por isso, a API rejeita a requisição como não autorizada — em vez de retornar o PDF do boleto.

• Cenário normal: API Key válida + token de boleto existente → retorna PDF
• Cenário atual: API Key inexistente → retorna erro “não autorizado”

Resposta da API para 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": "https://developers.boleto.cloud/"
      }
    ]
  }
}

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.