> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usealpa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Python

> SDK oficial para Python — aceite pagamentos em segundos com uma integração simples

<Card title="Alpa Python SDK" icon="python" href="https://github.com/anthonymengottii/alpa-python-sdk">
  SDK oficial da Alpa para Python. Compatível com Python 3.8+.
</Card>

## Instalação

<Note>
  Este SDK ainda não está publicado no PyPI. Instale diretamente pelo GitHub:
</Note>

```bash theme={null}
pip install git+https://github.com/anthonymengottii/alpa-python-sdk.git
```

## Uso Rápido

```python theme={null}
import os
from alpa import AlpaClient

alpa = AlpaClient(api_key=os.getenv('ALPA_API_KEY'))
```

## Criar Link de Pagamento

```python theme={null}
link = alpa.payment_links.create({
    'title': 'Produto Premium',
    'amountCents': 9900,
    'description': 'Acesso vitalício',
})
```

## Resposta

```python theme={null}
{
    'id': 'lnk_abc123',
    'title': 'Produto Premium',
    'description': 'Acesso vitalício',
    'amount': 9900,
    'currency': 'BRL',
    'status': 'ACTIVE',
    'slug': 'abc123',
    'createdAt': '2026-04-08T00:00:00.000Z',
    'updatedAt': '2026-04-08T00:00:00.000Z'
}
```

A URL do checkout é montada a partir do `slug`:

```python theme={null}
checkout_url = alpa.payment_links.get_checkout_url(link['slug'])
# https://checkout.usealpa.com/pay/abc123
```

## Criar Transação PIX

```python theme={null}
tx = alpa.transactions.create({
    'product': 'Curso Python',
    'paymentMethod': 'PIX',
    'amountCents': 19900,
    'clientName': 'João Silva',
    'clientEmail': 'joao@example.com',
    'clientDocument': '12345678900',
})

print(tx['pixCopiaECola'])
```

## Validar Cupom

```python theme={null}
result = alpa.coupons.validate(
    code='DESCONTO10',
    amount_cents=19900,
)

# result['valid'], result['discountCents'], result['finalAmountCents']
```

## Validação de Webhooks

```python theme={null}
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
    is_valid = alpa.verify_webhook_signature(
        payload=request.data,
        signature=request.headers.get('x-webhook-signature', ''),
        secret=os.getenv('ALPA_WEBHOOK_SECRET'),
    )

    if not is_valid:
        return jsonify(error='Assinatura inválida'), 401

    event = request.json
    return jsonify(received=True)
```

## Tratamento de Erros

```python theme={null}
from alpa import AlpaValidationError, AlpaError

try:
    tx = alpa.transactions.create({ ... })
except AlpaValidationError as e:
    print('Dados inválidos:', e)
except AlpaError as e:
    print(f'Erro {e.status_code}:', e)
```