Metadata-Version: 2.4
Name: integrax
Version: 1.0.0
Summary: Send SMS, RCS & OTP messages via API. Bulk SMS, OTP verification, phone number lookup.
Author-email: Integrax <contato@integrax.lat>
License-Expression: MIT
Project-URL: Homepage, https://integrax.lat
Project-URL: Documentation, https://integrax.lat/desenvolvedores
Project-URL: Repository, https://github.com/integrax-lat/integrax-python
Project-URL: Create Account, https://integrax.app
Keywords: sms,send-sms,bulk-sms,sms-api,rcs,otp,otp-verification,verify-phone,phone-verification,messaging,cpaas,text-message,integrax,api
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Classifier: Topic :: Communications
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.25.0
Dynamic: license-file

# integrax

SDK oficial da Integrax para Python — SMS, RCS, OTP e consultas via API REST.

- Usa [httpx](https://www.python-httpx.org/) como HTTP client
- Type hints completos (PEP 561 — `py.typed`)
- Python 3.9+

## Obtendo seu token

1. Crie uma conta gratuita em [integrax.app](https://integrax.app)
2. Após o cadastro, acesse o menu **API** e crie um token

Pronto, você já pode integrar!

> Se receber `MESSAGE_NOT_ALLOWED`, entre em contato com o suporte pelo [WhatsApp](https://wa.me/551132808396) e solicite a liberação.

## Instalação

```bash
pip install integrax
```

## Quick start

```python
from integrax import Integrax

ix = Integrax("seu-token-aqui")

# Enviar SMS
res = ix.sms.send(["5511999999999"], "Pedido #4821 confirmado ✓")
print(res["data"][0]["messageId"])  # "82816396"
```

Ou com context manager:

```python
with Integrax("seu-token") as ix:
    ix.sms.send(["5511999999999"], "Olá!")
```

## Configuração

```python
ix = Integrax(
    "seu-token",
    base_url="https://sms.aresfun.com",  # padrão
    timeout=15.0,                         # padrão: 30s
)
```

## SMS

```python
# Envio simples (usa shortcode padrão da conta)
res = ix.sms.send(["5511999999999", "5521888888888"], "Sua mensagem aqui")

# Com shortcode customizado
res = ix.sms.send(["5511999999999"], "Olá!", from_="29094")

# res["code"] == "SMS_SENT"
# res["data"][0]["status"] == "SENT_TO_OPERATOR"
# res["data"][0]["messageId"] == "82816396"
```

### DLR (webhook)

Configure seu webhook para receber o status de entrega:

```python
# Payload recebido no seu endpoint
{
    "message_id": "82816396",
    "status": "DELIVRD",  # DELIVRD | EXPIRED | REJECTD | UNDELIV
    "number": "5511999999999"
}
```

## OTP

Duas chamadas: enviar código e verificar.

```python
# 1. Envio mínimo (usa todos os defaults: 6 dígitos numéricos, expira em 10min)
ix.otp.send("5511999999999")

# 1b. Personalizado
ix.otp.send(
    "5511999999999",
    message_default="Use [code] pra confirmar sua conta",  # padrão: "Seu código: [code]"
    from_="29094",       # se omitido, usa o padrão da conta
    qtd_digits=5,        # padrão: 6
    with_text=True,      # alfanumérico (padrão: False = só números)
    expires_in=5,        # minutos (padrão: 10)
)

# 2. Verificar código digitado pelo usuário
res = ix.otp.verify("1MP5L", "5511999999999")
if res["status"] == "verified":
    print("Código válido!")
```

## RCS

### BASIC (só texto)

```python
ix.rcs.send(
    ["5511999999999"],
    "Olá! Mensagem RCS básica.",
    "IntegraX",
    rcs_type="BASIC",
)
```

### RICH (card com mídia e botões)

```python
ix.rcs.send(
    ["5511999999999"],
    "Confira nossa oferta!",
    "IntegraX",
    rcs_message={
        "card": {
            "title": "Black Friday",
            "description": "Até 60% OFF em todos os produtos.",
            "media": {
                "file": {"url": "https://exemplo.com/banner.png"},
                "height": "MEDIUM",
            },
            "suggestions": [
                {
                    "type": "OPEN_URL",
                    "text": "Ver ofertas",
                    "url": "https://exemplo.com/ofertas",
                    "postbackData": "click_ofertas",
                }
            ],
        }
    },
)
```

## Créditos

```python
balance = ix.credits.balance()
print(balance)
```

## Consultas

### Por CPF

```python
res = ix.consult.cpf(["00000000001"], show_phone_valid=True, show_restrictions=True)
```

### Por telefone

```python
res = ix.consult.phone(["551199999999"])
```

### Telefone premium (dados enriquecidos)

```python
res = ix.consult.phone_premium(["551199999999"])
```

## Números internacionais

- Para números de outros países, insira `+` na frente do número (ex: `+34992000000`).
- Para envios internacionais, é necessário solicitar a ativação da rota através do suporte.
- Alguns países permitem `from` personalizado. Se permitido, basta informar o `from` no payload.

## Tratamento de erros

```python
from integrax import Integrax, IntegraxError

try:
    ix.sms.send(["551100000000"], "teste")
except IntegraxError as e:
    print(e.status)  # HTTP status (ex: 401, 422)
    print(e.code)    # código da API
    print(e.body)    # corpo completo da resposta
```

## Licença

MIT
