asaasSdk

Guia de Início Rápido

Comece a usar o Asaas SDK em minutos! Este guia mostra os passos essenciais para integrar pagamentos na sua aplicação.

📦 Instalação

Maven

Adicione ao seu pom.xml:

<dependency>
    <groupId>io.github.jpdev01</groupId>
    <artifactId>asaassdk</artifactId>
    <version>1.4</version>
</dependency>

Gradle

Adicione ao seu build.gradle:

implementation 'io.github.jpdev01:asaassdk:1.4'

🔑 Obter Chave de API

Acesse Asaas
Faça login na sua conta
Vá em Configurações → Integrações → API
Copie sua chave de API

Importante: Use a chave de produção apenas em ambiente de produção!

⚡ Primeiro Código

1. Inicializar o SDK

import io.github.jpdev.asaassdk.Asaas;

public class Main {
    public static void main(String[] args) {
        // Ambiente de produção
        Asaas.init("sua_chave_api_producao");

        // OU ambiente sandbox (para testes)
        // Asaas.initSandbox("sua_chave_api_sandbox");
    }
}

2. Criar um Cliente

import io.github.jpdev.asaassdk.rest.customeraccount.CustomerAccount;

CustomerAccount cliente = CustomerAccount.creator()
    .setName("João Silva")
    .setCpfCnpj("12345678900")
    .setEmail("joao@exemplo.com")
    .setPhone("47999999999")
    .create();

System.out.println("✅ Cliente criado: " + cliente.getId());

3. Criar uma Cobrança PIX

import io.github.jpdev.asaassdk.rest.payment.Payment;
import io.github.jpdev.asaassdk.enums.BillingType;
import io.github.jpdev.asaassdk.util.Money;
import java.math.BigDecimal;
import java.util.Date;

Payment cobranca = Payment.creator()
    .setCustomer(cliente.getId())
    .setBillingType(BillingType.PIX)
    .setDueDate(new Date())
    .setValue(Money.create(new BigDecimal("100.00")))
    .setDescription("Pagamento de serviço")
    .create();

System.out.println("✅ Cobrança criada: " + cobranca.getId());
System.out.println("📱 QR Code PIX: " + cobranca.getPixQrCode());

🎯 Exemplo Completo

import io.github.jpdev.asaassdk.Asaas;
import io.github.jpdev.asaassdk.rest.customeraccount.CustomerAccount;
import io.github.jpdev.asaassdk.rest.payment.Payment;
import io.github.jpdev.asaassdk.enums.BillingType;
import io.github.jpdev.asaassdk.util.Money;
import java.math.BigDecimal;
import java.util.Date;

public class ExemploCompleto {
    public static void main(String[] args) {
        try {
            // 1. Inicializar SDK
            Asaas.init("sua_chave_api");
            System.out.println("✅ SDK inicializado");

            // 2. Criar cliente
            CustomerAccount cliente = CustomerAccount.creator()
                .setName("Maria Santos")
                .setCpfCnpj("12345678900")
                .setEmail("maria@exemplo.com")
                .setPhone("47999999999")
                .create();

            System.out.println("✅ Cliente criado: " + cliente.getId());

            // 3. Criar cobrança PIX
            Payment cobranca = Payment.creator()
                .setCustomer(cliente.getId())
                .setBillingType(BillingType.PIX)
                .setDueDate(new Date())
                .setValue(Money.create(new BigDecimal("150.00")))
                .setDescription("Pagamento de produto")
                .create();

            System.out.println("✅ Cobrança criada: " + cobranca.getId());
            System.out.println("💰 Valor: R$ " + cobranca.getValue());
            System.out.println("📱 QR Code: " + cobranca.getPixQrCode());

            // 4. Verificar status
            System.out.println("📊 Status: " + cobranca.getStatus());

        } catch (Exception e) {
            System.err.println("❌ Erro: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

🚀 Casos de Uso Comuns

Cobrança com Boleto

Payment boleto = Payment.creator()
    .setCustomer(cliente.getId())
    .setBillingType(BillingType.BOLETO)
    .setDueDate(new Date())
    .setValue(Money.create(new BigDecimal("250.00")))
    .setDescription("Mensalidade")
    .create();

System.out.println("Link do boleto: " + boleto.getBankSlipUrl());

Assinatura Mensal

import io.github.jpdev.asaassdk.rest.subscription.Subscription;
import io.github.jpdev.asaassdk.enums.SubscriptionCycle;

Subscription assinatura = Subscription.creator()
    .setCustomer(cliente.getId())
    .setBillingType(BillingType.CREDIT_CARD)
    .setNextDueDate(new Date())
    .setValue(Money.create(new BigDecimal("99.90")))
    .setCycle(SubscriptionCycle.MONTHLY)
    .setDescription("Plano Premium")
    .create();

System.out.println("Assinatura criada: " + assinatura.getId());

Transferência PIX

import io.github.jpdev.asaassdk.rest.transfer.Transfer;
import io.github.jpdev.asaassdk.enums.PixAddressKeyType;

Transfer transfer = Transfer.pixAddressKeyCreator()
    .setPixAddressKey("12345678900")
    .setPixAddressKeyType(PixAddressKeyType.CPF)
    .setValue(Money.create(new BigDecimal("100.00")))
    .setDescription("Pagamento fornecedor")
    .create();

System.out.println("PIX enviado: " + transfer.getId());

Webhook para Notificações

import io.github.jpdev.asaassdk.rest.webhook.Webhook;
import io.github.jpdev.asaassdk.enums.Event;
import io.github.jpdev.asaassdk.enums.SendType;

Webhook webhook = Webhook.creator()
    .setName("Notificações de Pagamento")
    .setUrl("https://seusite.com/webhook/asaas")
    .setEmail("notificacoes@seusite.com")
    .setSendType(SendType.SEQUENTIALLY)
    .addEvent(Event.PAYMENT_RECEIVED)
    .addEvent(Event.PAYMENT_CONFIRMED)
    .create();

System.out.println("Webhook configurado: " + webhook.getId());

🔧 Configurações Úteis

Ambiente Sandbox

Para testes, use o ambiente sandbox:

Asaas.initSandbox("sua_chave_api_sandbox");

Timeout Personalizado

Ajuste o timeout das requisições (padrão: 30 segundos):

Asaas.setTimeout(10000); // 10 segundos

Verificar Rate Limit

Payment payment = Payment.creator()
    .setCustomer(cliente.getId())
    .setBillingType(BillingType.PIX)
    .setDueDate(new Date())
    .setValue(Money.create(new BigDecimal("100.00")))
    .create();

RateLimit rateLimit = payment.getRateLimit();
System.out.println("Requisições restantes: " + rateLimit.getRemaining());
System.out.println("Limite total: " + rateLimit.getLimit());
System.out.println("Reseta em: " + rateLimit.getReset());

🛡️ Boas Práticas

1. Use Variáveis de Ambiente

Nunca exponha suas chaves de API no código:

String apiKey = System.getenv("ASAAS_API_KEY");
Asaas.init(apiKey);

2. Trate Erros Adequadamente

try {
    Payment payment = Payment.creator()
        .setCustomer("cus_invalid")
        .setBillingType(BillingType.PIX)
        .setDueDate(new Date())
        .setValue(Money.create(new BigDecimal("100.00")))
        .create();
} catch (AsaasException e) {
    System.err.println("Erro ao criar cobrança: " + e.getMessage());
    // Registrar erro, notificar equipe, etc.
}

3. Valide Dados de Entrada

String cpf = "123.456.789-00";
String cpfLimpo = cpf.replaceAll("[^0-9]", "");

if (cpfLimpo.length() == 11) {
    CustomerAccount cliente = CustomerAccount.creator()
        .setCpfCnpj(cpfLimpo)
        .setName("Cliente")
        .create();
}

4. Use Referências Externas

Mantenha sincronização com seu sistema:

CustomerAccount cliente = CustomerAccount.creator()
    .setName("João Silva")
    .setCpfCnpj("12345678900")
    .setExternalReference("CLIENTE_ID_123") // ID do seu sistema
    .create();