للمبرمجين

توثيق الـAPI

اربط متجر المسوّق (WooCommerce أو Shopify أو أي نظام) أو نظام المورد بتحسين: المنتجات وأسعارها، وتسجيل الطلبات ومتابعتها، والمحفظة. كل الردود JSON، والمفتاح بيعمله صاحب الحساب من حسابه بعد موافقة الفريق.

رابط الـAPI الأساسي

كل الروابط تحت بتبدأ بالرابط ده.

البداية

صاحب الحساب (المسوّق أو المورد) يطلب تفعيل الربط البرمجي من صفحة «مفاتيح API» في حسابه، ويستنى موافقة الفريق.
صاحب الحساب يعمل مفتاح من نفس الصفحة ويبعتهولك.
ابعته في كل طلب في الهيدر Authorization: Bearer YOUR_API_TOKEN.
جرّب أول طلب: GET /me، لو رجعلك حسابك يبقى الربط شغال.

curl

curl "https://thseen.com/api/v1/me" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

محتاجين نتفق على

كل الطلبات والردود JSON. ابعت Accept: application/json، ومع POST و PUT Content-Type: application/json.
الفلوس نص برقمين بعد العلامة بالجنيه المصري: "125.00". الكميات والأرقام (id) أرقام صحيحة.
الطلب ليه رقمين: id (رقم صحيح، هو اللي بتحطه في الروابط زي /orders/{id})، و number الرقم المرجعي اللي على الفاتورة والبوليصة وبيشوفه العميل: نص بكود الدولة وحروف كابيتال وأرقام زي "EG-7K3P9X2Q".
الأوقات بصيغة ISO-8601 بتوقيت مصر ومعاها الفرق: "2026-10-08T13:00:33+03:00".
القوايم صفحات: ?page=2&per_page=50 (25 لو ما حددتش، وأقصى حاجة 100)، والرد فيه meta بعدد الكل وآخر صفحة.
للمزامنة: ?updated_since= بيرجعلك اللي اتغير بس من آخر مرة سألت.
رقم حاجة مش بتاعتك بيرجع 404 كأنه مش موجود.

شكل أي قائمة

{
    "data": [
        "..."
    ],
    "meta": {
        "page": 2,
        "per_page": 50,
        "total": 120,
        "last_page": 3
    }
}

الحد الأقصى للطلبات

كل مفتاح ليه 120 طلب في الدقيقة، إلا لو فريق تحسين حدّدله حد تاني . لو عديته بيرجع 429 ومعاه retry_after (بالثواني) وهيدر Retry-After: استنى المدة دي وكمّل. محتاج حد أكبر لمزامنة كتالوج كبير؟ كلّم الدعم.

مثال: 429

{
    "error": {
        "code": "rate_limited",
        "message": "طلبات كتير في دقيقة واحدة. استنى شوية وجرّب تاني.",
        "retry_after": 42
    }
}

هيدرز في كل رد

الهيدر	معناه
`X-RateLimit-Limit`	حد المفتاح ده في الدقيقة.
`X-RateLimit-Remaining`	فاضلك كام طلب في الدقيقة دي.
`Retry-After`	مع 429 بس: استنى كام ثانية قبل ما تبعت تاني.
`Idempotent-Replayed`	مع POST /orders بس: true لو الرد ده هو الرد الأول بنفس Idempotency-Key.

الأخطاء

أي خطأ بيرجع بنفس الشكل: كود ثابت تقدر تعتمد عليه في الكود، ورسالة بالعربي تقدر تعرضها، وfields لو المشكلة في حقل معين.

مثال: 422

{
    "error": {
        "code": "validation_failed",
        "message": "في بيانات ناقصة أو غلط، راجع fields.",
        "fields": {
            "phone": [
                "رقم الهاتف يجب أن يكون رقماً مصرياً صحيحاً يبدأ بـ 01 ويليه 9 أرقام."
            ]
        }
    }
}

الكود	HTTP	إمتى
`unauthenticated`	401	المفتاح مش مبعوت، أو غلط، أو اتلغى، أو انتهت مدته.
`account_inactive`	403	الحساب اتوقف أو اتحذف أو بياناته مش مكتملة. المفاتيح القديمة بتقف معاه فورًا.
`wrong_side`	403	الطلب لنوع حساب تاني (مسوّق ومورد ليهم طلبات مختلفة)، أو الحساب حساب شركة شحن.
`api_not_enabled`	403	الربط البرمجي مش مفعّل على الحساب: لسه ما اتطلبش، أو الطلب بيتراجع أو اترفض، أو الفريق وقّفه، أو إنت وقّفته. api_status فيها الحالة (none / pending / rejected / suspended / cancelled).
`forbidden_ability`	403	المفتاح مالوش الصلاحية اللي الطلب محتاجها.
`not_found`	404	الرقم مش موجود، أو تبع حساب تاني (مش بنقول أيهم).
`method_not_allowed`	405	الرابط صح بس الطريقة (GET/POST/...) غلط.
`conflict`	409	طلب متكرر: نفس رقم الطلب عندك (external_reference)، أو نفس Idempotency-Key ببيانات مختلفة، أو طلب مينفعش يتلغي.
`validation_failed`	422	في حقل ناقص أو غلط؛ الرسالة لكل حقل في fields.
`rate_limited`	429	عديت حد المفتاح في الدقيقة (120 طلب لو مالوش حد خاص)؛ استنى retry_after ثانية.
`server_error`	500	مشكلة عندنا. جرّب تاني بعد شوية.

طلب واحد مش اتنين

النت ممكن يقطع بعد ما الطلب يتسجل وقبل ما الرد يوصلك، فبرنامجك يبعته تاني. عشان ده ما يعملش طلب مكرر عندك طريقتين، واستخدم الاتنين:

external_reference: رقم الطلب في متجرك. مينفعش يتكرر على حسابك؛ لو اتبعت تاني بيرجع 409 ومعاه existing_order_id (رقم الطلب اللي اتسجل) و existing_order_number (رقمه المرجعي) بدل ما يتسجل تاني. تقدر كمان تدوّر بيه: GET /orders?external_reference=WC-10425.
هيدر Idempotency-Key: نص فريد (لحد 100 حرف) تولّده لكل طلب جديد. لو بعت نفس الطلب بنفس المفتاح خلال 24 ساعة بيرجعلك نفس الرد الأول بالظبط ومعاه الهيدر Idempotent-Replayed: true. نفس المفتاح مع بيانات مختلفة بيرجع 409. لو الطلب الأول رجع خطأ، المفتاح ما بيتحفظش وتقدر تصلّح وتبعت بيه تاني.

مثال: 409

{
    "error": {
        "code": "conflict",
        "message": "الطلب ده اتسجّل قبل كده بنفس رقم الطلب عندك (WC-10425)، رقمه عندنا EG-7K3P9X2Q.",
        "existing_order_id": 1543,
        "existing_order_number": "EG-7K3P9X2Q"
    }
}

ربحك وعمولة تحسين

سعر بيع الصنف للعميل = price (سعره عليك) + profit (ربحك اللي بتبعته في السطر). من ربحك بيتخصم 4% عمولة تحسين على الطلبات الجديدة: في الطلب هتلاقي totals.profit (ربحك) وtotals.income_tax (عمولة تحسين) وtotals.net_profit (اللي بيدخل محفظتك). كل طلب بيفضل بنسبة عمولة تحسين اللي اتسجّل بيها، وبتلاقيها في totals.income_tax_percent.

كل الطلبات

كل طلب ومعاه الصلاحية اللي المفتاح محتاجها، والمدخلات، ومثال تقدر تنسخه، والرد بالظبط زي ما هيوصلك.

GET /api/v1/me

مين صاحب المفتاح

أول طلب تجرّبه: بيرجع حسابك ونوعه (side) وصلاحيات المفتاح. بيشتغل بأي صلاحية.

مجاني: مش بيتحسب في الفاتورة.

الصلاحية: أي مفتاح.

الأخطاء المحتملة

401 unauthenticated 403 account_inactive 403 api_not_enabled 429 rate_limited 500 server_error

مثال

curl

curl "https://thseen.com/api/v1/me" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

الرد 200

JSON

{
    "data": {
        "id": 2087,
        "name": "مصنع النور للملابس",
        "store_name": null,
        "email": "you@example.com",
        "phone": "01012345678",
        "side": "supplier",
        "token": {
            "name": "متجر WooCommerce",
            "abilities": [
                "catalog:read",
                "orders:read",
                "orders:write",
                "wallet:read",
                "quotes:read",
                "quotes:write",
                "statement:read"
            ],
            "expires_at": null
        }
    }
}

GET /api/v1/categories

الأقسام

أقسام المتجر المفعّلة، عشان تربط كل منتج بقسمه عندك.

مجاني: مش بيتحسب في الفاتورة.

الصلاحية: قراءة المنتجات catalog:read

المدخلات

الاسم	فين	النوع	مطلوب	الشرح
`page`	في الرابط (?)	رقم	اختياري	رقم الصفحة، من 1.
`per_page`	في الرابط (?)	رقم	اختياري	عدد في الصفحة: 25 لو ما حددتش، وأقصى حاجة 100.

الأخطاء المحتملة

401 unauthenticated 403 account_inactive 403 api_not_enabled 403 forbidden_ability 422 validation_failed 429 rate_limited 500 server_error

مثال

curl

curl "https://thseen.com/api/v1/categories" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

الرد 200

JSON

{
    "data": [
        {
            "id": 4,
            "name": "إلكترونيات",
            "slug": "electronics",
            "parent_id": null
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 25,
        "total": 8,
        "last_page": 1
    }
}

GET /api/v1/products

المنتجات

كل اللي المتجر بيبيعه دلوقتي: المنتج وأصنافه، وسعر كل صنف عليك (price)، والسعر المقترح للبيع (من suggested_min لـ suggested_max).

بيتحسب: كل منتج مختلف بيرجع في الرد = منتج مسحوب، مرة واحدة في الشهر مهما اتكرر.

الصلاحية: قراءة المنتجات catalog:read

المدخلات

الاسم	فين	النوع	مطلوب	الشرح
`category_id`	في الرابط (?)	رقم	اختياري	منتجات قسم واحد.
`q`	في الرابط (?)	نص	اختياري	بحث في اسم المنتج.
`updated_since`	في الرابط (?)	ISO-8601	اختياري	اللي اتغير (هو أو سعر صنف فيه) من التاريخ ده: للمزامنة الدورية.
`page`	في الرابط (?)	رقم	اختياري	رقم الصفحة، من 1.
`per_page`	في الرابط (?)	رقم	اختياري	عدد في الصفحة: 25 لو ما حددتش، وأقصى حاجة 100.

الأخطاء المحتملة

401 unauthenticated 403 account_inactive 403 api_not_enabled 403 forbidden_ability 422 validation_failed 429 rate_limited 500 server_error

مثال

curl

curl "https://thseen.com/api/v1/products?updated_since=2026-10-01T00%3A00%3A00%2B03%3A00" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

الرد 200

JSON

{
    "data": [
        {
            "id": 118,
            "title": "سماعة بلوتوث لاسلكية",
            "slug": "wireless-earbuds",
            "category": {
                "id": 4,
                "name": "إلكترونيات"
            },
            "description": "بطارية 30 ساعة، ومقاومة للمياه.",
            "images": [
                "https://thseen.com/product_files/earbuds-1.webp",
                "https://thseen.com/product_files/earbuds-2.webp"
            ],
            "files": [
                "https://thseen.com/product_files/earbuds-specs.pdf"
            ],
            "video_url": null,
            "marketing_files_url": "https://drive.google.com/drive/folders/example",
            "url": "https://thseen.com/product-detail/wireless-earbuds",
            "variants": [
                {
                    "id": 731,
                    "label": "أسود",
                    "price": "245.00",
                    "suggested_min": "320.00",
                    "suggested_max": "380.00",
                    "in_stock": true,
                    "stock_hint": 14,
                    "available": 14
                }
            ],
            "warranties": [
                {
                    "id": 2,
                    "name": "ضمان استبدال",
                    "admin_fee": 30,
                    "percent": 3,
                    "price_rule": "admin_fee + sale_price * percent / 100",
                    "price_from": 39.6,
                    "duration_days": 30,
                    "terms": "- استبدال بنفس المنتج خلال 30 يوم من الاستلام.\n- المنتج في علبته الأصلية بكل مشتملاته.",
                    "icon_url": null
                }
            ],
            "updated_at": "2026-10-06T18:42:00+03:00"
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 25,
        "total": 240,
        "last_page": 10
    }
}

GET /api/v1/products/{id}

منتج واحد

نفس شكل المنتج في القائمة. المنتج اللي اتوقف بيرجع 404.

بيتحسب: كل منتج مختلف بيرجع في الرد = منتج مسحوب، مرة واحدة في الشهر مهما اتكرر.

الصلاحية: قراءة المنتجات catalog:read

المدخلات

الاسم	فين	النوع	مطلوب	الشرح
`id`	في المسار	رقم	مطلوب	رقم المنتج.

الأخطاء المحتملة

401 unauthenticated 403 account_inactive 403 api_not_enabled 403 forbidden_ability 404 not_found 429 rate_limited 500 server_error

مثال

curl

curl "https://thseen.com/api/v1/products/118" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

الرد 200

JSON

{
    "data": {
        "id": 118,
        "title": "سماعة بلوتوث لاسلكية",
        "slug": "wireless-earbuds",
        "category": {
            "id": 4,
            "name": "إلكترونيات"
        },
        "description": "بطارية 30 ساعة، ومقاومة للمياه.",
        "images": [
            "https://thseen.com/product_files/earbuds-1.webp",
            "https://thseen.com/product_files/earbuds-2.webp"
        ],
        "files": [
            "https://thseen.com/product_files/earbuds-specs.pdf"
        ],
        "video_url": null,
        "marketing_files_url": "https://drive.google.com/drive/folders/example",
        "url": "https://thseen.com/product-detail/wireless-earbuds",
        "variants": [
            {
                "id": 731,
                "label": "أسود",
                "price": "245.00",
                "suggested_min": "320.00",
                "suggested_max": "380.00",
                "in_stock": true,
                "stock_hint": 14,
                "available": 14
            }
        ],
        "warranties": [
            {
                "id": 2,
                "name": "ضمان استبدال",
                "admin_fee": 30,
                "percent": 3,
                "price_rule": "admin_fee + sale_price * percent / 100",
                "price_from": 39.6,
                "duration_days": 30,
                "terms": "- استبدال بنفس المنتج خلال 30 يوم من الاستلام.\n- المنتج في علبته الأصلية بكل مشتملاته.",
                "icon_url": null
            }
        ],
        "updated_at": "2026-10-06T18:42:00+03:00"
    }
}

GET /api/v1/shipping/options

أنواع الشحن والمحافظات

كل نوع توصيل مفعّل والمحافظات المتاحة عليه بأسعارها، ومثال لمصاريف الشحن على بضاعة قيمتها 500 ج.م. استخدم الأرقام دي في governorate_id و shipping_option_id.

مجاني: مش بيتحسب في الفاتورة.

الصلاحية: قراءة المنتجات catalog:read

الأخطاء المحتملة

401 unauthenticated 403 account_inactive 403 api_not_enabled 403 forbidden_ability 429 rate_limited 500 server_error

مثال

curl

curl "https://thseen.com/api/v1/shipping/options" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

الرد 200

JSON

{
    "data": [
        {
            "id": 1,
            "name": "توصيل عادي",
            "governorates": [
                {
                    "id": 2,
                    "name": "القاهرة",
                    "delivery_charge": "60.00",
                    "shipping_tax_percent": "0.00",
                    "total_due_tax_percent": "1.00",
                    "example": {
                        "goods": "500.00",
                        "delivery_charge": "65.60"
                    }
                }
            ]
        }
    ]
}

POST /api/v1/shipping/quote

حساب الشحن قبل الطلب

نفس حساب صفحة الدفع بالظبط: مصاريف الشحن، والمطلوب من العميل، وربحك قبل وبعد عمولة تحسين (4%). مفيش طلب بيتسجل.

بيتحسب: كل منتج مختلف بيرجع في الرد = منتج مسحوب، مرة واحدة في الشهر مهما اتكرر.

الصلاحية: قراءة المنتجات catalog:read

المدخلات

الاسم	فين	النوع	مطلوب	الشرح
`shipping_option_id`	في الـJSON	رقم	مطلوب	نوع التوصيل.
`governorate_id`	في الـJSON	رقم	مطلوب	المحافظة.
`lines`	في الـJSON	قائمة	مطلوب	الأصناف: variant_id و quantity، و profit (اختياري).

الأخطاء المحتملة

401 unauthenticated 403 account_inactive 403 api_not_enabled 403 forbidden_ability 422 validation_failed 429 rate_limited 500 server_error

مثال

curl

curl -X POST "https://thseen.com/api/v1/shipping/quote" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "shipping_option_id": 1,
    "governorate_id": 2,
    "lines": [
        {
            "variant_id": 731,
            "quantity": 2,
            "profit": 50
        }
    ]
}'

الرد 200

JSON

{
    "data": {
        "shipping_option_id": 1,
        "governorate_id": 2,
        "products": "590.00",
        "warranties": "0.00",
        "delivery_charge": "66.00",
        "customer_total": "656.00",
        "profit": "100.00",
        "income_tax": "4.00",
        "net_profit": "96.00"
    }
}

POST /api/v1/orders

تسجيل طلب

بيسجّل الطلب بنفس قواعد صفحة الدفع ورسايلها. سعر كل صنف بيتحسب من سعره النهارده + ربحك. الرد 201 ومعاه الطلب كامل.

بيتحسب: عملية على الطلبات لما الطلب يتنفذ فعلًا (الإعادة بنفس Idempotency-Key والطلب المرفوض مش بيتحسبوا).

الصلاحية: تسجيل الطلبات orders:write

المدخلات

الاسم	فين	النوع	مطلوب	الشرح
`Idempotency-Key`	هيدر	نص ≤ 100	اختياري	مفتاح فريد لكل طلب: لو بعت نفس الطلب تاني بنفس المفتاح خلال 24 ساعة بيرجعلك نفس الرد من غير طلب جديد.
`external_reference`	في الـJSON	نص ≤ 100	اختياري	رقم الطلب عندك. مينفعش يتكرر على حسابك: التكرار بيرجع 409 ومعاه رقم الطلب الموجود.
`full_name`	في الـJSON	نص ≤ 255	مطلوب	اسم العميل.
`phone`	في الـJSON	موبايل مصري	مطلوب	01xxxxxxxxx (و +20 أو 0020 مقبولين وبيتظبطوا).
`second_phone`	في الـJSON	موبايل مصري	اختياري	رقم تاني للعميل.
`address`	في الـJSON	نص ≤ 255	مطلوب	العنوان بالتفاصيل.
`governorate_id`	في الـJSON	رقم	مطلوب	المحافظة، ولازم تكون متاحة مع نوع التوصيل.
`shipping_option_id`	في الـJSON	رقم	مطلوب	نوع التوصيل.
`store_name`	في الـJSON	نص ≤ 255	اختياري	اسم متجرك اللي يظهر للعميل.
`store_link`	في الـJSON	رابط http/https ≤ 255	اختياري	رابط متجرك.
`note`	في الـJSON	نص ≤ 1000	اختياري	ملاحظة للفريق.
`lines`	في الـJSON	قائمة (1 لـ 100)	مطلوب	كل سطر: variant_id، و quantity (1 لـ 999)، و profit (ربحك في القطعة، 0 أو أكتر)، و warranty_ids (اختياري، لحد 10): أرقام «ضمانات تحسين» من warranties في المنتج. العميل بيدفع الضمان فوق السعر وبيتضاف على المبلغ المطلوب منه، وربحك زي ما هو. السعر بنحسبه إحنا على سعر البيع للقطعة (fee + percent% منه)، وضمان مش تبع المنتج أو متوقف بيرجع 422 على lines.N.warranty_ids. الرد فيه warranties لكل سطر و totals.warranties.

الأخطاء المحتملة

401 unauthenticated 403 account_inactive 403 api_not_enabled 403 forbidden_ability 422 validation_failed 409 conflict 429 rate_limited 500 server_error

مثال

curl

curl -X POST "https://thseen.com/api/v1/orders" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: 7f3c9a2e-wc-10425" \
  -H "Content-Type: application/json" \
  -d '{
    "external_reference": "WC-10425",
    "full_name": "منى أحمد",
    "phone": "01012345678",
    "second_phone": null,
    "address": "مدينة نصر، شارع عباس العقاد، عمارة 12، الدور 3",
    "governorate_id": 2,
    "shipping_option_id": 1,
    "store_name": "متجر منى",
    "store_link": "https://mona-store.example",
    "note": "اتصل قبل التوصيل",
    "lines": [
        {
            "variant_id": 731,
            "quantity": 2,
            "profit": 50,
            "warranty_ids": [
                2
            ]
        }
    ]
}'

الرد 201

JSON

{
    "data": {
        "id": 1543,
        "number": "EG-7K3P9X2Q",
        "external_reference": "WC-10425",
        "tracking_url": null,
        "status": {
            "key": "order_confirmed",
            "label": "أكد العميل الطلب وجاري توفيره"
        },
        "family": "confirmed",
        "customer": {
            "name": "منى أحمد",
            "phone": "01012345678",
            "second_phone": null,
            "address": "مدينة نصر، شارع عباس العقاد، عمارة 12، الدور 3",
            "governorate": {
                "id": 2,
                "name": "القاهرة"
            }
        },
        "shipping_option": {
            "id": 1,
            "name": "توصيل عادي"
        },
        "lines": [
            {
                "id": 9001,
                "variant_id": 731,
                "product_id": 118,
                "title": "سماعة بلوتوث لاسلكية",
                "variant_label": "أسود",
                "quantity": 2,
                "delivered_quantity": null,
                "returned_quantity": null,
                "damaged_quantity": 0,
                "lost_quantity": 0,
                "destroyed_quantity": 0,
                "sell_price": "295.00",
                "profit": "50.00",
                "commission_on": true,
                "warranties": [
                    {
                        "id": 2,
                        "name": "ضمان استبدال",
                        "unit_price": "38.85",
                        "quantity": 2,
                        "total": "77.70",
                        "duration_days": 30,
                        "terms": "- استبدال بنفس المنتج خلال 30 يوم من الاستلام.\n- المنتج في علبته الأصلية بكل مشتملاته."
                    }
                ]
            }
        ],
        "totals": {
            "products": "590.00",
            "warranties": "77.70",
            "delivery_charge": "67.30",
            "customer_total": "735.00",
            "profit": "100.00",
            "income_tax_percent": "4",
            "income_tax": "4.00",
            "net_profit": "96.00"
        },
        "payout": {
            "state": "expected",
            "ready_at": null
        },
        "timeline": [
            {
                "status": "order_pending",
                "label": "الطلب معلق",
                "at": "2026-10-08T13:00:00+03:00",
                "reason": null
            },
            {
                "status": "order_confirmed",
                "label": "أكد العميل الطلب وجاري توفيره",
                "at": "2026-10-08T15:12:00+03:00",
                "reason": null
            }
        ],
        "created_at": "2026-10-08T13:00:00+03:00",
        "updated_at": "2026-10-08T15:12:00+03:00",
        "confirmed_at": "2026-10-08T15:12:00+03:00",
        "delivered_at": null
    }
}

GET /api/v1/orders

طلباتك

طلباتك إنت بس، الأحدث الأول.

مجاني: مش بيتحسب في الفاتورة.

الصلاحية: قراءة الطلبات orders:read

المدخلات

الاسم	فين	النوع	مطلوب	الشرح
`status`	في الرابط (?)	نص	اختياري	حالة واحدة بالكود بتاعها (status.key).
`family`	في الرابط (?)	نص	اختياري	مجموعة حالات: pending / confirmed / shipping / delivered / returned / cancelled / archived.
`external_reference`	في الرابط (?)	نص	اختياري	الطلب برقمه عندك.
`number`	في الرابط (?)	نص	اختياري	الطلب برقمه المرجعي عندنا (number) زي EG-7K3P9X2Q، كابيتال أو سمول وبالشرطة أو من غيرها. الرقم القديم للطلبات اللي قبل الأرقام المرجعية بيلاقيها برضه.
`updated_since`	في الرابط (?)	ISO-8601	اختياري	اللي اتغير من التاريخ ده.
`page`	في الرابط (?)	رقم	اختياري	رقم الصفحة، من 1.
`per_page`	في الرابط (?)	رقم	اختياري	عدد في الصفحة: 25 لو ما حددتش، وأقصى حاجة 100.

الأخطاء المحتملة

401 unauthenticated 403 account_inactive 403 api_not_enabled 403 forbidden_ability 422 validation_failed 429 rate_limited 500 server_error

مثال

curl

curl "https://thseen.com/api/v1/orders?family=shipping" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

الرد 200

JSON

{
    "data": [
        {
            "id": 1543,
            "number": "EG-7K3P9X2Q",
            "external_reference": "WC-10425",
            "tracking_url": null,
            "status": {
                "key": "order_confirmed",
                "label": "أكد العميل الطلب وجاري توفيره"
            },
            "family": "confirmed",
            "customer": {
                "name": "منى أحمد",
                "phone": "01012345678",
                "second_phone": null,
                "address": "مدينة نصر، شارع عباس العقاد، عمارة 12، الدور 3",
                "governorate": {
                    "id": 2,
                    "name": "القاهرة"
                }
            },
            "shipping_option": {
                "id": 1,
                "name": "توصيل عادي"
            },
            "lines": [
                {
                    "id": 9001,
                    "variant_id": 731,
                    "product_id": 118,
                    "title": "سماعة بلوتوث لاسلكية",
                    "variant_label": "أسود",
                    "quantity": 2,
                    "delivered_quantity": null,
                    "returned_quantity": null,
                    "damaged_quantity": 0,
                    "lost_quantity": 0,
                    "destroyed_quantity": 0,
                    "sell_price": "295.00",
                    "profit": "50.00",
                    "commission_on": true,
                    "warranties": [
                        {
                            "id": 2,
                            "name": "ضمان استبدال",
                            "unit_price": "38.85",
                            "quantity": 2,
                            "total": "77.70",
                            "duration_days": 30,
                            "terms": "- استبدال بنفس المنتج خلال 30 يوم من الاستلام.\n- المنتج في علبته الأصلية بكل مشتملاته."
                        }
                    ]
                }
            ],
            "totals": {
                "products": "590.00",
                "warranties": "77.70",
                "delivery_charge": "67.30",
                "customer_total": "735.00",
                "profit": "100.00",
                "income_tax_percent": "4",
                "income_tax": "4.00",
                "net_profit": "96.00"
            },
            "payout": {
                "state": "expected",
                "ready_at": null
            },
            "timeline": [
                {
                    "status": "order_pending",
                    "label": "الطلب معلق",
                    "at": "2026-10-08T13:00:00+03:00",
                    "reason": null
                },
                {
                    "status": "order_confirmed",
                    "label": "أكد العميل الطلب وجاري توفيره",
                    "at": "2026-10-08T15:12:00+03:00",
                    "reason": null
                }
            ],
            "created_at": "2026-10-08T13:00:00+03:00",
            "updated_at": "2026-10-08T15:12:00+03:00",
            "confirmed_at": "2026-10-08T15:12:00+03:00",
            "delivered_at": null
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 25,
        "total": 57,
        "last_page": 3
    }
}

GET /api/v1/orders/{id}

طلب واحد

الطلب بحالته وسجل حالاته وربحك ووقت ما يبقى جاهز للسحب (payout). طلب حساب تاني بيرجع 404.

مجاني: مش بيتحسب في الفاتورة.

الصلاحية: قراءة الطلبات orders:read

المدخلات

الاسم	فين	النوع	مطلوب	الشرح
`id`	في المسار	رقم	مطلوب	رقم الطلب (id).

الأخطاء المحتملة

401 unauthenticated 403 account_inactive 403 api_not_enabled 403 forbidden_ability 404 not_found 429 rate_limited 500 server_error

مثال

curl

curl "https://thseen.com/api/v1/orders/1543" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

الرد 200

JSON

{
    "data": {
        "id": 1543,
        "number": "EG-7K3P9X2Q",
        "external_reference": "WC-10425",
        "tracking_url": null,
        "status": {
            "key": "order_confirmed",
            "label": "أكد العميل الطلب وجاري توفيره"
        },
        "family": "confirmed",
        "customer": {
            "name": "منى أحمد",
            "phone": "01012345678",
            "second_phone": null,
            "address": "مدينة نصر، شارع عباس العقاد، عمارة 12، الدور 3",
            "governorate": {
                "id": 2,
                "name": "القاهرة"
            }
        },
        "shipping_option": {
            "id": 1,
            "name": "توصيل عادي"
        },
        "lines": [
            {
                "id": 9001,
                "variant_id": 731,
                "product_id": 118,
                "title": "سماعة بلوتوث لاسلكية",
                "variant_label": "أسود",
                "quantity": 2,
                "delivered_quantity": null,
                "returned_quantity": null,
                "damaged_quantity": 0,
                "lost_quantity": 0,
                "destroyed_quantity": 0,
                "sell_price": "295.00",
                "profit": "50.00",
                "commission_on": true,
                "warranties": [
                    {
                        "id": 2,
                        "name": "ضمان استبدال",
                        "unit_price": "38.85",
                        "quantity": 2,
                        "total": "77.70",
                        "duration_days": 30,
                        "terms": "- استبدال بنفس المنتج خلال 30 يوم من الاستلام.\n- المنتج في علبته الأصلية بكل مشتملاته."
                    }
                ]
            }
        ],
        "totals": {
            "products": "590.00",
            "warranties": "77.70",
            "delivery_charge": "67.30",
            "customer_total": "735.00",
            "profit": "100.00",
            "income_tax_percent": "4",
            "income_tax": "4.00",
            "net_profit": "96.00"
        },
        "payout": {
            "state": "expected",
            "ready_at": null
        },
        "timeline": [
            {
                "status": "order_pending",
                "label": "الطلب معلق",
                "at": "2026-10-08T13:00:00+03:00",
                "reason": null
            },
            {
                "status": "order_confirmed",
                "label": "أكد العميل الطلب وجاري توفيره",
                "at": "2026-10-08T15:12:00+03:00",
                "reason": null
            }
        ],
        "created_at": "2026-10-08T13:00:00+03:00",
        "updated_at": "2026-10-08T15:12:00+03:00",
        "confirmed_at": "2026-10-08T15:12:00+03:00",
        "delivered_at": null
    }
}

POST /api/v1/orders/{id}/cancel

إلغاء طلب

زي زرار الإلغاء في صفحة الطلب: بس والطلب لسه في الانتظار. بعد كده بيرجع 409.

بيتحسب: عملية على الطلبات لما الطلب يتنفذ فعلًا (الإعادة بنفس Idempotency-Key والطلب المرفوض مش بيتحسبوا).

الصلاحية: تسجيل الطلبات orders:write

المدخلات

الاسم	فين	النوع	مطلوب	الشرح
`id`	في المسار	رقم	مطلوب	رقم الطلب.
`reason_note`	في الـJSON	نص ≤ 500	اختياري	سبب الإلغاء.

الأخطاء المحتملة

401 unauthenticated 403 account_inactive 403 api_not_enabled 403 forbidden_ability 404 not_found 422 validation_failed 409 conflict 429 rate_limited 500 server_error

مثال

curl

curl -X POST "https://thseen.com/api/v1/orders/1543/cancel" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "reason_note": "العميل غيّر رأيه"
}'

الرد 200

JSON

{
    "data": {
        "id": 1543,
        "number": "EG-7K3P9X2Q",
        "external_reference": "WC-10425",
        "tracking_url": null,
        "status": {
            "key": "rejected_by_Marketer",
            "label": "تم الإلغاء من المسوق"
        },
        "family": "cancelled",
        "customer": {
            "name": "منى أحمد",
            "phone": "01012345678",
            "second_phone": null,
            "address": "مدينة نصر، شارع عباس العقاد، عمارة 12، الدور 3",
            "governorate": {
                "id": 2,
                "name": "القاهرة"
            }
        },
        "shipping_option": {
            "id": 1,
            "name": "توصيل عادي"
        },
        "lines": [
            {
                "id": 9001,
                "variant_id": 731,
                "product_id": 118,
                "title": "سماعة بلوتوث لاسلكية",
                "variant_label": "أسود",
                "quantity": 2,
                "delivered_quantity": null,
                "returned_quantity": null,
                "damaged_quantity": 0,
                "lost_quantity": 0,
                "destroyed_quantity": 0,
                "sell_price": "295.00",
                "profit": "50.00",
                "commission_on": true,
                "warranties": [
                    {
                        "id": 2,
                        "name": "ضمان استبدال",
                        "unit_price": "38.85",
                        "quantity": 2,
                        "total": "77.70",
                        "duration_days": 30,
                        "terms": "- استبدال بنفس المنتج خلال 30 يوم من الاستلام.\n- المنتج في علبته الأصلية بكل مشتملاته."
                    }
                ]
            }
        ],
        "totals": {
            "products": "590.00",
            "warranties": "77.70",
            "delivery_charge": "67.30",
            "customer_total": "735.00",
            "profit": "100.00",
            "income_tax_percent": "4",
            "income_tax": "4.00",
            "net_profit": "96.00"
        },
        "payout": {
            "state": "expected",
            "ready_at": null
        },
        "timeline": [
            {
                "status": "order_pending",
                "label": "الطلب معلق",
                "at": "2026-10-08T13:00:00+03:00",
                "reason": null
            },
            {
                "status": "order_confirmed",
                "label": "أكد العميل الطلب وجاري توفيره",
                "at": "2026-10-08T15:12:00+03:00",
                "reason": null
            }
        ],
        "created_at": "2026-10-08T13:00:00+03:00",
        "updated_at": "2026-10-08T15:12:00+03:00",
        "confirmed_at": "2026-10-08T15:12:00+03:00",
        "delivered_at": null
    }
}

GET /api/v1/wallet

المحفظة

نفس أرقام صفحة المحفظة: الجاهز للسحب رصيد واحد، أرباحك كمسوّق ومستحقات التوريد مع بعض، بنفس مواعيد السحب والحد الأدنى. profits_ready جزء الأرباح منه، وsupply جزء مستحقات التوريد: الجاهز منها، ورصيد دفتر الحساب، واللي اتدفع لك. كل طلب سحب بياخد من مستحقات التوريد الأول (supply_amount).

مجاني: مش بيتحسب في الفاتورة.

الصلاحية: قراءة المحفظة wallet:read

الأخطاء المحتملة

401 unauthenticated 403 account_inactive 403 api_not_enabled 403 forbidden_ability 429 rate_limited 500 server_error

مثال

curl

curl "https://thseen.com/api/v1/wallet" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

الرد 200

JSON

{
    "data": {
        "side": "supplier",
        "currency": "EGP",
        "income_tax_percent": "4",
        "ready": "12260.00",
        "held": {
            "amount": "0.00",
            "next_ready_at": null
        },
        "expected": "120.00",
        "referral": {
            "percent": "2",
            "earned": "0.00",
            "expected": "0.00"
        },
        "received": "900.00",
        "total_commission": "13660.00",
        "pending_withdrawals": {
            "count": 1,
            "amount": "500.00",
            "items": [
                {
                    "id": 311,
                    "amount": "500.00",
                    "supply_amount": "0.00",
                    "status": {
                        "key": "pending",
                        "label": "قيد التحويل"
                    },
                    "wallet_number": "01012345678",
                    "wallet_description": "محفظة موبايل",
                    "notes": null,
                    "transfer_reference": null,
                    "receipt_url": null,
                    "created_at": "2026-10-07T11:30:00+03:00",
                    "decided_at": null
                }
            ]
        },
        "withdrawal": {
            "open": false,
            "days": [
                "sunday",
                "thursday"
            ],
            "timezone": "Africa/Cairo",
            "opens_at": "2026-10-22T00:00:00+03:00",
            "closes_at": "2026-10-23T00:00:00+03:00",
            "minimum": "50.00",
            "minimum_currency": "EGP",
            "note": "يُتاح سحب الأرباح يومَي الأحد والخميس من كل أسبوع بتوقيت القاهرة."
        },
        "profits_ready": "310.00",
        "supply": {
            "currency": "EGP",
            "ready": "11950.00",
            "ledger_balance": "12450.00",
            "paid": "40200.00"
        }
    }
}

GET /api/v1/supplier/variants

الأصناف اللي تقدر تسعّرها

نفس اللي في «مزاد المنتجات»: كل صنف مفعّل، ومعاه سعرك عليه لو عندك (my_quote). أسعار الموردين التانيين مش بتظهر.

مجاني: مش بيتحسب في الفاتورة.

الصلاحية: قراءة عروض الأسعار quotes:read

المدخلات

الاسم	فين	النوع	مطلوب	الشرح
`q`	في الرابط (?)	نص	اختياري	بحث في اسم المنتج.
`product_id`	في الرابط (?)	رقم	اختياري	أصناف منتج واحد.
`page`	في الرابط (?)	رقم	اختياري	رقم الصفحة، من 1.
`per_page`	في الرابط (?)	رقم	اختياري	عدد في الصفحة: 25 لو ما حددتش، وأقصى حاجة 100.

الأخطاء المحتملة

401 unauthenticated 403 account_inactive 403 api_not_enabled 403 forbidden_ability 403 wrong_side 422 validation_failed 429 rate_limited 500 server_error

مثال

curl

curl "https://thseen.com/api/v1/supplier/variants" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

الرد 200

JSON

{
    "data": [
        {
            "id": 731,
            "product": {
                "id": 118,
                "title": "سماعة بلوتوث لاسلكية"
            },
            "label": "أسود",
            "my_quote": {
                "cost": "182.50",
                "valid_until": "2026-12-31",
                "expired": false
            }
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 25,
        "total": 310,
        "last_page": 13
    }
}

GET /api/v1/supplier/quotes

أسعارك

أسعارك الثابتة على الأصناف (من غير عروض جولات التوريد).

مجاني: مش بيتحسب في الفاتورة.

الصلاحية: قراءة عروض الأسعار quotes:read

المدخلات

الاسم	فين	النوع	مطلوب	الشرح
`page`	في الرابط (?)	رقم	اختياري	رقم الصفحة، من 1.
`per_page`	في الرابط (?)	رقم	اختياري	عدد في الصفحة: 25 لو ما حددتش، وأقصى حاجة 100.

الأخطاء المحتملة

401 unauthenticated 403 account_inactive 403 api_not_enabled 403 forbidden_ability 403 wrong_side 422 validation_failed 429 rate_limited 500 server_error

مثال

curl

curl "https://thseen.com/api/v1/supplier/quotes" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

الرد 200

JSON

{
    "data": [
        {
            "id": 5120,
            "variant": {
                "id": 731,
                "product": {
                    "id": 118,
                    "title": "سماعة بلوتوث لاسلكية"
                },
                "label": "أسود"
            },
            "cost": "182.50",
            "valid_until": "2026-12-31",
            "expired": false,
            "created_at": "2026-09-20T10:05:00+03:00",
            "updated_at": "2026-10-08T09:40:00+03:00"
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 25,
        "total": 42,
        "last_page": 2
    }
}

PUT /api/v1/supplier/quotes/{variant_id}

إضافة أو تغيير سعرك

زي ما بتسعّر من الشاشة بالظبط: لو سعرك بقى الأرخص (أو كان الأرخص واتغير)، سعر البيع الجديد بيروح للمراجعة قبل ما يتطبق. الرد 201 لو سعر جديد و200 لو تعديل.

مجاني: مش بيتحسب في الفاتورة.

الصلاحية: تعديل عروض الأسعار quotes:write

المدخلات

الاسم	فين	النوع	مطلوب	الشرح
`variant_id`	في المسار	رقم	مطلوب	رقم الصنف.
`cost`	في الـJSON	رقم (قرشين بالكتير)	مطلوب	سعرك للقطعة، من 0.01 لـ 999999.99.
`valid_until`	في الـJSON	تاريخ Y-m-d	اختياري	آخر يوم السعر ساري فيه (النهارده أو بعده). من غيره السعر ساري لحد ما تغيّره.

الأخطاء المحتملة

401 unauthenticated 403 account_inactive 403 api_not_enabled 403 forbidden_ability 403 wrong_side 404 not_found 422 validation_failed 429 rate_limited 500 server_error

مثال

curl

curl -X PUT "https://thseen.com/api/v1/supplier/quotes/731" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "cost": 182.5,
    "valid_until": "2026-12-31"
}'

الرد 200

JSON

{
    "data": {
        "id": 5120,
        "variant": {
            "id": 731,
            "product": {
                "id": 118,
                "title": "سماعة بلوتوث لاسلكية"
            },
            "label": "أسود"
        },
        "cost": "182.50",
        "valid_until": "2026-12-31",
        "expired": false,
        "created_at": "2026-09-20T10:05:00+03:00",
        "updated_at": "2026-10-08T09:40:00+03:00"
    }
}

DELETE /api/v1/supplier/quotes/{variant_id}

شيل سعرك

زي الحذف من «عروضي».

مجاني: مش بيتحسب في الفاتورة.

الصلاحية: تعديل عروض الأسعار quotes:write

المدخلات

الاسم	فين	النوع	مطلوب	الشرح
`variant_id`	في المسار	رقم	مطلوب	رقم الصنف.

الأخطاء المحتملة

401 unauthenticated 403 account_inactive 403 api_not_enabled 403 forbidden_ability 403 wrong_side 404 not_found 429 rate_limited 500 server_error

مثال

curl

curl -X DELETE "https://thseen.com/api/v1/supplier/quotes/731" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

الرد 200

JSON

{
    "data": {
        "variant_id": 731,
        "deleted": true
    }
}

GET /api/v1/supplier/statement

كشف الحساب

رصيدك (balance: المستحق ليك) وحركات حسابك، الأحدث الأول: فواتير المشتريات والمرتجعات والدفعات والتسويات.

مجاني: مش بيتحسب في الفاتورة.

الصلاحية: قراءة كشف الحساب statement:read

المدخلات

الاسم	فين	النوع	مطلوب	الشرح
`from`	في الرابط (?)	تاريخ Y-m-d	اختياري	من يوم.
`to`	في الرابط (?)	تاريخ Y-m-d	اختياري	لحد يوم.
`type`	في الرابط (?)	نص	اختياري	purchase_invoice / sourcing / purchase_return / payment / refund_in / adjustment / opening / expense.
`page`	في الرابط (?)	رقم	اختياري	رقم الصفحة، من 1.
`per_page`	في الرابط (?)	رقم	اختياري	عدد في الصفحة: 25 لو ما حددتش، وأقصى حاجة 100.

الأخطاء المحتملة

401 unauthenticated 403 account_inactive 403 api_not_enabled 403 forbidden_ability 403 wrong_side 422 validation_failed 429 rate_limited 500 server_error

مثال

curl

curl "https://thseen.com/api/v1/supplier/statement?from=2026-10-01" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

الرد 200

JSON

{
    "balance": "12450.00",
    "data": [
        {
            "id": 880,
            "date": "2026-10-05",
            "type": {
                "key": "purchase_invoice",
                "label": "فاتورة مشتريات"
            },
            "debit": "0.00",
            "credit": "3650.00",
            "note": "فاتورة 20 سماعة",
            "reference": {
                "type": "purchase",
                "number": 214
            },
            "created_at": "2026-10-05T12:00:00+03:00"
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 25,
        "total": 36,
        "last_page": 2
    }
}

ربط متجر WooCommerce أو Shopify

مفيش إضافة جاهزة؛ دي الخطوات اللي المبرمج بتاعك هيعملها، بأي لغة.

اعمل مفتاح بصلاحيات «قراءة المنتجات» و«قراءة الطلبات» و«تسجيل الطلبات».
هات المنتجات بـ GET /products وضيفها في متجرك بسعر البيع بتاعك، واحفظ مع كل صنف الـvariant_id بتاعه هنا.
حدّث الأسعار والمتاح كل يوم بـ GET /products?updated_since=….
لما عميل يطلب من متجرك (في WooCommerce: Webhook «Order created»، وفي Shopify: Webhook «orders/create»)، ابعت POST /orders: external_reference = رقم الطلب في متجرك، ولكل صنف profit = سعر البيع عندك − price. احسب الشحن الأول بـ POST /shipping/quote لو عايز تعرضه للعميل.
حدّث حالة الطلب في متجرك من GET /orders?updated_since=…، أو اشترك في الـWebhooks عشان توصلك كل حالة أول ما تتغير.
المفتاح يتحط في السيرفر بس، عمره ما يتحط في كود الصفحة اللي العميل بيشوفها.

وكمورد: ربط نظامك خطوة بخطوة

اعمل مفتاح بصلاحيات «قراءة عروض الأسعار» و«تعديل عروض الأسعار» و«قراءة كشف الحساب».
هات الأصناف بـ GET /supplier/variants واربط كل صنف عندك بالـid بتاعه هنا (مرة واحدة).
كل ما سعر يتغير عندك ابعته بـ PUT /supplier/quotes/{variant_id}. سعر البيع الجديد بيروح للمراجعة زي ما بيحصل من الشاشة.
تابع حسابك بـ GET /supplier/statement?from=…، أو اشترك في الـWebhooks عشان توصلك كل دفعة أول بأول. طلبات الشراء اللي الفريق بيبعتها لك بتوصلك في الجرس وعلى صفحة «طلبات الشراء».
المفتاح يتحط في السيرفر أو البرنامج بس، وما يتبعتش في رسايل.