Skip to main content

alazoorims

مكتبة Python للتعامل مع REST API لمنصة IMS SMS.

تغلّف المكتبة كل نقاط النهاية المتاحة في اللوحة، وتضيف طبقتين لتسهيل الاستخدام:

· حاسبة السعر التلقائية (Auto Calculator) — تحسب سعر العميل انطلاقاً من سعرك ونسبة ربحك. · تسهيل التواريخ (Date Convenience) — تقبل صيغاً مبسّطة للتواريخ بدل كتابة ISO 8601 كاملاً.


الميزات

الميزة الوصف تغطية كاملة كل نقاط النهاية: الرسائل، النطاقات، الأرقام، CDRs، العملاء، التعيين والإلغاء. وضعان للبيانات dict (افتراضي) أو dataclasses (as_dataclass=True) مع Decimal للأموال. حاسبة تلقائية auto_margin_percent لحساب client_payout_rate تلقائياً بتقريب آمن للأعلى. تسهيل التواريخ "01", "08-01", "2026-08-01", "today", "7d", datetime, date. احترام حدود المعدل إعادة محاولة تلقائية على 429 باستخدام Retry-After. ترقيم تلقائي iter_all() يجلب كل الصفحات دون إدارة nextCursor يدوياً. أخطاء واضحة هرمية استثناءات كاملة تربط أكواد أخطاء الـ API بأسماء Python. توقيت UTC صارم كل حسابات التواريخ بتوقيت غرينتش، لا علاقة بتوقيت جهازك.


التثبيت

pip install alazoorims

لبيئة التطوير (اختبارات + أدوات):

pip install "alazoorims[dev]"

المتطلب الوحيد: Python 3.9 أو أحدث.


البدء السريع

from alazoorims import IMSClient

# 1) أنشئ العميل — يقرأ التوكن من متغير البيئة IMS_API_TOKEN
client = IMSClient()

# 2) آخر 10 رسائل
messages = client.messages.list(limit=10)
print(messages["count"])

# 3) آخر 7 أيام من سجلات الفواتير (CDRs)
cdrs = client.cdrs.list(from_="7d")

# 4) كل أرقامك (تلقائياً عبر كل الصفحات)
for number in client.numbers.iter_all(as_dataclass=True):
    print(number.number, number.range, number.payout_rate)

# 5) عيّن رقماً لعميل مع حساب السعر تلقائياً بنسبة ربح 20%
client2 = IMSClient(auto_margin_percent=20)
client2.numbers.assign(client="acme_uk", numbers=["447700900123"])

المصادقة

هناك طريقتان لتمرير التوكن:

  1. عبر متغير البيئة (الأفضل):
export IMS_API_TOKEN="your-token-here"
client = IMSClient()  # يقرأ IMS_API_TOKEN تلقائياً
  1. مباشرة في الكود (للسكربتات السريعة):
client = IMSClient(token="your-token-here")

تحذير أمني: لا تضع التوكن في الكود المرفوع إلى Git، ولا تشاركه في محادثة أو تذكرة دعم. التوكن يمنح نفس صلاحيات حسابك بالكامل.

تخصيص العنوان والسلوك:

client = IMSClient(
    token="...",
    base_url="https://imssms.org",  # عنوان لوحتك
    timeout=30.0,                    # ثوان لكل طلب
    max_retries=3,                   # محاولات إعادة عند 429/الشبكة
)

استخدم الكائن كـ Context Manager لضمان إغلاق الاتصال:

with IMSClient() as client:
    client.messages.list()

الموارد

الرسائل — client.messages

# آخر 10 رسائل (افتراضي)
client.messages.list()

# فلترة بفترة (استخدم صيغ التاريخ المبسطة)
client.messages.list(from_="2026-08-01", to="2026-08-31", limit=100)

# فلترة برقم مستقبِل أو مُرسِل
client.messages.list(number="447700900123", cli="WhatsApp")

# وضع dataclass
for msg in client.messages.list(limit=50, as_dataclass=True):
    print(msg.time, msg.number, msg.payout, msg.status)

المعاملات: from_, to, number, cli, limit, as_dataclass.

ملاحظة: بدون أي فلترة، الـ API يعيد آخر 10 رسائل فقط.

حالات الرسالة: pending, cleared, inactive, cli_blocked, cli_limit, range_limit, number_daily, number_weekly. أي حالة غير pending أو cleared تعني أن الرسالة لم تدر شيئاً.


النطاقات — client.ranges

for rng in client.ranges.list(as_dataclass=True):
    print(rng.name, rng.prefix, rng.currency, rng.active)
    for rate in rng.rates:
        print(f"  cycle={rate.invoice_cycle_days}d "
              f"delay={rate.payout_delay_days}d "
              f"payout={rate.payout_rate}")

ملاحظات:

· rates هي أسعارك أنت فقط — أسعار المنبع لا تُكشف أبداً. · خطط لا تملك أرقاماً عليها تظهر بسعر 0. · unassignedNumbers تظهر لحسابات الوكلاء فقط. · نقطة النهاية تتطلب Extended API.


الأرقام — client.numbers

عرض الصفحات:

# صفحة واحدة (أنت تدير المؤشر)
page = client.numbers.list(limit=100)
print(page["count"], page.get("nextCursor"))

# كل الصفحات تلقائياً
for num in client.numbers.iter_all(limit=500, as_dataclass=True):
    print(num.number, num.client)

# بحث بجزء من الرقم
client.numbers.list(search="4477")

المعاملات: range_id, assigned, client_id, search, after, limit, as_dataclass.

تعيين أرقام لعميل (وكلاء فقط):

# بسعر يدوي
client.numbers.assign(
    client="acme_uk",
    numbers=["447700900123", "447700900124"],
    client_payout_rate="0.0100",
)

# بحساب تلقائي (انظر قسم الحاسبة)
client.numbers.assign(
    client="acme_uk",
    numbers=["447700900123"],
    auto_margin_percent=20,
)

إلغاء التعيين:

client.numbers.unassign(numbers=["447700900123"])

ملاحظات مهمة:

· client_payout_rate مطلوب إن لم تُفعّل الحاسبة. "لا يربح شيئاً" يُكتب "0". · الحد الأقصى 1000 رقم لكل نداء. · الأرقام المعيّنة لعميل آخر تُنقل تلقائياً وتُحتسب في reassigned. · الإلغاء لا يسترجع أرباحاً سابقة. · لا يمكن إضافة أرقام جديدة عبر الـ API — تُضاف من اللوحة أو بواسطة مشغّل المنصة.


سجلات الفواتير — client.cdrs

أكثر تفصيلاً من /messages: يحمل بادئة النطاق، العملة، ربحك، وربح العميل (للوكلاء)، ووقت التسوية.

# آخر 7 أيام
client.cdrs.list(from_="7d")

# شهر كامل
client.cdrs.list(from_="2026-08-01", to="2026-08-31", limit=100)

# تصفية بنطاق محدد + وضع dataclass
for cdr in client.cdrs.list(
    from_="2026-08-01",
    to="2026-08-31",
    range_id="0f8b4a1e-6c2d-4a77-9d31-2b5e8c9a4f10",
    as_dataclass=True,
):
    print(cdr.number, cdr.payout, cdr.client_payout, cdr.cleared_at)

ملاحظات:

· clientPayout تظهر لحسابات الوكلاء فقط. · clearedAt تكون None حتى تُسوَّى الفاتورة. · تتطلب Extended API.


العملاء — client.clients

للحسابات الوكيلة فقط. تتطلب Extended API.

# عرض العملاء
for cli in client.clients.list(as_dataclass=True):
    print(cli.username, cli.name, cli.can_use_api, cli.disabled)

# إنشاء عميل — توليد كلمة مرور تلقائياً
created = client.clients.create(
    username="acme_uk",
    name="Acme UK",
    email="ops@acme.example",
    can_use_api=True,
)
print(created["password"])  # تظهر مرة واحدة فقط!

# إنشاء عميل بكلمة مرور تختارها (12 حرفاً على الأقل)
client.clients.create(
    username="acme_uk_2",
    password="a-very-long-password-123",
    can_use_api=True,
    can_view_ranges=True,
)

مهم: إذا حذفت password، يولّد الـ API واحداً ويعيده مرة واحدة. احفظه فوراً — لا يمكن استرجاعه لاحقاً.

المعاملات: username, password, name, email, contact, can_use_api, can_view_ranges, can_use_extended_api.


الحاسبة التلقائية (Auto Calculator)

بدل كتابة سعر العميل يدوياً، دَع المكتبة تقرأ payoutRate الخاص بكل رقم وتطبّق نسبتك:

client_rate = agent_rate x (1 - margin / 100)

التقريب دائماً للأعلى إلى 4 خانات عشرية باستخدام Decimal (لتفادي فقدان الدقة).

مثال

سعرك (Agent Rate) نسبتك (Margin) سعر العميل 0.0125 20% 0.0100 0.0125 7% 0.0117 (تقريب للأعلى من 0.011625) 0.0100 20% 0.0080

ثلاث طرق للاستخدام

  1. على مستوى العميل (تُطبَّق على كل assign):
client = IMSClient(auto_margin_percent=20)
client.numbers.assign(client="acme_uk", numbers=["447700900123"])
# clientPayoutRate = "0.0100"
  1. على مستوى النداء (يتجاوز الافتراضي مع تحذير):
client = IMSClient(auto_margin_percent=50)
client.numbers.assign(
    client="acme_uk",
    numbers=["447700900123"],
    auto_margin_percent=20,  # يفوز + warnings.warn
)
  1. دالة مستقلة بدون اتصال بالـ API:
from alazoorims import calculate_client_rate

calculate_client_rate("0.0125", margin_percent=20)  # "0.0100"
calculate_client_rate("0.0125", margin_percent=7)   # "0.0117"
calculate_client_rate("0.0100", margin_percent=20)  # "0.0080"

قواعد الأمان

· لا يمكن تمرير client_payout_rate وauto_margin_percent في نفس النداء -> ValueError. · إذا فُعّلت الحاسبة العامة ومرّرت نسبة محلية -> المحلية تفوز + تحذير. · إذا لم تُفعّل الحاسبة ولم تمرّر client_payout_rate -> ValueError. · النسبة يجب أن تكون بين 0 و100 (حصرياً). · agent_rate يجب أن يكون موجباً. · النتيجة النهائية لا تتجاوز أبداً agent_rate.


تسهيل التواريخ (Date Convenience)

بدل كتابة ISO 8601 كاملاً، تقبل المكتبة صيغاً مبسّطة وتُكمل الوقت تلقائياً.

الصيغ المدعومة

المدخل التفسير "2026-08-01T00:00:00Z" ISO كامل — يُمرَّر كما هو "2026-08-01T14:30" ISO بدون Z — يُفترض UTC "2026-08-01 14:30" نفس السابق مع مسافة "2026-08-01" تاريخ كامل — يُطبَّق حد اليوم "08-01" شهر-يوم من السنة الحالية (UTC) "01" يوم من الشهر الحالي (UTC) "today" اليوم UTC "yesterday" أمس UTC "7d" آخر 7 أيام (من الآن - 7 أيام حتى الآن) datetime(...) كائن Python date(...) كائن Python None لا فلترة

قاعدة حدّ اليوم

المعامل الوقت الافتراضي المضاف from_ T00:00:00Z to T23:59:59Z

أمثلة

كل السطور التالية متكافئة (بفرض اليوم 2026-09-18 UTC):

client.messages.list(from_="01", to="18")
client.messages.list(from_="09-01", to="09-18")
client.messages.list(from_="2026-09-01", to="2026-09-18")
client.messages.list(from_="2026-09-01T00:00:00Z",
                    to="2026-09-18T23:59:59Z")
from datetime import date, datetime

client.cdrs.list(from_=date(2026, 8, 1), to=date(2026, 8, 31))
client.cdrs.list(from_=datetime(2026, 8, 1, 12, 0))
client.cdrs.list(from_="7d")
client.messages.list(from_="today", to="today")

التوقيت: UTC فقط

الشهر والسنة الحاليان يُحسبان من datetime.now(timezone.utc) — بتوقيت غرينتش، لا بتوقيت جهازك. إذا كنت في اليمن (UTC+3) ونفّذت السكربت الساعة 02:00 صباحاً، المكتبة تعرف أن اليوم بتوقيت UTC هو اليوم السابق.

استخدام الدالة مباشرة

from alazoorims.utils import normalize_datetime

normalize_datetime("01")                    # "2026-09-01T00:00:00Z"
normalize_datetime("01", end_of_day=True)   # "2026-09-01T23:59:59Z"
normalize_datetime("7d")                    # "2026-09-11T14:22:00Z"
normalize_datetime("today")                 # "2026-09-18T00:00:00Z"

الأخطاء

· تاريخ غير موجود ("02-30", "32") -> ValueError برسالة واضحة. · صيغة غير معروفة -> ValueError مع قائمة الصيغ المدعومة.


الأخطاء

كل استثناء يورث من IMSAPIError، فـ except IMSAPIError يمسك كل شيء.

IMSAPIError (القاعدة)
├── IMSAuthError          <- missing_token / invalid_token (401)
├── IMSPermissionError    <- module_disabled / extended_api_disabled (403)
├── IMSRateLimitError     <- rate_limited (429) + retry_after
├── IMSValidationError    <- invalid_request / too_many_numbers / ...
├── IMSNotFoundError      <- not_found (404)
├── IMSServerError        <- internal_error (500) + error_id
└── IMSNetworkError       <- أخطاء الشبكة (timeout, DNS, connection)

مثال

from alazoorims import (
    IMSAPIError,
    IMSAuthError,
    IMSPermissionError,
    IMSRateLimitError,
    IMSServerError,
    IMSValidationError,
)

try:
    client.numbers.assign(
        client="acme_uk",
        numbers=["447700900123"],
        client_payout_rate="0.0100",
    )
except IMSAuthError:
    print("التوكن غير صالح.")
except IMSPermissionError as exc:
    print(f"الميزة غير مفعّلة: {exc.error_code}")
except IMSValidationError as exc:
    print(f"طلب مرفوض: {exc.error_code}")
except IMSRateLimitError as exc:
    print(f"تجاوزت الحد — أعد المحاولة بعد {exc.retry_after} ثانية")
except IMSServerError as exc:
    print(f"خطأ من الخادم — error_id={exc.error_id}")
except IMSAPIError as exc:
    print(f"خطأ آخر: {exc.error_code}  payload={exc.payload}")

حدود المعدل (Rate Limits)

الـ API يفرض نافذتين لكل رمز:

· قصيرة: طلب واحد كل ثانية. · طويلة: 40 طلباً كل دقيقة.

القيد يُحتسب لكل نقطة نهاية على حدة، فلا يؤثر messages على numbers.

المكتبة تتعامل مع 429 تلقائياً:

  1. تقرأ Retry-After من الترويسة أو retryAfterSeconds من الجسم.
  2. تنتظر المدة.
  3. تعيد المحاولة حتى max_retries (افتراضياً 3).

إن نفدت المحاولات، يرفع IMSRateLimitError مع retry_after.


الأمثلة

مجلد Examples/ يحتوي 12 ملفاً جاهزاً للتشغيل:

الملف الموضوع

01 01_messages.py قراءة الرسائل 02 02_ranges.py النطاقات والأسعار 03 03_numbers_list.py عرض الأرقام + الترقيم التلقائي 04 04_numbers_assign.py تعيين بسعر يدوي 05 05_numbers_assign_auto.py الحاسبة التلقائية 06 06_numbers_unassign.py إلغاء التعيين 07 07_cdrs.py سجلات الفواتير 08 08_clients.py إدارة العملاء 09 09_dataclass_mode.py وضع dataclass في كل الموارد 10 10_error_handling.py معالجة الأخطاء 11 11_date_convenience.py صيغ التواريخ 12 12_date_shortcuts.py today / yesterday / Nd

قبل التشغيل:

export IMS_API_TOKEN="your-token-here"
python Examples/01_messages.py

الترخيص

MIT — انظر ملف LICENSE.

Metadata

Release files for alazoorims 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for alazoorims 1.0.0
File Size Uploaded Provenance Actions
alazoorims-1.0.0.tar.gz 33.8 kB Without provenance Details for alazoorims-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for alazoorims 1.0.0
File Interpreter ABI Platform Actions
alazoorims-1.0.0-py3-none-any.whl Python 3 none any Details for alazoorims-1.0.0-py3-none-any.whl

Total release size: 55.1 kB

Release files / alazoorims-1.0.0.tar.gz

Download URL alazoorims-1.0.0.tar.gz
Size 33.8 kB
Tags Source
SHA-256 checksum
How to use checksums
694a6174cb01c81942bd5c5c640c40c00c6e565586ca1994a9bbe91d67c2c1ff
BLAKE2b-256 checksum
How to use checksums
bb4a1acd7385b17888b129729cd1836499d127debd7283255a87e2318821d027
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.4

Release files / alazoorims-1.0.0-py3-none-any.whl

Download URL alazoorims-1.0.0-py3-none-any.whl
Size 21.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9f08d5940d49bca658d07307671421f0e9361a87bd09e9c9af2e85669736981d
BLAKE2b-256 checksum
How to use checksums
bc72edd4cf097f408e8f9ca8eb7edda1a87ffd59e72278b9c35f4d7f073f968e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.4

Security for alazoorims 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page