Asaas Django SDK

SDK para integração com a API do Asaas em projetos Django.
Fornece funcionalidades como:

• criação de clientes
• geração de cobranças PIX
• geração de PIX com split para múltiplas carteiras
• criação de eventos de pagamento
• consulta de eventos
• suporte a webhooks (pagamento aprovado)

Este pacote permite que qualquer projeto Django integre rapidamente com o Asaas sem duplicar lógica.

---

📦 Instalação

Instale diretamente pelo GitHub:

pip install git+https://github.com/TimeNovaData/modulo_asaas.git

⚙️ Configuração no Django

Edite o seu settings.py e adicione:

INSTALLED_APPS = [
    ...
    "asaas_django",
]

Configure sua chave do Asaas:

ASAAS_API_KEY = "sua_chave_api"
ASAAS_ENV = "sandbox"  # ou "production"

🧱 Models necessários (no SEU projeto Django)

O SDK não possui models. Você deve criar os seguintes modelos no seu projeto Django:

1. Configuração do Gateway (opcional — fallback entre MP e Asaas ou outro)

class PaymentGatewayConfig(models.Model):
    PRINCIPAL_CHOICES = [
        ("asaas", "Asaas"),
        ("mercado_pago", "Mercado Pago"),
        ("outro_getway", "Outro GetWay")
    ]

    principal_gateway = models.CharField(
        max_length=20, choices=PRINCIPAL_CHOICES, default="asaas"
    )

2. Carteiras (Wallets) para divisão de pagamentos

class AsaasWallet(models.Model):
    nome = models.CharField(max_length=100)
    wallet_id = models.CharField(max_length=100)

3. Splits (inline) — múltiplos splits por carteira

class AsaasSplit(models.Model):
    wallet = models.ForeignKey(AsaasWallet, on_delete=models.CASCADE)
    percentual = models.DecimalField(max_digits=5, decimal_places=2)

Admin inline

class SplitInline(admin.TabularInline):
    model = AsaasSplit
    extra = 1

@admin.register(AsaasWallet)
class WalletAdmin(admin.ModelAdmin):
    inlines = [SplitInline]

🚀 Funcionalidades do SDK

O SDK expõe funções principais diretamente no pacote:

from asaas_django import (
    criar_cliente,
    criar_pix,
    criar_pix_com_split,
    buscar_cliente_por_email
)

Lista completa

Função	Descrição
criar_cliente()	Cria um cliente no Asaas
buscar_cliente_por_email()	Busca cliente pelo email
criar_pix()	Cria um pagamento PIX
criar_pix_com_split()	Cria PIX com divisão entre várias carteiras
criar_evento_pagamento()	Cria um evento de pagamento
obter_evento()	Consulta um evento do Asaas
listar_pix_transactions()	Lista transações PIX
validar_webhook()	Valida payload recebido via webhook
evento_aprovado()	Retorna True se o pagamento foi aprovado

🧪 Como testar no Django (shell)

Ative seu ambiente virtual e rode:

python manage.py shell

Teste criação de cliente:

from asaas_django import criar_cliente
criar_cliente("Caio Teste", "09972781720") # CPF precisa ser valido

Gerar PIX com split automático carregado do banco:

from pagamentos.services import gerar_pix_split
gerar_pix_split("cus_123", 100.00) # cus_123 é o customer_id do cliente

💵 Serviço para gerar PIX com split (no SEU projeto Django)

Crie no seu app:

def gerar_pix_split(customer_id, value, descricao="Pagamento"):
    splits = [
        {
            "walletId": s.wallet.wallet_id,
            "percentualValue": float(s.percentual)
        }
        for s in AsaasSplit.objects.all()
    ]

    from asaas_django import criar_pix_com_split
    return criar_pix_com_split(customer_id, value, splits, descricao)

📬 Webhook de pagamento aprovado

Crie um endpoint no seu Django:

@api_view(["POST"])
def webhook_asaas(request):
    payload = validar_webhook(request)

    if evento_aprovado(payload):
        pagamento = payload["payment"]
        processar_pagamento_aprovado(pagamento)

    return Response({'received': True}, status=status.HTTP_200_OK)

Serviço de processamento:

def processar_pagamento_aprovado(pagamento):
    payment_id = pagamento["id"]
    valor_liquido = pagamento["netValue"]
    splits = pagamento.get("split", [])

    # Aqui você trata o pagamento:
    # atualizar pedido, liberar acesso, etc.

📡 URL pública do webhook

Adicione no seu urls.py:

path("webhook/asaas/", webhook_asaas, name="webhook_asaas"),

📁 Estrutura do SDK

asaas_django/
├── __init__.py
├── apps.py
├── client.py
├── customers.py
├── exceptions.py
├── payments.py
├── pix.py
├── split.py
├── transactions.py
└── webhooks.py