قائمة وثائق المطورين

استكشف الواجهة في Postman

مبتدئ

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

أنشئ بيئة

في Postman، افتح Environments، وأنشئ بيئة باسم جوكر برايس، وأضف متغيرين:

المتغيرالنوعالقيمة
baseUrldefault (افتراضي)https://jokerprice.com
apiKeysecret (سري)مفتاحك ss_…

اختر البيئة من القائمة في أعلى يمين النافذة. ويؤدي وسم المفتاح بأنه سري إلى إخفائه على الشاشة وفي لقطات الشاشة المشتركة.

استورد المجموعة

اختر Import، والصق JSON أدناه، ثم أكّد. ترسل المجموعة Bearer {{apiKey}} مع كل طلب، لذا لا تحمل الطلبات المنفردة أي إعدادات مصادقة.

JokerPrice.postman_collection.json
{
  "info": {
    "name": "JokerPrice API",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "auth": {
    "type": "bearer",
    "bearer": [
      {
        "key": "token",
        "value": "{{apiKey}}",
        "type": "string"
      }
    ]
  },
  "variable": [
    {
      "key": "city",
      "value": "riyadh"
    },
    {
      "key": "cursor",
      "value": ""
    }
  ],
  "item": [
    {
      "name": "List markets",
      "request": {
        "method": "GET",
        "url": "{{baseUrl}}/api/v1/markets"
      }
    },
    {
      "name": "Get market",
      "request": {
        "method": "GET",
        "url": "{{baseUrl}}/api/v1/markets/{{city}}"
      }
    },
    {
      "name": "Metrics",
      "request": {
        "method": "GET",
        "url": "{{baseUrl}}/api/v1/metrics?city={{city}}&past_days=30&forward_days=60"
      }
    },
    {
      "name": "Trends",
      "request": {
        "method": "GET",
        "url": "{{baseUrl}}/api/v1/trends?city={{city}}&metric=occupancy&days=90"
      }
    },
    {
      "name": "Listings (next page)",
      "event": [
        {
          "listen": "test",
          "script": {
            "type": "text/javascript",
            "exec": [
              "pm.test(\"200 OK\", () => pm.response.to.have.status(200));",
              "const next = pm.response.json().nextCursor;",
              "pm.collectionVariables.set(\"cursor\", next || \"\");",
              "console.log(next ? \"Send again for the next page\" : \"Last page reached\");"
            ]
          }
        }
      ],
      "request": {
        "method": "GET",
        "url": "{{baseUrl}}/api/v1/listings?city={{city}}&limit=100&cursor={{cursor}}"
      }
    },
    {
      "name": "Estimate",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Content-Type",
            "value": "application/json"
          }
        ],
        "url": "{{baseUrl}}/api/v1/estimate",
        "body": {
          "mode": "raw",
          "raw": "{\n  \"latitude\": 24.7743,\n  \"longitude\": 46.7386,\n  \"radiusKm\": 3,\n  \"bedrooms\": 3,\n  \"typeId\": \"7\"\n}"
        }
      }
    }
  ]
}

غيّر المدينة

يتحكم متغير المجموعة city في أربعة طلبات. شغّل List markets، وانسخ معرّفًا slug مثل jeddah أو dubai، ثم اضبطه في تبويب Variables الخاص بالمجموعة.

تنقّل بين صفحات العقارات

يحفظ الطلب Listings (next page) قيمة nextCursor في المتغير cursor بعد كل استجابة. أرسله مرارًا لتمر على المدينة كلها، وتخبرك وحدة التحكم (Console) عند بلوغ الصفحة الأخيرة. امسح cursor للبدء من جديد.

استخدم Collection Runner بحذر

يرسل المشغّل الطلبات متتابعة دون توقف. اضبط تأخيرًا لا يقل عن 1,000 ملّي ثانية كي يبقى التشغيل دون 120 طلبًا في الدقيقة، وهو الحد خلال التجربة المجانية. ويُحتسب كل تشغيل ضمن طلبات الحساب اليومية (25,000 خلال التجربة المجانية).

اقرأ الأخطاء

يتضمن جسم كل خطأ error.code وerror.message وrequestId. وتعرض وحدة التحكم في Postman ترويسة X-Request-ID أيضًا.