پرش به محتوای اصلی
روزانم

API روزانم برای توسعه‌دهندگان

آخرین به‌روزرسانی: ۳ آبان ۱۴۰۵

API روزانم دو کار می‌کند: به شریکان (اپ‌ها و سایت‌های سلامت، فروشگاه‌ها، پژوهشگران) کاتالوگ عمومی غذاهای ایرانی با ارزش غذایی، بانک دستور پخت و آمار عمومی را می‌دهد، و به هر کاربر اجازه می‌دهد با توکن شخصی خودش، داده‌های خودش را در برنامه‌ها و اتوماسیون‌هایش (مثل ترازوی هوشمند یا میان‌بُرهای گوشی) بخواند و آب، وزن و قدم ثبت کند.

نشانی پایه https://api.roozanam.ir/v1 است و همه‌ی پاسخ‌ها JSON‌اند. هیچ نشانی‌ای هوش مصنوعی را صدا نمی‌زند و استفاده از API رایگان است. سند ماشین‌خوان: OpenAPI 3.1.

۱. شروع سریع

شریکان: کلید شریک (با پیشوند rzk_) را از روزانم بگیرید و آن را در متغیر محیطی سرور خود بگذارید؛ نمونه‌ی زیر تا پنج غذای نزدیک به «نان سنگک» را برمی‌گرداند:

export ROOZANAM_KEY="rzk_…"
curl -G "https://api.roozanam.ir/v1/foods" \
  -H "Authorization: Bearer $ROOZANAM_KEY" \
  --data-urlencode "q=نان سنگک" \
  --data-urlencode "per_page=5"

کاربران: در وب‌اپ روزانم به «پروفایل» ← «🔑 توکن دسترسی» بروید، برای برنامه‌ی خود یک توکن (با پیشوند rzp_) با دسترسی‌های لازم بسازید و همان لحظه کپی کنید؛ نمونه‌ی زیر خلاصه‌ی امروز شما را برمی‌گرداند:

export ROOZANAM_TOKEN="rzp_…"
curl "https://api.roozanam.ir/v1/me/days/today" \
  -H "Authorization: Bearer $ROOZANAM_TOKEN"

۲. احراز هویت

هر درخواست (به‌جز همین راهنما و سند OpenAPI) یکی از دو اعتبارنامه‌ی زیر را لازم دارد:

نوعپیشونداز کجابه چه چیزی دسترسی دارد
کلید شریکrzk_مالک روزانم آن را در پنل مدیریت با نام، دسترسی‌ها و سقف درخواست می‌سازد.فقط کاتالوگ عمومی: غذاها، دستورهای پخت منتشرشده و آمار؛ هیچ داده‌ی کاربری.
توکن دسترسی شخصیrzp_خود کاربر در وب‌اپ: «پروفایل» ← «🔑 توکن دسترسی» (حداکثر ۱۰ توکن فعال).فقط داده‌های همان کاربر، با دسترسی‌هایی که خودش انتخاب کرده است.
  • اعتبارنامه را در سرآیند Authorization: Bearer <token> بفرستید. فرستادن آن در نشانی (مثل ?key=…) پذیرفته نمی‌شود، چون نشانی‌ها در لاگ‌ها و تاریخچه‌ها می‌مانند.
  • کلید و توکن مخصوص سرور یا اسکریپت شخصی شماست. آن را در کد صفحه‌ی وب یا اپی که به دست کاربران می‌رسد نگذارید؛ به همین دلیل این نشانی‌ها CORS ندارند و باید از سرور صدا زده شوند.
  • کلید و توکن فقط یک بار، هنگام ساخت، نمایش داده می‌شوند. روزانم فقط هش SHA-256 آن‌ها را نگه می‌دارد و راهی برای بازیابی‌شان نیست؛ اگر گم شد، یکی تازه بسازید و قبلی را باطل کنید.
  • ابطال از درخواست بعدی اعمال می‌شود: کلید شریک را مالک در پنل باطل می‌کند و توکن شخصی را کاربر در وب‌اپ یا با دکمه‌ای که پس از ساخت هر توکن در ربات برایش می‌آید. «خروج از همه‌ی دستگاه‌ها» در وب‌اپ، مسدود شدن حساب یا تغییر شماره‌ی موبایل کاربر هم همه‌ی توکن‌های او را باطل می‌کند.
  • اعتبارنامه‌ی نادرست یا باطل‌شده پاسخ 401 می‌گیرد؛ نوع نادرست (مثلاً کلید شریک روی /me) یا نداشتن دسترسی لازم پاسخ 403.

۳. دسترسی‌ها (scope)

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

دسترسینوع اعتبارنامهاجازهنقاط پایانی
foods:readکلید شریکجست‌وجوی غذاها و ارزش غذایی هر ۱۰۰ گرم و هر سهمGET /foodsGET /foods/{id}
recipes:readکلید شریکبانک دستور پخت منتشرشدهGET /recipesGET /recipes/{slug}
stats:readکلید شریکآمار عمومی روزانمGET /stats
profile:readتوکن دسترسی شخصیخواندن پروفایل و هدف‌های روزانهGET /me/profile
diary:readتوکن دسترسی شخصیخواندن خلاصه‌ی روز (وعده‌ها، آب، قدم، فعالیت، وزن) و فهرست وزن‌هاGET /me/days/{date}GET /me/weights
water:writeتوکن دسترسی شخصیثبت آبPOST /me/water
weight:writeتوکن دسترسی شخصیثبت وزنPOST /me/weights
steps:writeتوکن دسترسی شخصیثبت تعداد قدم یک روزPUT /me/days/{date}/steps

۴. سقف درخواست‌ها

  • کلید شریک: هر کلید سقف جداگانه‌ای در دقیقه دارد که مالک روزانم هنگام ساخت تعیین می‌کند (پیش‌فرض ۶۰، بین ۱۰ تا ۶۰۰ درخواست در دقیقه).
  • توکن شخصی: ۶۰ درخواست در دقیقه برای هر توکن؛ و برای ثبت‌ها (آب، وزن، قدم) روی همه‌ی توکن‌های یک کاربر روی‌هم ۳۰ ثبت در دقیقه و ۵۰۰ ثبت در روز.
  • تلاش ناموفق: پس از ۳۰ درخواست با اعتبارنامه‌ی نادرست یا باطل‌شده در ۱۰ دقیقه از یک نشانی اینترنتی، تلاش‌های نادرست بعدی آن نشانی تا پایان همان بازه پاسخ 429 می‌گیرند؛ درخواست‌هایی که اعتبارنامه‌ی درست دارند اثری نمی‌پذیرند.
  • هر پاسخ احراز‌شده سرآیندهای X-RateLimit-Limit (سقف در دقیقه) و X-RateLimit-Remaining (باقی‌مانده) را دارد. پاسخ 429 با کد rate_limited و سرآیند Retry-After (ثانیه) می‌آید؛ پس از آن زمان دوباره بفرستید. پاسخ‌های 304 هم شمرده می‌شوند.

۵. قالب پاسخ‌ها و صفحه‌بندی

  • پاسخ موفق {"data": …} است. فهرست‌ها کنار data یک pagination دارند: {"page", "per_page", "total", "has_more"}.
  • صفحه‌ها با page (از ۱) و per_page (۱ تا ۱۰۰، پیش‌فرض ۲۰) خوانده می‌شوند؛ تا وقتی has_more درست است، صفحه‌ی بعد را بخواهید.
  • نام فیلدها snake_case است. انرژی با calories (کیلوکالری) و بقیه با واحدِ آمده در نام فیلد (_g، _mg، _ml، _kg، _ug) می‌آیند. عددها عدد JSON‌اند و متن‌ها فارسی.
  • زمان‌ها (*_at) به قالب ISO 8601 و به وقت UTC‌اند. فیلدهای date روزِ خود کاربر به قالب YYYY-MM-DD (میلادی) هستند، با منطقه‌ی زمانی پروفایل او (پیش‌فرض Asia/Tehran)؛ در مسیرها today و yesterday هم پذیرفته می‌شوند.
  • در نسخه‌ی ۱ ممکن است فیلد یا نشانی تازه‌ای اضافه شود؛ برنامه‌ی شما باید فیلدهای ناشناخته را نادیده بگیرد.

۶. کش و ETag

  • پاسخ‌های کاتالوگ (غذاها، دستورهای پخت و آمار) سرآیند ETag و Cache-Control: private, max-age=… دارند (غذاها و دستورها ۳۰۰ ثانیه، آمار ۶۰ ثانیه). اگر همان ETag را در If-None-Match بفرستید و چیزی تغییر نکرده باشد، پاسخ 304 بدون بدنه برمی‌گردد.
  • این پاسخ‌ها خصوصی‌اند: سرور یا CDN مشترک نباید آن‌ها را برای دیگران نگه دارد.
  • داده‌های کاربر و همه‌ی خطاها Cache-Control: no-store دارند.

۷. نقاط پایانی

نشانی پایه: https://api.roozanam.ir/v1

روش و مسیرکاردسترسی
GET /foodsجست‌وجو و فهرست غذاهاfoods:read
GET /foods/{id}ارزش غذایی یک غذاfoods:read
GET /recipesفهرست بانک دستور پختrecipes:read
GET /recipes/{slug}یک دستور پختrecipes:read
GET /statsآمار عمومیstats:read
GET /me/profileپروفایل و هدف‌هاprofile:read
GET /me/days/{date}خلاصه‌ی یک روزdiary:read
GET /me/weightsفهرست وزن‌هاdiary:read
POST /me/waterثبت آبwater:write
POST /me/weightsثبت وزنweight:write
PUT /me/days/{date}/stepsثبت قدم‌های یک روزsteps:write

غذاهاکاتالوگ عمومی غذاها و ارزش غذایی آن‌ها (کلید شریک).

GET /v1/foodsجست‌وجو و فهرست غذاها

دسترسی لازم: foods:read · کلید شریک · قابل نگه‌داری تا ۳۰۰ ثانیه با ETag

با q غذاها به ترتیب نزدیکی به عبارت برمی‌گردند (نام یا نام دیگرِ دقیقاً برابر در صدر)؛ بدون q کل کاتالوگ عمومی به ترتیب نام برمی‌گردد که برای همگام‌سازی مناسب است. ارزش‌ها برای هر ۱۰۰ گرم‌اند. کاتالوگ عمومی فقط غذاهای پایه‌ی بازبینی‌شده است؛ دستورهای خانگی کاربران، محصولات بسته‌بندی‌ای که کاربران ثبت کرده‌اند و برآوردهای بازبینی‌نشده‌ی هوش مصنوعی در آن نیستند.

پارامترمحلاجباریتوضیح
qپرس‌وجوخیرعبارت جست‌وجو (فارسی یا انگلیسی)، ۲ تا ۱۰۰ نویسه.
categoryپرس‌وجوخیرفقط یک دسته: «غذای اصلی»، «برنج و نان»، «سوپ و آش»، «فست‌فود»، «پروتئین»، «لبنیات»، «حبوبات»، «میوه»، «سبزیجات»، «آجیل و خشکبار»، «شیرینی و دسر»، «نوشیدنی»، «میان‌وعده»، «روغن و چاشنی».
pageپرس‌وجوخیرشماره‌ی صفحه، از ۱.
per_pageپرس‌وجوخیرتعداد در هر صفحه، ۱ تا ۱۰۰ (پیش‌فرض ۲۰).

نمونه:

curl -G "https://api.roozanam.ir/v1/foods" \
  -H "Authorization: Bearer $ROOZANAM_KEY" \
  --data-urlencode "q=نان سنگک" \
  --data-urlencode "per_page=5"

نمونه‌ی پاسخ (۲۰۰):

{
  "data": [
    {
      "id": "3f2b8c1e-5d7a-4c2e-9b1f-6a0d4e8c2b71",
      "name": "نان سنگک",
      "name_en": "Sangak bread",
      "category": "برنج و نان",
      "default_serving_g": 50,
      "per_100g": {
        "calories": 270,
        "protein_g": 9,
        "carbs_g": 55,
        "fat_g": 1.5,
        "sugar_g": 1.5,
        "fiber_g": 4,
        "sodium_mg": 420
      }
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "has_more": false
  }
}

GET /v1/foods/{id}ارزش غذایی یک غذا

دسترسی لازم: foods:read · کلید شریک · قابل نگه‌داری تا ۳۰۰ ثانیه با ETag

ارزش غذایی هر ۱۰۰ گرم (با ریزمغذی‌های شناخته‌شده)، یک سهم معمول و پیمانه‌های خانگی همان غذا (مثل «یک کفگیر» یا «یک لیوان») با گرم و ارزش غذایی هر کدام. شناسه‌ی غذایی که در کاتالوگ عمومی نیست، not_found می‌گیرد.

پارامترمحلاجباریتوضیح
idمسیربلهشناسه‌ی غذا از نتیجه‌ی جست‌وجو.

نمونه:

curl "https://api.roozanam.ir/v1/foods/3f2b8c1e-5d7a-4c2e-9b1f-6a0d4e8c2b71" \
  -H "Authorization: Bearer $ROOZANAM_KEY"

نمونه‌ی پاسخ (۲۰۰):

{
  "data": {
    "id": "3f2b8c1e-5d7a-4c2e-9b1f-6a0d4e8c2b71",
    "name": "نان سنگک",
    "name_en": "Sangak bread",
    "aliases": [
      "سنگک",
      "نون سنگک"
    ],
    "category": "برنج و نان",
    "per_100g": {
      "calories": 270,
      "protein_g": 9,
      "carbs_g": 55,
      "fat_g": 1.5,
      "sugar_g": 1.5,
      "fiber_g": 4,
      "sodium_mg": 420,
      "micros": {
        "calcium_mg": 30,
        "iron_mg": 2.5,
        "magnesium_mg": 45,
        "zinc_mg": 1.2
      }
    },
    "default_serving": {
      "label": "یک کف دست",
      "grams": 50,
      "nutrition": {
        "calories": 135,
        "protein_g": 4.5,
        "carbs_g": 27.5,
        "fat_g": 0.8,
        "sugar_g": 0.8,
        "fiber_g": 2,
        "sodium_mg": 210
      }
    },
    "servings": [
      {
        "label": "یک کف دست",
        "grams": 50,
        "nutrition": {
          "calories": 135,
          "protein_g": 4.5,
          "carbs_g": 27.5,
          "fat_g": 0.8,
          "sugar_g": 0.8,
          "fiber_g": 2,
          "sodium_mg": 210
        }
      },
      {
        "label": "نصف نان",
        "grams": 150,
        "nutrition": {
          "calories": 405,
          "protein_g": 13.5,
          "carbs_g": 82.5,
          "fat_g": 2.3,
          "sugar_g": 2.3,
          "fiber_g": 6,
          "sodium_mg": 630
        }
      }
    ],
    "updated_at": "2026-10-20T09:30:00.000Z"
  }
}

دستور پختبانک دستورهای پخت منتشرشده‌ی روزانم (کلید شریک).

GET /v1/recipesفهرست بانک دستور پخت

دسترسی لازم: recipes:read · کلید شریک · قابل نگه‌داری تا ۳۰۰ ثانیه با ETag

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

پارامترمحلاجباریتوضیح
tagپرس‌وجوخیرفقط یک برچسب: وعده، گیاهی، پرپروتئین، کم‌کربوهیدرات یا اقتصادی.
qپرس‌وجوخیربخشی از نام دستور.
pageپرس‌وجوخیرشماره‌ی صفحه، از ۱.
per_pageپرس‌وجوخیرتعداد در هر صفحه، ۱ تا ۱۰۰ (پیش‌فرض ۲۰).

نمونه:

curl -G "https://api.roozanam.ir/v1/recipes" \
  -H "Authorization: Bearer $ROOZANAM_KEY" \
  --data-urlencode "tag=breakfast" \
  --data-urlencode "per_page=10"

نمونه‌ی پاسخ (۲۰۰):

{
  "data": [
    {
      "slug": "adasi-sobhaneh",
      "name": "عدسی صبحانه",
      "description": "عدسی سنتی با عدس و سبزیجات تازه، پخته شده با روغن کم و ادویه‌های ساده برای صبحانه‌ای گرم و مقوی.",
      "servings": 4,
      "serving_grams": 250,
      "per_serving": {
        "calories": 245.6,
        "protein_g": 12.7,
        "carbs_g": 34.5,
        "fat_g": 7.1,
        "sugar_g": 4.2,
        "fiber_g": 9.1,
        "sodium_mg": 310
      },
      "tags": [
        "breakfast",
        "vegetarian"
      ],
      "prep_minutes": 15,
      "cook_minutes": 60,
      "url": "https://roozanam.ir/recipes/adasi-sobhaneh",
      "published_at": "2026-10-21T08:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "has_more": false
  }
}

GET /v1/recipes/{slug}یک دستور پخت

دسترسی لازم: recipes:read · کلید شریک · قابل نگه‌داری تا ۳۰۰ ثانیه با ETag

مواد با مقدار و گرم، مراحل پخت، و ارزش غذایی کل دستور، هر سهم و هر ۱۰۰ گرم. url نشانی صفحه‌ی همین دستور در سایت روزانم است.

پارامترمحلاجباریتوضیح
slugمسیربلهنامک لاتین دستور از فهرست.

نمونه:

curl "https://api.roozanam.ir/v1/recipes/adasi-sobhaneh" \
  -H "Authorization: Bearer $ROOZANAM_KEY"

نمونه‌ی پاسخ (۲۰۰):

{
  "data": {
    "slug": "adasi-sobhaneh",
    "name": "عدسی صبحانه",
    "description": "عدسی سنتی با عدس و سبزیجات تازه، پخته شده با روغن کم و ادویه‌های ساده برای صبحانه‌ای گرم و مقوی.",
    "servings": 4,
    "serving_grams": 250,
    "per_serving": {
      "calories": 245.6,
      "protein_g": 12.7,
      "carbs_g": 34.5,
      "fat_g": 7.1,
      "sugar_g": 4.2,
      "fiber_g": 9.1,
      "sodium_mg": 310
    },
    "tags": [
      "breakfast",
      "vegetarian"
    ],
    "prep_minutes": 15,
    "cook_minutes": 60,
    "url": "https://roozanam.ir/recipes/adasi-sobhaneh",
    "published_at": "2026-10-21T08:00:00.000Z",
    "ingredients": [
      {
        "name": "عدس خشک",
        "quantity": 1,
        "unit": "پیمانه",
        "amount_text": "۱ پیمانه",
        "grams": 190,
        "nutrition": {
          "calories": 669,
          "protein_g": 46.9,
          "carbs_g": 114.1,
          "fat_g": 2,
          "sugar_g": 3.8,
          "fiber_g": 20.3,
          "sodium_mg": 11
        }
      },
      {
        "name": "پیاز",
        "quantity": 1,
        "unit": "عدد",
        "amount_text": "۱ عدد",
        "grams": 110,
        "nutrition": {
          "calories": 44,
          "protein_g": 1.2,
          "carbs_g": 10.3,
          "fat_g": 0.1,
          "sugar_g": 4.7,
          "fiber_g": 1.9,
          "sodium_mg": 4
        }
      }
    ],
    "steps": [
      "عدس را بشویید و یک ساعت خیس کنید.",
      "پیاز را تفت دهید، عدس و آب را اضافه کنید و بگذارید بپزد."
    ],
    "cooked_grams": 1000,
    "raw_grams": 334,
    "totals": {
      "calories": 982.5,
      "protein_g": 50.6,
      "carbs_g": 138,
      "fat_g": 28.4,
      "sugar_g": 16.8,
      "fiber_g": 36.4,
      "sodium_mg": 1240,
      "micros": {
        "iron_mg": 14.6
      }
    },
    "per_100g": {
      "calories": 98.3,
      "protein_g": 5.1,
      "carbs_g": 13.8,
      "fat_g": 2.8,
      "sugar_g": 1.7,
      "fiber_g": 3.6,
      "sodium_mg": 124
    },
    "updated_at": "2026-10-21T08:00:00.000Z"
  }
}

آمارآمار عمومی روزانم، همان عددهای صفحه‌ی اول سایت (کلید شریک).

GET /v1/statsآمار عمومی

دسترسی لازم: stats:read · کلید شریک · قابل نگه‌داری تا ۶۰ ثانیه با ETag

همان عددهای بخش «روزانم در یک نگاه» سایت؛ چند بار در روز دوباره محاسبه می‌شود و زمان محاسبه در computed_at می‌آید.

نمونه:

curl "https://api.roozanam.ir/v1/stats" \
  -H "Authorization: Bearer $ROOZANAM_KEY"

نمونه‌ی پاسخ (۲۰۰):

{
  "data": {
    "computed_at": "2026-10-25T06:20:00.000Z",
    "total_users": 1840,
    "active_users_7d": 612,
    "meals_logged": 48210,
    "activities_logged": 7302,
    "weight_logs": 5120,
    "total_kg_lost": 1312.4,
    "avg_kg_lost_per_user": 3.1,
    "total_kg_gained": 96.5,
    "calories_tracked": 31250000,
    "users_with_results": 431
  }
}

داده‌های منداده‌های خود کاربر و ثبت‌های رایگان (توکن دسترسی شخصی).

GET /v1/me/profileپروفایل و هدف‌ها

دسترسی لازم: profile:read · توکن دسترسی شخصی

هدف، نوع رژیم، عددهای بدن و هدف‌های روزانه‌ی صاحب توکن: کالری، درشت‌مغذی‌ها، آب و قدم. یادداشت‌های پزشکی و شرایط سلامت از راه API داده نمی‌شوند.

نمونه:

curl "https://api.roozanam.ir/v1/me/profile" \
  -H "Authorization: Bearer $ROOZANAM_TOKEN"

نمونه‌ی پاسخ (۲۰۰):

{
  "data": {
    "onboarding_completed": true,
    "timezone": "Asia/Tehran",
    "goal": "lose_weight",
    "diet_type": "balanced",
    "activity_level": "light",
    "body": {
      "gender": "female",
      "age": 32,
      "height_cm": 165,
      "weight_kg": 72.5,
      "start_weight_kg": 76,
      "target_weight_kg": 64
    },
    "targets": {
      "calories": 1650,
      "calories_manual": false,
      "protein_g": 103,
      "carbs_g": 186,
      "carbs_is_max": false,
      "fat_g": 55,
      "sugar_max_g": 41,
      "fiber_g": 25,
      "sodium_max_mg": 2300,
      "water_ml": 2540,
      "steps": 8000
    }
  }
}

GET /v1/me/days/{date}خلاصه‌ی یک روز

دسترسی لازم: diary:read · توکن دسترسی شخصی

کالری خورده‌شده، سوزانده‌شده و باقی‌مانده، وعده‌ها با اقلامشان، فعالیت‌ها، آب، قدم و وزن‌های همان روز — همان چیزی که برگه‌ی «امروز» وب‌اپ نشان می‌دهد. اقلامی که فقط کالری‌شان ثبت شده واحد «کیلوکالری» و صفر گرم دارند.

پارامترمحلاجباریتوضیح
dateمسیربلهروز به وقت کاربر: YYYY-MM-DD (میلادی)، یا today / yesterday. روزهای آینده پذیرفته نمی‌شوند.

نمونه:

curl "https://api.roozanam.ir/v1/me/days/today" \
  -H "Authorization: Bearer $ROOZANAM_TOKEN"

نمونه‌ی پاسخ (۲۰۰):

{
  "data": {
    "date": "2026-10-25",
    "timezone": "Asia/Tehran",
    "calories": {
      "consumed": 214,
      "burned": 310,
      "target": 1650,
      "remaining": 1746,
      "net": -96
    },
    "consumed": {
      "calories": 214,
      "protein_g": 9.3,
      "carbs_g": 28.7,
      "fat_g": 6.8,
      "sugar_g": 1.8,
      "fiber_g": 2,
      "sodium_mg": 630
    },
    "meals": [
      {
        "id": "9a1c4e2b-0d3f-4b6a-8e5c-7f2d1a0b3c4e",
        "type": "breakfast",
        "logged_at": "2026-10-25T05:10:00.000Z",
        "summary": "نان سنگک با پنیر",
        "nutrition": {
          "calories": 214,
          "protein_g": 9.3,
          "carbs_g": 28.7,
          "fat_g": 6.8,
          "sugar_g": 1.8,
          "fiber_g": 2,
          "sodium_mg": 630
        },
        "items": [
          {
            "name": "نان سنگک",
            "quantity": 1,
            "unit": "کف دست",
            "grams": 50,
            "nutrition": {
              "calories": 135,
              "protein_g": 4.5,
              "carbs_g": 27.5,
              "fat_g": 0.8,
              "sugar_g": 0.8,
              "fiber_g": 2,
              "sodium_mg": 210
            }
          },
          {
            "name": "پنیر سفید",
            "quantity": 30,
            "unit": "گرم",
            "grams": 30,
            "nutrition": {
              "calories": 79,
              "protein_g": 4.8,
              "carbs_g": 1.2,
              "fat_g": 6,
              "sugar_g": 1,
              "fiber_g": 0,
              "sodium_mg": 420
            }
          }
        ]
      }
    ],
    "activities": [
      {
        "id": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f",
        "name": "پیاده‌روی تند",
        "duration_min": 30,
        "intensity": "moderate",
        "calories_burned": 150,
        "logged_at": "2026-10-25T14:00:00.000Z"
      }
    ],
    "water": {
      "total_ml": 1500,
      "entries": 6,
      "target_ml": 2540
    },
    "steps": {
      "steps": 9200,
      "source": "manual",
      "goal": 8000,
      "calories_burned": 160
    },
    "weights": [
      {
        "id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
        "weight_kg": 72.5,
        "logged_at": "2026-10-25T04:45:00.000Z",
        "date": "2026-10-25"
      }
    ]
  }
}

GET /v1/me/weightsفهرست وزن‌ها

دسترسی لازم: diary:read · توکن دسترسی شخصی

وزن‌های ثبت‌شده، تازه‌ترین در ابتدا. per_page همان «N وزن آخر» است و با page به عقب می‌روید.

پارامترمحلاجباریتوضیح
pageپرس‌وجوخیرشماره‌ی صفحه، از ۱.
per_pageپرس‌وجوخیرتعداد در هر صفحه، ۱ تا ۱۰۰ (پیش‌فرض ۲۰).

نمونه:

curl -G "https://api.roozanam.ir/v1/me/weights" \
  -H "Authorization: Bearer $ROOZANAM_TOKEN" \
  --data-urlencode "per_page=30"

نمونه‌ی پاسخ (۲۰۰):

{
  "data": [
    {
      "id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
      "weight_kg": 72.5,
      "logged_at": "2026-10-25T04:45:00.000Z",
      "date": "2026-10-25"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "has_more": false
  }
}

POST /v1/me/waterثبت آب

دسترسی لازم: water:write · توکن دسترسی شخصی

یک نوبت آب به همین لحظه ثبت می‌شود (مثل دکمه‌ی «+۱ لیوان»؛ یک لیوان ۲۵۰ میلی‌لیتر است). رایگان و بدون هوش مصنوعی.

بدنه‌ی درخواست (JSON، حداکثر ۴ کیلوبایت):

{
  "amount_ml": 250
}

نمونه:

curl -X POST "https://api.roozanam.ir/v1/me/water" \
  -H "Authorization: Bearer $ROOZANAM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"amount_ml":250}'

نمونه‌ی پاسخ (۲۰۱):

{
  "data": {
    "id": "5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e",
    "amount_ml": 250,
    "logged_at": "2026-10-25T09:12:00.000Z",
    "date": "2026-10-25",
    "day_total_ml": 1750,
    "target_ml": 2540
  }
}

POST /v1/me/weightsثبت وزن

دسترسی لازم: weight:write · توکن دسترسی شخصی

وزن تازه به همین لحظه ثبت می‌شود و مثل ربات، وزن پروفایل و هدف‌های روزانه هم با آن به‌روز می‌شوند. رایگان و بدون هوش مصنوعی.

بدنه‌ی درخواست (JSON، حداکثر ۴ کیلوبایت):

{
  "weight_kg": 72.5
}

نمونه:

curl -X POST "https://api.roozanam.ir/v1/me/weights" \
  -H "Authorization: Bearer $ROOZANAM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"weight_kg":72.5}'

نمونه‌ی پاسخ (۲۰۱):

{
  "data": {
    "id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
    "weight_kg": 72.5,
    "logged_at": "2026-10-25T04:45:00.000Z",
    "date": "2026-10-25",
    "change_from_previous_kg": -0.4,
    "change_from_start_kg": -3.5
  }
}

PUT /v1/me/days/{date}/stepsثبت قدم‌های یک روز

دسترسی لازم: steps:write · توکن دسترسی شخصی

عدد قدم‌های آن روز را می‌گذارد (جایگزین عدد قبلی همان روز می‌شود و با آن جمع نمی‌شود) و بر عدد گام‌شمار گوشی همان روز مقدم است؛ برای امروز و تا ۷ روز قبل. کالری قدم‌ها فراتر از پیاده‌روی‌های ثبت‌شده، جزو سوزانده‌شده‌ی روز حساب می‌شود. رایگان و بدون هوش مصنوعی.

پارامترمحلاجباریتوضیح
dateمسیربلهروز به وقت کاربر: YYYY-MM-DD (میلادی)، یا today / yesterday. روزهای آینده پذیرفته نمی‌شوند.

بدنه‌ی درخواست (JSON، حداکثر ۴ کیلوبایت):

{
  "steps": 9200
}

نمونه:

curl -X PUT "https://api.roozanam.ir/v1/me/days/today/steps" \
  -H "Authorization: Bearer $ROOZANAM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"steps":9200}'

نمونه‌ی پاسخ (۲۰۰):

{
  "data": {
    "date": "2026-10-25",
    "steps": 9200,
    "source": "manual",
    "previous_steps": 6100,
    "goal": 8000,
    "calories_burned": 160
  }
}

۸. کدهای خطا

هر خطا با کد وضعیت HTTP مناسب و بدنه‌ی یکسان {"error": {"code", "message"}} می‌آید؛ code ثابت و ماشین‌خوان است و message توضیح فارسی. در خطای ورودی، فیلد مشکل‌دار در error.field می‌آید. هر پاسخ سرآیند X-Request-Id دارد.

{
  "error": {
    "code": "invalid_request",
    "message": "amount_ml باید عددی بین ۱ تا ۵٬۰۰۰ (میلی‌لیتر) باشد.",
    "field": "amount_ml"
  }
}
HTTPcodeمعنا
۴۰۰invalid_requestپارامتر یا بدنه‌ی درخواست نامعتبر است؛ فیلد مشکل‌دار در error.field می‌آید.
۴۰۱unauthorizedسرآیند Authorization: Bearer … نیامده یا قالب آن درست نیست.
۴۰۱invalid_tokenکلید یا توکن نامعتبر است: اشتباه، ناقص، یا متعلق به حسابی که دیگر فعال نیست.
۴۰۱token_revokedکلید یا توکن باطل شده است و دیگر کار نمی‌کند.
۴۰۳wrong_token_kindاین نشانی با نوع دیگری از اعتبارنامه کار می‌کند: کلید شریک برای کاتالوگ، توکن شخصی برای داده‌های خود کاربر.
۴۰۳insufficient_scopeکلید یا توکن، دسترسی (scope) لازم برای این نشانی را ندارد.
۴۰۴not_foundنشانی یا موردی که خواسته شده وجود ندارد (یا عمومی نیست).
۴۰۵method_not_allowedاین روش HTTP برای این نشانی پشتیبانی نمی‌شود.
۴۱۳payload_too_largeبدنه‌ی درخواست بزرگ‌تر از حد مجاز (۴ کیلوبایت) است.
۴۲۹rate_limitedتعداد درخواست‌ها از سقف گذشته است؛ پس از ثانیه‌های سرآیند Retry-After دوباره بفرستید.
۵۰۰internal_errorخطای پیش‌بینی‌نشده‌ی سرور؛ شناسه‌ی سرآیند X-Request-Id را برای پشتیبانی بفرستید.
۵۰۳service_unavailableسرویس موقتاً در دسترس نیست؛ کمی بعد دوباره امتحان کنید.

۹. نسخه‌بندی

  • همه‌ی نشانی‌ها زیر /v1 هستند. تغییرهای این نسخه فقط افزودنی‌اند (فیلد یا نشانی تازه)؛ تغییری که برنامه‌ها را بشکند در نسخه‌ی تازه (/v2) می‌آید و از پیش اعلام می‌شود و نسخه‌ی قبلی تا مدتی کار می‌کند.
  • سند ماشین‌خوان (OpenAPI 3.1) همیشه در https://api.roozanam.ir/v1/openapi.json است و برای ابزارهایی مثل Postman یا ساختن کلاینت به کار می‌آید.
  • نشانی قدیمی و بدون کلید https://api.roozanam.ir/stats برای خود سایت می‌ماند، اما بخشی از نسخه‌ی ۱ نیست؛ شریکان از /v1/stats استفاده کنند.

۱۰. امنیت و حریم خصوصی

  • کلیدها و توکن‌ها فقط به‌صورت هش SHA-256 ذخیره می‌شوند و در هر درخواست با مقایسه‌ی زمان‌ثابت بررسی می‌شوند.
  • کلید شریک هرگز به داده‌ی کاربران نمی‌رسد. کاتالوگ عمومی فقط غذاهای پایه‌ی بازبینی‌شده است: دستورهای خانگی کاربران، محصولات بسته‌بندی‌ای که کاربران ثبت کرده‌اند و برآوردهای بازبینی‌نشده‌ی هوش مصنوعی در آن نیستند.
  • توکن شخصی فقط داده‌های صاحب خودش را می‌بیند؛ یادداشت‌های پزشکی و شرایط سلامت از راه API داده نمی‌شوند.
  • ساخته شدن هر توکن تازه در ربات به کاربر خبر داده می‌شود، با دکمه‌ای برای باطل کردن همه‌ی توکن‌ها.
  • هیچ نشانی‌ای از API هوش مصنوعی را صدا نمی‌زند؛ استفاده رایگان است و از این راه چیزی برای سرویس‌های هوش مصنوعی فرستاده نمی‌شود.
  • در صورت مشاهده‌ی مشکل امنیتی، لطفاً از «پشتیبانی» ربات @roozanambot خبر بدهید. همچنین حریم خصوصی را ببینید.

۱۱. پشتیبانی

برای گرفتن کلید شریک، افزایش سقف درخواست یا هر سؤالی، از «🆘 پشتیبانی» در ربات @roozanambot پیام بدهید. اگر خطای 500 گرفتید، مقدار سرآیند X-Request-Id همان پاسخ را هم بفرستید.

این صفحه را هم بخوانید: حریم خصوصی