{"openapi":"3.1.0","info":{"title":"API نِت اَرز","version":"1.0.0","description":"رابط برنامه‌نویسی نِت اَرز برای دریافت لیست محصولات، قیمت‌های لحظه‌ای (دلار و تومان)، نرخ ارز و ثبت سفارش مستقیم از کیف پول.\n\n**احراز هویت:** توکن شخصی را از پنل کاربری ← «توکن‌های API» بسازید و در هدر `Authorization: Bearer TOKEN` ارسال کنید.\n\n**محدودیت نرخ:** عمومی ۱۲۰ و احرازشده ۶۰ درخواست در دقیقه.","contact":{"name":"پشتیبانی نِت اَرز","url":"https://netarz.ir"}},"servers":[{"url":"https://netarz.ir/api/v1","description":"سرور اصلی"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"عمومی","description":"بدون نیاز به احراز هویت"},{"name":"کیف پول و سفارش","description":"نیازمند توکن"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"توکن شخصی ساخته‌شده در پنل کاربری"}},"schemas":{"Price":{"type":"object","properties":{"usd":{"type":"number","example":11.5,"description":"قیمت پایه به دلار"},"toman":{"type":"integer","example":2185000,"description":"قیمت معادل به تومان (نرخ روز)"},"from":{"type":"boolean","example":true,"description":"اگر true باشد، قیمت «از» (کمترین گزینه) است"}}},"Variant":{"type":"object","properties":{"id":{"type":"integer","example":5},"title":{"type":"string","example":"۵۰ دلاری"},"price":{"type":"object","properties":{"usd":{"type":"number","example":54},"toman":{"type":"integer","example":10260000}}},"in_stock":{"type":"boolean","example":true}}},"Product":{"type":"object","properties":{"id":{"type":"integer","example":194},"slug":{"type":"string","example":"گیفت-کارت-اپل-آمریکا"},"title":{"type":"string","example":"گیفت‌کارت اپل آمریکا"},"type":{"type":"string","example":"gift_card"},"delivery_type":{"type":"string","enum":["instant","manual","service"],"example":"instant"},"has_variants":{"type":"boolean","example":true},"in_stock":{"type":"boolean","example":true},"price":{"$ref":"#/components/schemas/Price"},"image":{"type":"string","nullable":true},"url":{"type":"string"}}},"Order":{"type":"object","properties":{"order_number":{"type":"string","example":"NTRZ-260630-AB12X"},"status":{"type":"string","example":"completed"},"status_label":{"type":"string","example":"تکمیل‌شده"},"total_toman":{"type":"integer","example":10260000},"usd_rate":{"type":"integer","example":190000,"description":"نرخ دلار قفل‌شده در زمان خرید"},"items":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"quantity":{"type":"integer"},"unit_price_usd":{"type":"number"},"line_total_toman":{"type":"integer"},"delivered":{"type":"boolean"},"delivered_payload":{"type":"string","nullable":true,"description":"کد/اطلاعات تحویل"}}}}}},"Error":{"type":"object","properties":{"message":{"type":"string","example":"موجودی کیف پول کافی نیست."}}}}},"paths":{"/rate":{"get":{"tags":["عمومی"],"summary":"نرخ روز دلار","security":[],"description":"نرخ تبدیل دلار به تومان که برای همه‌ی قیمت‌ها استفاده می‌شود. نرخ به‌صورت خودکار و در فاصله‌های کوتاه (refresh_interval_minutes) از بازار به‌روزرسانی می‌شود؛ زمان آخرین به‌روزرسانی در updated_at آمده است.","responses":{"200":{"description":"موفق","content":{"application/json":{"example":{"data":{"usd_to_irt_rate":190000,"currency":"IRT","auto_updated":true,"updated_at":"2026-09-02T11:05:00+00:00","refresh_interval_minutes":5}}}}}}}},"/estimate":{"post":{"tags":["عمومی"],"summary":"برآورد هوشمند قیمت از روی لینک","security":[],"description":"لینک صفحه‌ی خرید یک محصول/اکانت خارجی را می‌گیرد، با هوش مصنوعی قیمت را می‌خواند، به دلار تبدیل می‌کند، ۲۵٪ حق خدمات و زمان ارسال دبی→ایران (۱۰ روز) را اضافه می‌کند و قیمت نهایی تومانی و مدت تحویل را برمی‌گرداند. محدودیت: ۲۰ درخواست در دقیقه.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","example":"https://example.ae/product/some-account"}}},"example":{"url":"https://example.ae/product/some-account"}}}},"responses":{"200":{"description":"موفق","content":{"application/json":{"example":{"data":{"success":true,"product_name":"اکانت نمونه","source":{"currency":"AED","price":199},"breakdown":{"unit_price_usd":54.19,"shipping_cost_usd":0,"service_fee_percent":25,"service_fee_usd":13.55,"total_usd":67.74,"usd_rate":190000,"total_toman":12870000},"delivery":{"seller_days":3,"extra_days":10,"total_days":13}}}}}},"422":{"description":"قیمت پیدا نشد / خطای سرویس","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/products":{"get":{"tags":["عمومی"],"summary":"لیست محصولات","security":[],"description":"لیست محصولات منتشرشده با قیمت دلار و تومان (صفحه‌بندی‌شده).","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"جستجو در عنوان"},{"name":"category","in":"query","schema":{"type":"string"},"description":"نامک دسته"},{"name":"type","in":"query","schema":{"type":"string"},"description":"نوع محصول (مثل gift_card)"},{"name":"delivery","in":"query","schema":{"type":"string","enum":["instant","manual","service"]}},{"name":"sort","in":"query","schema":{"type":"string","enum":["latest","cheapest","expensive","popular"]}},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"maximum":50}},{"name":"page","in":"query","schema":{"type":"integer","default":1}}],"responses":{"200":{"description":"موفق","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"type":"object"},"links":{"type":"object"}}}}}}}}},"/products/{slug}":{"get":{"tags":["عمومی"],"summary":"جزئیات محصول","security":[],"description":"جزئیات کامل محصول به همراه گزینه‌ها (variants).","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"example":"گیفت-کارت-اپل-آمریکا"}],"responses":{"200":{"description":"موفق","content":{"application/json":{"example":{"data":{"slug":"گیفت-کارت-اپل-آمریکا","title":"گیفت‌کارت اپل آمریکا","has_variants":true,"price":{"usd":11.5,"toman":2185000,"from":true},"variants":[{"id":4,"title":"۱۰ دلاری","price":{"usd":11.5,"toman":2185000},"in_stock":true},{"id":5,"title":"۵۰ دلاری","price":{"usd":54,"toman":10260000},"in_stock":true}]}}}}},"404":{"description":"یافت نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/wallet":{"get":{"tags":["کیف پول و سفارش"],"summary":"موجودی کیف پول","description":"موجودی فعلی کیف پول کاربر به تومان.","responses":{"200":{"description":"موفق","content":{"application/json":{"example":{"data":{"balance_toman":5000000}}}}},"401":{"description":"بدون احراز هویت","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orders":{"get":{"tags":["کیف پول و سفارش"],"summary":"لیست سفارش‌ها","responses":{"200":{"description":"موفق","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Order"}}}}}}}}},"post":{"tags":["کیف پول و سفارش"],"summary":"ثبت سفارش (پرداخت از کیف پول)","description":"یک محصول را خریداری و از کیف پول پرداخت می‌کند. برای محصولات چندگزینه‌ای، `variant_id` الزامی است. کد تحویل آنی در پاسخ بازمی‌گردد.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","oneOf":[{"required":["product_slug"]},{"required":["product_id"]}],"properties":{"product_slug":{"type":"string","example":"گیفت-کارت-اپل-آمریکا"},"product_id":{"type":"integer"},"variant_id":{"type":"integer","nullable":true,"example":5},"quantity":{"type":"integer","default":1,"maximum":20}}},"example":{"product_slug":"گیفت-کارت-اپل-آمریکا","variant_id":5,"quantity":1}}}},"responses":{"201":{"description":"سفارش ثبت و تحویل شد","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Order"}}}}}},"422":{"description":"خطا (موجودی ناکافی / گزینه نامعتبر)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"محصول یافت نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orders/{order_number}":{"get":{"tags":["کیف پول و سفارش"],"summary":"جزئیات سفارش","parameters":[{"name":"order_number","in":"path","required":true,"schema":{"type":"string"},"example":"NTRZ-260630-AB12X"}],"responses":{"200":{"description":"موفق","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Order"}}}}}},"404":{"description":"یافت نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}