مستندات وب‌سرویس ثبت پرونده دیجی فایند

احراز هویت

برای استفاده از سرویس‌هایی که نیاز به احراز هویت دارند، ابتدا توکن دریافت کنید.

دریافت توکن

دریافت Refresh Token

محدودیت نرخ ورود و قفل حساب

متدهای دریافت و رفرش توکن مشمول محدودیت نرخ هستند.

سرویس‌های پیش‌نیاز

موجودیت پرونده‌ها در دیجی فایند وابستگی‌های از پیش تعریف‌شده دارد. توسعه‌دهنده کافی است این داده‌ها را فراخوانی و در درخواست ثبت پرونده جای‌گذاری کند.

دریافت لیست استان‌ها

لیست تمامی استان‌ها شامل شناسه و نام.

{
  "id": "5bea91b0-fd48-4d04-bd54-9355d899545d",
  "title": "لرستان"
}

دریافت لیست شهرها

لیست شهرها شامل شناسه، نام و شناسه استان مربوطه.

{
  "id": "bcee4e39-a455-455a-a15a-3941c586c831",
  "title": "دورود",
  "provinceId": "5bea91b0-fd48-4d04-bd54-9355d899545d"
}

دریافت لیست محصولات مژدگانی

{
  "id": "8a1db491-7101-3f0b-c85e-3a0c3a7bfeed",
  "title": "برچسب 10 عددی"
}

دریافت لیست محصولات ردیابی موبایل

{
  "id": "a17b24e2-d422-57c6-2c29-3a13639ac08d",
  "title": "ردیابی موبایل 150 روزه"
}

دریافت لیست برندهای موبایل

{
  "id": "7857132a-370a-5f1f-003b-3a0fa9cb8c7b",
  "title": "اپل"
}

دریافت لیست آیتم‌های گمشده یا پیداشده

خروجی شامل شناسه، نام، ترتیب نمایش و ویژگی‌های هر آیتم است. هر ویژگی دارای شناسه، عنوان، توضیحات، ترتیب، اجباری بودن و الگوی Regex می‌باشد.

[
  {
    "id": "c277840b-c327-a3b5-0f1e-3a0c3a7c5a3e",
    "title": "لپ تاپ",
    "order": 0,
    "properties": [
      {
        "id": "7d8a83e0-edf7-f20f-2000-3a0c3a7c5a3e",
        "title": "برند لپ تاپ",
        "description": "برند گمشده را وارد کنید",
        "order": 0,
        "isRequired": true,
        "regexValidationPattern": null
      }
    ]
  }
]

ثبت پرونده گمشده یا پیداشده

پارامترهای ورودی به دو دسته تقسیم می‌شوند: اطلاعات مستقیم کاربر و شناسه‌هایی که از سرویس‌های پیش‌نیاز دریافت می‌شوند. ارسال هدر Idempotency-Key در این درخواست‌های POST الزامی است. جزئیات در بخش محدودیت نرخ و Idempotency آمده است.

ثبت پرونده پیداشده

پس از ثبت موفق، یک Guid به‌عنوان شناسه پرونده برگردانده می‌شود.

ثبت پرونده گمشده

ثبت پرونده گوشی سرقتی

برای phoneBrand پس از دریافت لیست برندها، نام برند را به‌صورت رشته ارسال کنید. برای selectedProductId از متد محصولات ردیابی موبایل استفاده کنید.

ثبت مالک برای پرونده پیداشده

پس از یافتن پرونده پیداشده (از متد جستجو)، مالک می‌تواند با این متد پرونده گمشدهٔ مرتبط را ثبت کند. کد ملی مالک باید با کد ملی ثبت‌شده روی پرونده پیداشده مطابقت داشته باشد. اگر پرونده پیداشده از قبل به یک پرونده گمشده متصل باشد، پرونده جدیدی ساخته نمی‌شود و همان پرونده مرتبط برگردانده می‌شود.

پاسخ این متد از ساختار مشترک پیام پیروی می‌کند. در موفقیت، result شامل شناسه و شماره پرونده مرتبط و پیام خروجی است.

جستجو در دیجی فایند

جستجو بر اساس کد ملی و نوع پرونده انجام می‌شود. حداکثر ۱۰ نتیجه برگردانده می‌شود.

پاسخ این متد از ساختار مشترک پیام پیروی می‌کند و فهرست نتایج را در آرایهٔ results برمی‌گرداند.

محدودیت نرخ و Idempotency

متدهای ثبت پرونده، ثبت مالک و جستجو مشمول محدودیت نرخ هستند. درخواست‌های POST ثبت پرونده و ثبت مالک باید هدر الزامی Idempotency-Key را داشته باشند تا از ثبت تکراری جلوگیری شود. محدودیت نرخ دریافت و رفرش توکن در بخش احراز هویت آمده است.

محدودیت نرخ (Rate limit)

درخواست‌های POST ثبت پرونده و ثبت مالک، و همچنین GET جستجو، مشمول محدودیت نرخ هستند. سرویس‌های پیش‌نیاز (استان، شهر، …) محدود نمی‌شوند.

هدر Idempotency-Key (الزامی روی POST)

در درخواست‌های POST ثبت پرونده و ثبت مالک، ارسال هدر Idempotency-Key الزامی است. برای هر عملیات منطقی یک کلید یکتا بفرستید و در صورت تکرار درخواست (خطا یا وقفه در شبکه) همان کلید را دوباره استفاده کنید. نمونه: Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

ساختار مشترک پیام

متدهای جستجو و ثبت مالک پاسخ را با همین ساختار برمی‌گردانند:

نمونه درخواست و پاسخ

Found Case — پرونده پیداشده

{
  "finderName": "امیرحسین",
  "finderLastName": "هداوند",
  "finderPhoneNumber": "09365093716",
  "lostItemNationalCode": "",
  "lostItemAniyabSerial": "12345678",
  "foundItems": [
    {
      "id": "c277840b-c327-a3b5-0f1e-3a0c3a7c5a3e",
      "properties": [
        {
          "id": "7d8a83e0-edf7-f20f-2000-3a0c3a7c5a3e",
          "value": "مک بوک"
        }
      ]
    }
  ]
}

Lost Case — پرونده گمشده

{
  "ownerName": "امیرحسین",
  "ownerLastName": "هداوند",
  "ownerFatherName": "اسماعیل",
  "ownerNationalCode": "4901289632",
  "ownerAniyabSerial": "12345678",
  "ownerPhoneNumber": "09365093716",
  "lostDate": "2025-02-04T08:32:02.981Z",
  "provinceId": "",
  "cityId": "",
  "region": "4",
  "street": "ستارخان",
  "lostItems": [
    {
      "id": "c277840b-c327-a3b5-0f1e-3a0c3a7c5a3e",
      "properties": [
        {
          "id": "7d8a83e0-edf7-f20f-2000-3a0c3a7c5a3e",
          "value": "مک بوک"
        }
      ]
    }
  ],
  "rewardProductId": "7d8a83e0-edf7-f20f-2000-3a0c3a7c5a3e"
}

Phone Lost Case — گوشی سرقتی

{
  "ownerName": "امیرحسین",
  "ownerLastName": "هداوند",
  "ownerFatherName": "اسماعیل",
  "ownerNationalCode": "4901289632",
  "ownerAniyabSerial": "12345678",
  "ownerPhoneNumber": "09365093716",
  "phoneBrand": "اپل",
  "imeI1": "359603087204549",
  "imeI2": "352829096791013",
  "lostDate": "2025-02-05T11:02:28.101Z",
  "selectedProductId": "44ac3a11-fcfc-2145-f1cc-3a13639998ec"
}

Register Owner — درخواست ثبت مالک

{
  "foundCaseId": "c277840b-c327-a3b5-0f1e-3a0c3a7c5a3e",
  "ownerName": "امیرحسین",
  "ownerLastName": "هداوند",
  "ownerNationalId": "4901289632",
  "ownerPhoneNumber": "09365093716"
}

Register Owner — پاسخ موفق

{
  "resultCode": 1,
  "isSuccessful": true,
  "errorMessage": "",
  "result": {
    "caseId": "8a1db491-7101-3f0b-c85e-3a0c3a7bfeed",
    "caseNumber": "1403123456",
    "content": "پرونده مرتبط با کد 1403123456 ثبت شد! به زودی اطلاعات یابنده فرستاده خواهد شد!"
  }
}

Search — پاسخ موفق

{
  "resultCode": 1,
  "isSuccessful": true,
  "errorMessage": "",
  "results": [
    {
      "caseId": "c277840b-c327-a3b5-0f1e-3a0c3a7c5a3e",
      "caseNumber": "1403123456",
      "caseCategoryTitle": "لپ تاپ",
      "content": "پرونده ای با موضوع لپ تاپ و شماره پرونده 1403123456 یافت شد."
    }
  ]
}

Search — پرونده یافت نشد

{
  "resultCode": 1,
  "isSuccessful": false,
  "errorMessage": "",
  "results": [
    {
      "caseId": "00000000-0000-0000-0000-000000000000",
      "caseNumber": "",
      "caseCategoryTitle": "",
      "content": "متاسفانه پرونده ای با این اطلاعات در دیجی فایند وجود ندارد."
    }
  ]
}