تكامل SDK Python - OneClickDz Flexy API

نظرة عامة

يوفر SDK Navio Python واجهة نظيفة وأصيلة لدمج مدفوعات Navio في تطبيقات Python الخاصة بك. مبني باستخدام تلميحات أنواع Python 3.8+ وdataclasses لأفضل تجربة للمطورين.

API أصيل بـ Python

واجهة نظيفة مع تلميحات أنواع كاملة وdataclasses

آمن من حيث الأنواع

تعليقات توضيحية كاملة مع dataclasses وenums

التحقق من المدخلات

التحقق من جانب العميل للحصول على تغذية راجعة سريعة للأخطاء

اعتمادات محدودة

يتطلب فقط حزمة requests

المتطلبات

Python 3.8 أو أحدث
pip

التثبيت

قم بالتثبيت عبر pip:

pip install ocpay-python-sdk

أو قم بالتثبيت من المصدر:

git clone https://github.com/oneclickdz/ocpay-python-sdk.git
cd ocpay-python-sdk
pip install -e .

البدء السريع

1. تهيئة SDK

from ocpay import OCPay

ocpay = OCPay("your-api-access-token")

خزّن مفتاح API الخاص بك في متغيرات البيئة، ولا تضعه مباشرة في الكود المصدري.

2. إنشاء رابط دفع

from ocpay import OCPay, FeeMode
from ocpay.types import ProductInfo, CreateLinkRequest

ocpay = OCPay("your-api-key")

request = CreateLinkRequest(
    product_info=ProductInfo(
        title="Premium Subscription",
        amount=5000,  # Amount in DZD (500–500,000)
        description="Monthly access to all premium features",
    ),
    fee_mode=FeeMode.NO_FEE,
    success_message="Thank you for your purchase!",
    redirect_url="https://yourstore.com/success?orderId=12345",
)

response = ocpay.create_link(request)

# Share this URL with your customer
print("Payment URL:", response.payment_url)

# Save this reference for tracking
print("Payment Reference:", response.payment_ref)

3. التحقق من حالة الدفع

from ocpay import OCPay

ocpay = OCPay("your-api-key")

status = ocpay.check_payment("OCPL-A1B2C3-D4E5")

if status.is_confirmed():
    print("Payment confirmed!")
    if status.transaction_details:
        print(f"Amount: {status.transaction_details.amount} DZD")
elif status.is_pending():
    print("Payment still pending...")
elif status.is_failed():
    print(f"Payment failed: {status.message}")

مثال تجارة إلكترونية كامل

تدفق طلب تجارة إلكترونية كامل

from ocpay import (
    OCPay,
    FeeMode,
    ValidationException,
    ApiException,
)
from ocpay.types import ProductInfo, CreateLinkRequest

# Initialize SDK
ocpay = OCPay("your-api-key")

# Step 1: Create payment link for your order
order_id = "ORD-12345"
response = ocpay.create_link(CreateLinkRequest(
    product_info=ProductInfo(
        title=f"Order #{order_id}",
        amount=8000,
        description=f"Payment for order #{order_id}",
    ),
    fee_mode=FeeMode.NO_FEE,
    success_message=f"Thank you! Your order #{order_id} is being processed.",
    redirect_url=f"https://yourstore.com/orders/{order_id}/success",
))

# Step 2: Save payment reference to your database
print(f"Payment URL: {response.payment_url}")
print(f"Payment Ref: {response.payment_ref}")

# Step 3: Check payment status (in webhook or polling job)
status = ocpay.check_payment(response.payment_ref)

if status.is_confirmed():
    print("✅ Payment confirmed - fulfilling order")
elif status.is_failed():
    print("❌ Payment failed")
else:
    print("⏳ Payment is pending")

مرجع API

فئة Navio

نقطة الدخول الرئيسية لـ SDK.

المنشئ

OCPay(access_token: str, options: ClientOptions = None)

access_token

string

مطلوب

رمز الوصول إلى API OneClickDz الخاص بك.

options

ClientOptions

إعداد اختياري للعميل.

إظهار خصائص ClientOptions

timeout

int

مهلة الطلب بالثواني. الافتراضي: 30.

base_url

string

URL أساسي مخصص، يُستخدم بشكل رئيسي للاختبار.

headers

dict

رؤوس إضافية لتضمينها في كل طلب.

مثال:

from ocpay import OCPay, ClientOptions

ocpay = OCPay("your-api-key", options=ClientOptions(timeout=60))

`create_link(request)`

ينشئ رابط دفع جديداً.

request

CreateLinkRequest

مطلوب

طلب إنشاء رابط الدفع.

إظهار خصائص CreateLinkRequest

product_info

ProductInfo

مطلوب

معلومات المنتج.

إظهار خصائص ProductInfo

title

string

مطلوب

اسم المنتج أو الخدمة (1–200 حرف).

amount

int

مطلوب

المبلغ بالدينار الجزائري (500–500,000). يجب أن يكون عدداً صحيحاً.

description

string

وصف اختياري للمنتج (حد أقصى 1000 حرف).

fee_mode

FeeMode

من يدفع رسوم المعاملات. الافتراضي: FeeMode.NO_FEE.

success_message

string

رسالة اختيارية تُعرض للعميل بعد الدفع (حد أقصى 500 حرف).

redirect_url

string

URL اختياري لإعادة توجيه العميل بعد اكتمال الدفع.

يُرجع:

payment_url

string

URL صفحة الدفع لمشاركتها مع عميلك.

payment_ref

string

كود مرجعي فريد للدفع (مثال: OCPL-A1B2C3-D4E5). احفظه لتتبع حالة الدفع.

يرفع: ValidationException (400)، UnauthorizedException (403)، ApiException

`check_payment(payment_ref)`

يتحقق من حالة دفع.

payment_ref

string

مطلوب

كود مرجعي للدفع تم إرجاعه بواسطة create_link (مثال: "OCPL-A1B2C3-D4E5").

يُرجع:

status

PaymentStatus

حالة الدفع الحالية: PENDING أو CONFIRMED أو FAILED.

message

string

رسالة حالة مقروءة للإنسان.

transaction_details

TransactionDetails

تفاصيل المعاملة المؤكدة. موجود فقط عندما يكون status هو CONFIRMED.

يرفع: NotFoundException (404)، PaymentExpiredException (410)، ApiException

Enums

FeeMode

القيمة	الوصف
`FeeMode.NO_FEE`	التاجر يدفع جميع الرسوم (الافتراضي)
`FeeMode.SPLIT_FEE`	الرسوم مقسمة 50/50 بين التاجر والعميل
`FeeMode.CUSTOMER_FEE`	العميل يدفع جميع الرسوم

PaymentStatus

القيمة	الوصف
`PaymentStatus.PENDING`	الدفع قيد التنفيذ
`PaymentStatus.CONFIRMED`	اكتمل الدفع بنجاح
`PaymentStatus.FAILED`	تم رفض الدفع أو انتهت صلاحيته أو تم إلغاؤه

فئات الاستثناء

ValidationException - HTTP 400

تُطلق عندما تكون بيانات الطلب غير صالحة (مثال: مبلغ خارج النطاق، حقول مطلوبة مفقودة).الخصائص: message، status_code، request_id، error_data

UnauthorizedException - HTTP 403

تُطلق عند فشل المصادقة. تحقق من أن مفتاح API الخاص بك صالح ونشط.الخصائص: message، status_code، request_id، error_data

NotFoundException - HTTP 404

تُطلق عندما لا يوجد مرجع الدفع.الخصائص: message، status_code، request_id، error_data

PaymentExpiredException - HTTP 410

تُطلق عند انتهاء صلاحية رابط الدفع. تنتهي صلاحية الروابط بعد 20 دقيقة من الإنشاء.الخصائص: message، status_code، request_id، error_data

ApiException - متنوعة

الاستثناء الأساسي لجميع أخطاء API الأخرى. التقطه كخيار احتياطي.الخصائص: message، status_code، request_id، error_data

معالجة الأخطاء

from ocpay import (
    OCPay,
    ApiException,
    ValidationException,
    UnauthorizedException,
    NotFoundException,
    PaymentExpiredException,
)

ocpay = OCPay("your-api-key")

try:
    response = ocpay.create_link(request)
except ValidationException as e:
    print(f"Validation error: {e.message}")
    print(f"Request ID: {e.request_id}")
except UnauthorizedException as e:
    print("Authentication failed. Check your API key.")
except NotFoundException as e:
    print(f"Not found: {e.message}")
except PaymentExpiredException as e:
    print(f"Payment expired: {e.message}")
except ApiException as e:
    print(f"API error: {e.message} (status {e.status_code})")
    print(f"Request ID: {e.request_id}")

التكامل مع الأطر

Flask
Django
FastAPI

from flask import Flask, jsonify, request
from ocpay import OCPay, FeeMode
from ocpay.types import CreateLinkRequest, ProductInfo

app = Flask(__name__)
ocpay = OCPay("your-api-key")

@app.route("/api/payment", methods=["POST"])
def create_payment():
    data = request.json
    response = ocpay.create_link(CreateLinkRequest(
        product_info=ProductInfo(
            title=data["title"],
            amount=data["amount"],
        ),
        fee_mode=FeeMode.NO_FEE,
    ))
    return jsonify({
        "payment_url": response.payment_url,
        "payment_ref": response.payment_ref,
    })

from ocpay import OCPay, FeeMode
from ocpay.types import CreateLinkRequest, ProductInfo

ocpay = OCPay(settings.OCPAY_API_KEY)

def create_order_payment(order):
    response = ocpay.create_link(CreateLinkRequest(
        product_info=ProductInfo(
            title=f"Order #{order.id}",
            amount=order.total,
        ),
        fee_mode=FeeMode.NO_FEE,
        redirect_url=f"https://yourstore.com/orders/{order.id}/success",
    ))
    order.payment_ref = response.payment_ref
    order.save()
    return response.payment_url

from fastapi import FastAPI
from ocpay import OCPay, FeeMode
from ocpay.types import CreateLinkRequest, ProductInfo

app = FastAPI()
ocpay = OCPay("your-api-key")

@app.post("/api/payment")
async def create_payment(title: str, amount: int):
    response = ocpay.create_link(CreateLinkRequest(
        product_info=ProductInfo(title=title, amount=amount),
        fee_mode=FeeMode.NO_FEE,
    ))
    return {
        "payment_url": response.payment_url,
        "payment_ref": response.payment_ref,
    }

ملاحظات مهمة

التحقق من التاجر مطلوب - أكمل التحقق من التاجر على enterprise.oneclickdz.com/profile قبل استخدام API.

حدود المبلغ - الحد الأدنى 500 دج، الحد الأقصى 500,000 دج. يجب أن تكون أعداداً صحيحة (بدون كسور عشرية).

انتهاء صلاحية الرابط - تنتهي صلاحية روابط الدفع بعد 20 دقيقة من الإنشاء. بعد انتهاء الصلاحية يصبح الحالة FAILED.

اختبار Sandbox - استخدم مفتاح API sandbox الخاص بك للاختبار. تحقق من response.payment_link.is_sandbox لتأكيد وضع الاختبار.

مرجع API

عرض نقاط نهاية API Navio

الدعم

التواصل مع فريق الدعم

GitHub

عرض الكود المصدري على GitHub

تكامل Navio

Documentation Index

​نظرة عامة

API أصيل بـ Python

آمن من حيث الأنواع

التحقق من المدخلات

اعتمادات محدودة

​المتطلبات

​التثبيت

​البدء السريع

​1. تهيئة SDK

​2. إنشاء رابط دفع

​3. التحقق من حالة الدفع

​مثال تجارة إلكترونية كامل

​مرجع API

​فئة Navio

​المنشئ

​create_link(request)

​check_payment(payment_ref)

​Enums

​FeeMode

​PaymentStatus

​فئات الاستثناء

​معالجة الأخطاء

​التكامل مع الأطر

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

مرجع API

الدعم

GitHub

نظرة عامة

المتطلبات

التثبيت

البدء السريع

1. تهيئة SDK

2. إنشاء رابط دفع

3. التحقق من حالة الدفع

مثال تجارة إلكترونية كامل

مرجع API

فئة Navio

المنشئ

`create_link(request)`

`check_payment(payment_ref)`

Enums

FeeMode

PaymentStatus

فئات الاستثناء

معالجة الأخطاء

التكامل مع الأطر

ملاحظات مهمة