Java

📘
O SDK Java do Asaas é a forma mais prática, segura e robusta de integrar a API REST em aplicações desenvolvidas com Java ou Kotlin. Ele é publicado oficialmente no Sonatype (Maven Central) e validado continuamente por ferramentas de qualidade e segurança.

Repositório oficial

Você pode acessar o código-fonte, histórico de versões e exemplos no GitHub clicando aqui.

O repositório contém exemplos de uso em inglês. Esta documentação (em português) complementa os exemplos com explicações mais detalhadas e aplicadas ao contexto local.

Publicação e qualidade

O SDK é distribuído pelo Maven Central via Sonatype.
Os artefatos são assinados com suporte ao GitHub Artifact Attestations, garantindo a proveniência e integridade dos builds. Saiba mais sobre essa tecnologia em: GitHub Artifact Attestations.

Você pode consultar o SDK diretamente no Sonatype Central.

Instalação

<dependency>
    <groupId>com.asaas</groupId>
    <artifactId>api-sdk</artifactId>
    <version>VERSAO_AQUI</version>
</dependency>

implementation group: 'com.asaas', name: 'api-sdk', version: 'VERSAO_AQUI'

Consulte o GitHub ou a página do Sonatype para verificar a versão mais recente.

Autenticação

A autenticação é feita via API Key (Veja a seção Autenticação), que deve ser configurada ao inicializar o SDK:

import com.asaas.apisdk.AsaasSdk;
import com.asaas.apisdk.config.ApiKeyAuthConfig;
import com.asaas.apisdk.config.AsaasSdkConfig;

ApiKeyAuthConfig authConfig = ApiKeyAuthConfig.builder()
  .apiKey("SUA_API_KEY")
  .build();

AsaasSdkConfig config = AsaasSdkConfig.builder()
  .apiKeyAuthConfig(authConfig)
  .build();

AsaasSdk asaasSdk = new AsaasSdk(config);

❗️
Nunca exponha sua chave de API diretamente no código-fonte. Use variáveis de ambiente ou um gerenciador seguro de configurações

Ambientes

O SDK suporta tanto o ambiente de sandbox, quanto o de produção:

Environment.DEFAULT   // Produção (https://api.asaas.com/)
Environment.SANDBOX   // Sandbox (https://api-sandbox.asaas.com/)

Para definir o ambiente desejado:

asaasSdk.setEnvironment(Environment.SANDBOX);

Timeout personalizado

Você pode configurar o timeout das requisições HTTP ao instanciar o SDK:

AsaasSdkConfig config = AsaasSdkConfig.builder()
  .timeout(10000) // timeout em milissegundos
  .build();

Usando o SDK em projetos Spring Boot

Para usar o SDK de forma mais idiomática em projetos Spring, você pode configurá-lo como um @Bean e injetar os serviços onde precisar.

import com.asaas.apisdk.AsaasSdk;
import com.asaas.apisdk.config.ApiKeyAuthConfig;
import com.asaas.apisdk.config.AsaasSdkConfig;
import com.asaas.apisdk.http.Environment;

import com.asaas.apisdk.services.CustomerService;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class AsaasConfig {

    @Value("${asaas.api.key}")
    private String asaasApiKey;

    @Bean
    public AsaasSdk asaasSdk() {
        AsaasSdkConfig config = AsaasSdkConfig.builder()
            .apiKeyAuthConfig(ApiKeyAuthConfig.builder().apiKey(asaasApiKey).build())
            .build();

        config.setEnvironment(Environment.SANDBOX);

        return new AsaasSdk(config);
    }

    @Bean
    public CustomerService customerService(AsaasSdk asaasSdk) {
        return asaasSdk.customer;
    }

}

Agora você pode injetar o CustomerService normalmente nos seus serviços:

import com.asaas.apisdk.AsaasSdk;

import com.asaas.apisdk.models.CustomerGetResponseDto;
import com.asaas.apisdk.models.CustomerSaveRequestDto;
import com.asaas.apisdk.services.CustomerService;
import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Service;

@Service
@RequiredArgsConstructor
public class MyService {

    private final AsaasSdk asaasSdk;

    private final CustomerService customerService;

    public CustomerGetResponseDto save() {
        CustomerSaveRequestDto request = CustomerSaveRequestDto.builder()
            .name("Jhon Doe")
            .cpfCnpj("24971563792")
            .email("[email protected]")
            .phone("88888888888")
            .build();

        return customerService.createNewCustomer(request);
    }

}

✅
Com essa estrutura, o SDK está totalmente integrado à sua aplicação Spring. Basta repetir o padrão para outros serviços como cobranças, assinaturas, links de pagamento, etc.
Você pode encontrar mais exemplos clicando aqui