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"
}
}| HTTP | code | معنا |
|---|---|---|
| ۴۰۰ | 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 همان پاسخ را هم بفرستید.
این صفحه را هم بخوانید: حریم خصوصی