integrax 1.0.0

Send SMS, RCS & OTP messages via API. Bulk SMS, OTP verification, phone number lookup.

integrax

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

• Usa httpx como HTTP client
• Type hints completos (PEP 561 — py.typed)
• Python 3.9+

Obtendo seu token

1. Crie uma conta gratuita em 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 e solicite a liberação.

Instalação

pip install integrax

Quick start

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:

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

Configuração

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

SMS

# 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:

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

OTP

Duas chamadas: enviar código e verificar.

# 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)

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

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

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

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

Consultas

Por CPF

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

Por telefone

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

Telefone premium (dados enriquecidos)

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

Números internacionais

• Para números de outros países, insira + na frente do número (ex: [phone]).
• 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

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