Metadata-Version: 2.4
Name: kambasms
Version: 2.0.0
Summary: SDK oficial da KambaSMS para SMS, OTP, Email, Notify e Transactions
Author-email: KambaSMS <support@kambasms.ao>
License: MIT
Project-URL: Homepage, https://github.com/FranciiscoCampos170/kamba_sms_python_sdk
Project-URL: Repository, https://github.com/FranciiscoCampos170/kamba_sms_python_sdk
Project-URL: Issues, https://github.com/FranciiscoCampos170/kamba_sms_python_sdk/issues
Keywords: sms,angola,kambasms,api,messaging
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# KambaSMS Python SDK

SDK oficial, tipado e sem dependências externas para SMS, OTP, Verify, Lookup, Notify, Email e Transactions.

Requer Python 3.8 ou superior.

## Instalação

```bash
pip install kambasms
```

## Configuração

```python
import os
from kambasms import KambaSMS

client = KambaSMS(api_key=os.environ["KAMBA_API_KEY"])
```

A URL padrão é `https://api.kambasms.ao`. Também podes definir `base_url` e `timeout` no construtor.

## SMS e OTP

```python
sms = client.sms.send(
    to="+244923456789",
    text="O seu pedido foi recebido.",
    idempotency_key="order:123:sms",
)

otp = client.otp.send("+244923456789", sender_id="KAMBA")
result = client.otp.verify("+244923456789", "123456")
```

Também estão disponíveis `send_bulk`, `schedule`, `list_scheduled`, `cancel_scheduled`, `list_bulk` e `get_bulk`.

## Verify

Verify gere a sessão completa de verificação: código, expiração, tentativas, reenvio e estado.

```python
session = client.verify.start(
    "+244923456789",
    metadata={"customer_id": "123"},
    idempotency_key="verify:customer:123",
)

result = client.verify.check(session["verification_id"], "123456")
```

Usa `client.verify.list()`, `get()`, `events()`, `stats()` e `resend()` para acompanhar as verificações.

## Lookup

```python
number = client.lookup.lookup("923 456 789")
batch = client.lookup.bulk(["923456789", "+244933123456"])
```

A operadora devolvida é uma estimativa pelo prefixo, não uma confirmação em tempo real.

## Notify

A chave API precisa do scope `notify`.

```python
client.notify.create_template(
    key="appointment_reminder",
    name="Lembrete",
    body="Olá {{name}}, a sua consulta está marcada para {{date}}.",
)

client.notify.send(
    to="+244923456789",
    template_key="appointment_reminder",
    variables={"name": "Ana", "date": "10/10 às 09:00"},
    idempotency_key="appointment:123:reminder",
)
```

## Kamba Email

Email usa volume próprio, separado dos créditos SMS. Em produção, adiciona e verifica um domínio. A chave API precisa do scope `email`.

```python
domain = client.email.create_domain("example.ao")
client.email.verify_domain(domain["id"])

client.email.send(
    to="cliente@example.com",
    domain_id=domain["id"],
    from_local="alertas",
    from_name="Minha Empresa",
    subject="Pedido recebido",
    html="<p>O pedido <strong>#123</strong> foi recebido.</p>",
    idempotency_key="order:123:email",
)
```

O recurso inclui templates, renderização, Sandbox e bulk de até 500 destinatários por pedido. Os limites efetivos dependem do plano.

## Kamba Transactions

Transactions recebe um evento do teu sistema e entrega comunicações por SMS e/ou email. Não processa pagamentos, cartões ou dinheiro. A chave API precisa do scope `transactions`.

```python
client.transactions.create_template(
    key="meeting_notice",
    event_type="meeting.scheduled",
    name="Reunião agendada",
    channels=["sms"],
    sms_body="A sua reunião foi agendada para {{date}}.",
)

event = client.transactions.send_event(
    event="meeting.scheduled",
    template_key="meeting_notice",
    external_reference="meeting-123",
    customer={"phone": "+244923456789"},
    data={"date": "10/10 às 09:00"},
    channels=["sms"],
    idempotency_key="meeting:123",
)
```

## Conta e ambiente de testes

```python
balance = client.account.get_balance()
history = client.account.get_history(limit=20)
stats = client.account.get_stats()
usage = client.account.get_usage()
```

Usa uma chave Sandbox para simular operações sem consumir créditos reais. As respostas podem incluir `environment`, `simulated` e `test_code`.

## Erros

```python
from kambasms import KambaAPIError, KambaValidationError

try:
    client.sms.send("923456789", "Mensagem")
except KambaValidationError as error:
    print("Dados inválidos:", error)
except KambaAPIError as error:
    print(error.status_code, error.code, error.request_id, error.details)
```

O estado `0` indica falha de rede ou timeout. O SDK não repete pedidos automaticamente: reutiliza a mesma chave de idempotência quando precisares de confirmar uma operação incerta.

Documentação: [kambasms.ao/dashboard/docs](https://www.kambasms.ao/dashboard/docs)
