به محتوای اصلی

بک‌اند آماده رزرو و نوبت‌دهی

خدمت و کارشناس عمومی، نوبت‌ها خصوصی — بک‌اند کلینیک، سالن و خدمات.

ماه اول رایگانبا پلناسپرسو

اعتبار هدیهٔ ثبت‌نام هزینه‌اش را می‌دهد؛ لازم نیست حتی یک تومان پرداخت کنید.

با دکمهٔ زیر، پروژه روی پلن اسپرسو شروع می‌شود. پلن پیشنهادی این قالب کاپوچینو است، با ۱۵ روز رایگان؛ در قدم پلن با یک کلیک انتخابش می‌کنید.

مناسب برای

  • نوبت‌دهی کلینیک یا مطب
  • سالن زیبایی و آرایشگاه
  • اپ رزرو جلسهٔ مشاوره

همان لحظهٔ ساخت، این‌ها در جدول هستند

خدمت/v1/service
  • ویزیت مشاورهٔ تغذیه۸۵۰٬۰۰۰ تومان
  • جلسهٔ پیگیری۴۰۰٬۰۰۰ تومان
  • آنالیز ترکیب بدن۶۰۰٬۰۰۰ تومان

۴ جدولورود کاربران۴ قانون۲ فانکشن۱۰ ردیف نمونه

با این قالب چه می‌شود ساخت

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

  • ساخت صفحهٔ انتخاب خدمت

    خدمت‌ها و کارشناس‌ها عمومی‌اند؛ با کلید عمومی و بدون ورود خوانده می‌شوند.

    GET /v1/service
  • گرفتن نوبت، با بررسی تداخل

    کاربر واردشده با service_id، staff_id و start_time (و در صورت نیاز customer_note) فانکشن book را صدا می‌زند. سرور زمان پایان را از مدت خدمت و مبلغ را از قیمت خدمت حساب می‌کند و نوبت‌های همهٔ مشتری‌های همان کارشناس را می‌سنجد. ساعت پر با ۴۰۹ slot_taken، ساعتی بیرون از بازه‌های کاری کارشناس در آن روز (به وقت تهران) با ۴۰۹ outside_working_hours و خدمتی که کارشناس ارائه نمی‌دهد با ۴۰۹ service_not_offered رد می‌شود. تداخل را از خود اپ نسنجید: با توکن کاربر فقط نوبت‌های خود او دیده می‌شود، و کلید Production نباید در اپ باشد. POST مستقیم به /v1/booking برای کاربر بسته است.

    POST /v1/fn/book
  • نوبت‌های من

    با توکن کاربر، فهرست نوبت‌ها فقط نوبت‌های خود او را برمی‌گرداند؛ وضعیت نوبت تازه «در انتظار تأیید» است.

    GET /v1/booking
  • لغو نوبت

    کاربر با booking_id فانکشن cancel_booking را صدا می‌زند؛ نوبت «لغوشده» می‌شود، زمان لغو خودکار ثبت می‌شود و ساعت برای دیگران آزاد می‌شود. فقط نوبتی که زمانش نرسیده لغو می‌شود، و نوبت لغوشده دوباره فعال نمی‌شود. وضعیت، ساعت و کارشناس نوبت را کاربر با PATCH عوض نمی‌کند: برای ساعت دیگر لغو کنید و دوباره بگیرید. تأیید و «انجام‌شده» کار خود کسب‌وکار است، با کلید Production یا از پنل.

    POST /v1/fn/cancel_booking

داده‌ای که همان لحظه دارید

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

خدمت

۳ ردیف/v1/service
نامقیمت (تومان)توضیحاتمدت (دقیقه)
ویزیت مشاورهٔ تغذیه۸۵۰٬۰۰۰جلسهٔ ۴۵ دقیقه‌ای بررسی رژیم و برنامهٔ غذایی.۴۵
جلسهٔ پیگیری۴۰۰٬۰۰۰بازبینی روند و اصلاح برنامه، ۲۰ دقیقه.۲۰
آنالیز ترکیب بدن۶۰۰٬۰۰۰اندازه‌گیری با دستگاه و تفسیر نتیجه.۳۰

کارشناس

۲ ردیف/v1/staff
نامعنوان شغلیفعال
دکتر مریم احمدیمتخصص تغذیهبله
دکتر سینا رحیمیکارشناس ارشد تغذیهٔ ورزشیبله

بازهٔ کاری

۳ ردیف/v1/availability
عنوانروز هفتهساعت شروعساعت پایان
شنبه صبحشنبه09:0013:00
دوشنبه عصردوشنبه16:0020:00
یکشنبه صبحیکشنبه10:0014:00

نوبت

۲ ردیف/v1/booking
کد نوبتوضعیتیادداشت مشتریمبلغ هنگام رزرو
NB-1403-0041انجام‌شدهسابقهٔ کم‌خونی دارم.۸۵۰٬۰۰۰
NB-1403-0068تأییدشده—۴۰۰٬۰۰۰

جدول‌ها و دسترسی

هر جدول یک مسیر API دارد و از قبل مشخص است چه کسی می‌خواندش. فیلدهای هر جدول زیر همان جدول باز می‌شوند.

  • خدمت

    /v1/service

    عمومی: هر کسی می‌خواندش، حتی بدون ورود و با کلید عمومی داخل اپ.

    خدمت‌های قابل رزرو — عمومی، فهرستی که اپ قبل از ورود نشان می‌دهد

    ۶ فیلد
    • nameناممتنضروری
    • descriptionتوضیحاتمتن
    • duration_minutesمدت (دقیقه)عددضروری
    • priceقیمت (تومان)عددضروری
    • costهزینهٔ تمام‌شدهعددفقط مدیر
    • activeفعالبله/خیر= true
  • کارشناس

    /v1/staff

    عمومی: هر کسی می‌خواندش، حتی بدون ورود و با کلید عمومی داخل اپ.

    کسانی که خدمت ارائه می‌دهند — عمومی، برای انتخاب در اپ

    ۵ فیلدو ۱ رابطه
    • nameناممتنضروری
    • titleعنوان شغلیمتن
    • photoتصویرفایل
    • phoneتلفنتلفنفقط مدیر
    • activeفعالبله/خیر= true
    • رابطه با خدمتچند به چند
  • بازهٔ کاری

    /v1/availability

    عمومی: هر کسی می‌خواندش، حتی بدون ورود و با کلید عمومی داخل اپ.

    ساعت‌های کاری هر کارشناس — عمومی، تا اپ بتواند تقویم را بسازد

    ۵ فیلدو ۱ رابطه
    • staff_idکارشناسمتنضروری
    • labelعنوانمتن
    • weekdayروز هفتهگزینه‌ای
    • start_hourساعت شروعمتن
    • end_hourساعت پایانمتن
    • رابطه با کارشناسچند به یکstaff_id
  • نوبت

    /v1/booking

    فقط صاحب ردیف: هر کاربر فقط ردیف‌های خودش را می‌بیند. مالکیت از روی customer_id

    نوبت‌ها — هر کاربر فقط نوبت‌های خودش را می‌بیند؛ ثبت فقط از راه فانکشن book

    ۱۱ فیلدو ۳ رابطه
    • customer_idمشتریمتن
    • service_idخدمتمتنضروری
    • staff_idکارشناسمتنضروری
    • referenceکد نوبتمتن
    • start_timeزمان شروعتاریخضروری
    • end_timeزمان پایانتاریخضروری
    • statusوضعیتگزینه‌ای= "pending"
    • price_at_bookingمبلغ هنگام رزروعدد= 0
    • customer_noteیادداشت مشتریمتن
    • staff_noteیادداشت داخلیمتنپنهان
    • cancelled_atزمان لغوتاریخ
    • رابطه با خدمتچند به یکservice_id
    • رابطه با کارشناسچند به یکstaff_id
    • رابطه با کاربرچند به یکcustomer_id

قوانین آماده

منطقی که همراه قالب نصب می‌شود و از لحظهٔ ساخت فعال است، بدون اینکه یک خط کد بنویسید.

  • ثبت زمان لغو

    تریگرروی نوبت
  • جلوگیری از تکمیل نوبت تأییدنشده

    اعتبارسنجیروی نوبت

    پیامی که کاربر می‌گیرد: «نوبت در انتظار تأیید را نمی‌توان مستقیم «انجام‌شده» کرد — اول تأییدش کنید»

  • الزام ترتیب زمان شروع و پایان

    اعتبارسنجیروی نوبت

    پیامی که کاربر می‌گیرد: «زمان پایان باید بعد از زمان شروع باشد»

  • جلوگیری از فعال کردن دوبارهٔ نوبت لغوشده

    اعتبارسنجیروی نوبت

    پیامی که کاربر می‌گیرد: «نوبت لغوشده دوباره فعال نمی‌شود؛ ممکن است این ساعت را کس دیگری گرفته باشد — نوبت تازه بگیرید»

فانکشن‌های آماده

منطقی که نباید دست اپ باشد همراه قالب نصب می‌شود و از لحظهٔ ساخت روشن است. هر فانکشن یک آدرس دارد که اپ یا سرور شما صدایش می‌زند، و از سهمیهٔ فانکشن پلن حساب می‌شود.

  • گرفتن نوبت

    POST /v1/fn/book

    تنها راه گرفتن نوبت: مشتریِ واردشده با service_id، staff_id و start_time (و در صورت نیاز customer_note) صدایش می‌زند. زمان پایان از مدت خدمت و مبلغ از قیمت خدمت حساب می‌شود. نوبتِ بیرون از ساعت کاری کارشناس (۴۰۹ outside_working_hours)، خدمتی که کارشناس ارائه نمی‌دهد (۴۰۹ service_not_offered) و ساعتی که با نوبت مشتری دیگری تداخل دارد (۴۰۹ slot_taken) رد می‌شود.

    کاربران واردشده: کاربری که در اپ وارد شده صدایش می‌زند؛ سرور شما هم با کلید API.

    کد فانکشن
    // book: the only way a customer takes a slot.
    //
    // The booking table reads «own»: a customer's token sees only their own
    // rows, so an app can never tell by itself that someone else holds the
    // slot — and the project's Production key must never ship inside an app.
    // Here ctx.db.admin reads every customer's bookings of that staff member,
    // and none of them is handed back.
    //
    // Decided on the server, never taken from the request: end_time (start +
    // the service's own duration), price_at_booking (the service's own price)
    // and the customer (the caller). The request names only WHICH service,
    // WHICH staff member and WHEN, plus an optional note. Those fields are
    // admin-write in the schema, so a direct POST /v1/booking from an app is
    // refused and this function is the only door.
    //
    // Two requests at the same instant: each checks, writes, and then looks
    // again. A booking that, once written, finds any other live booking
    // overlapping it deletes itself and answers 409. Of two racing bookings
    // the one written second always sees the first (each write commits before
    // its second look starts), so two overlapping bookings never both stay; at
    // worst both step back and the customer simply tries again.
    //
    // Working hours: the whole booking must sit inside one of the staff
    // member's availability rows for that weekday, read in Tehran time (Iran
    // has kept a fixed +03:30 since 2022). No row for the day: no bookings
    // that day.
    //
    // Services: when the staff member's «services» link names any service,
    // only those are taken. A staff member with none linked takes every
    // service — the template's demo data has no links (seed rows cannot
    // write a many-to-many link), and a new project must not refuse every
    // booking until someone fills them in. A project under active access
    // policies cannot include a relation; there the check is skipped and the
    // run's log says so.
    //
    // Budget: at most 7 of the 25 database calls.
    function fail(status, code, message) {
      throw {status: status, code: code, message: message};
    }
    // A row that is not there — or an id that is not even an id — is null;
    // any other refusal (the call budget, authorization being unavailable)
    // goes up as is.
    function getOrNull(handle, entity, id) {
      try { return handle.get(entity, id); } catch (e) {
        if (e && (e.status === 404 || e.status === 400)) return null;
        throw e;
      }
    }
    
    // An API key has no customer to book for; only a signed-in customer books.
    if (ctx.auth !== "user" || !ctx.user.id) {
      fail(403, "login_required", "نوبت را خود مشتریِ واردشده با توکن خودش می‌گیرد، نه با کلید API");
    }
    const me = ctx.user.id;
    
    const body = ctx.request.body;
    const input = body && typeof body === "object" && !Array.isArray(body) ? body : {};
    const serviceId = typeof input.service_id === "string" ? input.service_id.trim() : "";
    const staffId = typeof input.staff_id === "string" ? input.staff_id.trim() : "";
    const startRaw = typeof input.start_time === "string" ? input.start_time.trim() : "";
    const note = input.customer_note == null ? "" : String(input.customer_note).trim();
    if (!serviceId) fail(400, "service_required", "خدمت را با service_id بفرستید");
    if (!staffId) fail(400, "staff_required", "کارشناس را با staff_id بفرستید");
    if (note.length > 400) fail(400, "note_too_long", "یادداشت نوبت حداکثر ۴۰۰ نویسه است");
    
    // A date and a clock, optionally with a zone. Without one it is Tehran
    // time, the same reading the API gives a zone-less date everywhere else.
    const shape = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d{3})?)?)(Z|[+-]\d{2}:\d{2})?$/.exec(startRaw);
    const start = shape ? Date.parse(shape[1] + (shape[2] || "+03:30")) : NaN;
    if (isNaN(start)) {
      fail(400, "invalid_start_time", "start_time را به شکل 2026-09-01T09:30:00Z یا 2026-09-01T13:00:00+03:30 بفرستید");
    }
    if (start <= Date.now()) fail(400, "start_in_past", "زمان شروع گذشته است؛ ساعتی در آینده انتخاب کنید");
    
    const service = getOrNull(ctx.db, "service", serviceId);
    if (!service || service.active === false) {
      fail(404, "service_not_found", "این خدمت پیدا نشد یا فعال نیست");
    }
    // The staff member with the services they offer, in one read.
    let staff = null;
    let offered = null; // null: not known (see the header)
    try {
      const found = ctx.db.list("staff", {filter: {id: staffId}, include: "services", limit: 1});
      staff = found.length > 0 ? found[0] : null;
      if (staff) offered = Array.isArray(staff.services) ? staff.services : [];
    } catch (e) {
      if (e && e.status === 400) {
        staff = null; // an id that is not even an id
      } else if (e && e.code === "policy_path_unsupported") {
        ctx.log("book: active access policies cannot include staff.services; the service check is skipped");
        staff = getOrNull(ctx.db, "staff", staffId);
      } else {
        throw e;
      }
    }
    if (!staff || staff.active === false) {
      fail(404, "staff_not_found", "این کارشناس پیدا نشد یا فعال نیست");
    }
    if (offered && offered.length > 0 && !offered.some(function (s) { return s.id === service.id; })) {
      fail(409, "service_not_offered", "«" + staff.name + "» خدمت «" + service.name + "» را ارائه نمی‌دهد؛ کارشناس دیگری انتخاب کنید");
    }
    const minutes = Number(service.duration_minutes);
    if (!(minutes > 0)) fail(409, "service_without_duration", "مدت این خدمت تعریف نشده است");
    
    // ── working hours, in Tehran time ──────────────────────────────────────
    const TEHRAN = 210 * 60000; // +03:30
    const DAYS = ["sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday"];
    const FA = {saturday: "شنبه", sunday: "یکشنبه", monday: "دوشنبه", tuesday: "سه‌شنبه",
      wednesday: "چهارشنبه", thursday: "پنجشنبه", friday: "جمعه"};
    const local = new Date(start + TEHRAN);
    const weekday = DAYS[local.getUTCDay()];
    const begins = local.getUTCHours() * 60 + local.getUTCMinutes() + local.getUTCSeconds() / 60;
    const ends = begins + minutes;
    function toMin(t) {
      const m = /^(\d{2}):(\d{2})$/.exec(String(t || ""));
      return m ? Number(m[1]) * 60 + Number(m[2]) : NaN;
    }
    const shifts = ctx.db.list("availability", {filter: {staff_id: staff.id, weekday: weekday}, limit: 20});
    const fits = shifts.some(function (sh) {
      return toMin(sh.start_hour) <= begins && ends <= toMin(sh.end_hour);
    });
    if (!fits) {
      const hours = shifts
        .filter(function (sh) { return !isNaN(toMin(sh.start_hour)) && !isNaN(toMin(sh.end_hour)); })
        .map(function (sh) { return sh.start_hour + " تا " + sh.end_hour; });
      fail(409, "outside_working_hours", hours.length > 0
        ? "«" + staff.name + "» " + FA[weekday] + "‌ها فقط " + hours.join("، ") + " (به وقت تهران) کار می‌کند و این نوبت در آن جا نمی‌شود"
        : "«" + staff.name + "» " + FA[weekday] + "‌ها نوبت نمی‌دهد");
    }
    
    const from = new Date(start).toISOString();
    const to = new Date(start + minutes * 60000).toISOString();
    const TAKEN = "این ساعت برای این کارشناس پر است؛ ساعت دیگری انتخاب کنید";
    
    // Every customer's live bookings of this staff member that overlap
    // [from, to). Back-to-back is not an overlap: one ends as the next begins.
    function overlapping(limit) {
      return ctx.db.admin.list("booking", {
        filter: {
          staff_id: staff.id,
          "start_time[lt]": to,
          "end_time[gt]": from,
          "status[in]": ["pending", "confirmed"],
        },
        limit: limit,
      });
    }
    
    if (overlapping(1).length > 0) fail(409, "slot_taken", TAKEN);
    
    const suffix = ("0" + Math.floor(Math.random() * 1296).toString(36)).slice(-2);
    const row = {
      customer_id: me,
      service_id: service.id,
      staff_id: staff.id,
      start_time: from,
      end_time: to,
      price_at_booking: Number(service.price) || 0,
      reference: "NB-" + (Date.now().toString(36) + suffix).toUpperCase(),
    };
    if (note) row.customer_note = note;
    const created = ctx.db.admin.create("booking", row);
    
    // The second look. Two rows are enough: at most one of them is this one.
    for (const other of overlapping(2)) {
      if (other.id !== created.id) {
        ctx.db.admin.delete("booking", created.id);
        fail(409, "slot_taken", TAKEN);
      }
    }
    
    ctx.respond(201, created);
    
  • لغو نوبت

    POST /v1/fn/cancel_booking

    مشتریِ واردشده با booking_id نوبت خودش را لغو می‌کند؛ زمان لغو ثبت و ساعت برای دیگران آزاد می‌شود. فقط نوبت «در انتظار تأیید» یا «تأییدشده» که زمانش نرسیده لغو می‌شود، و صدا زدن دوباره روی نوبت لغوشده همان را برمی‌گرداند. وضعیت نوبت را مشتری مستقیم نمی‌نویسد.

    کاربران واردشده: کاربری که در اپ وارد شده صدایش می‌زند؛ سرور شما هم با کلید API.

    کد فانکشن
    // cancel_booking: the one status change a customer makes.
    //
    // status is admin-write, so «confirmed» and «completed» stay the
    // clinic's to set. This function reads the booking through the caller's
    // own handle — a customer sees only their own bookings, so anyone
    // else's is simply «not found» — and writes the cancellation with
    // ctx.db.admin. The template's trigger stamps cancelled_at.
    function fail(status, code, message) {
      throw {status: status, code: code, message: message};
    }
    if (ctx.auth !== "user" || !ctx.user.id) {
      fail(403, "login_required", "نوبت را خود مشتریِ واردشده با توکن خودش لغو می‌کند، نه با کلید API");
    }
    const body = ctx.request.body;
    const input = body && typeof body === "object" && !Array.isArray(body) ? body : {};
    const id = typeof input.booking_id === "string" ? input.booking_id.trim() : "";
    if (!id) fail(400, "booking_required", "نوبت را با booking_id بفرستید");
    
    let booking = null;
    try { booking = ctx.db.get("booking", id); } catch (e) {
      if (!e || (e.status !== 404 && e.status !== 400)) throw e;
    }
    // An admin's own token reads every booking; a customer cancels only theirs.
    if (!booking || booking.customer_id !== ctx.user.id) {
      fail(404, "booking_not_found", "این نوبت پیدا نشد یا مال شما نیست");
    }
    if (booking.status === "cancelled") ctx.respond(booking);
    if (booking.status !== "pending" && booking.status !== "confirmed") {
      fail(409, "booking_not_cancellable", "فقط نوبت «در انتظار تأیید» یا «تأییدشده» لغو می‌شود");
    }
    if (Date.parse(booking.start_time) <= Date.now()) {
      fail(409, "booking_started", "زمان این نوبت رسیده یا گذشته است و دیگر لغو نمی‌شود");
    }
    ctx.respond(ctx.db.admin.update("booking", booking.id, {status: "cancelled"}));
    

اولین درخواست

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

نمایش خدمت‌ها و کارشناس‌ها

خدمت‌ها، کارشناس‌ها و بازه‌های کاری عمومی‌اند — اپ می‌تواند کل ویترین و تقویم را بدون ورود کاربر بسازد.

npm install @fikaro/client
import { createClient } from "@fikaro/client";

const client = createClient({
  project: "{{slug}}",
  key: "{{publishable_key}}",
});

// ویترین: خدمت‌های فعال و کارشناس‌ها
const { data: services } = await client.from("service").list({
  filter: { active: true },
});
const { data: staff } = await client.from("staff").list({ filter: { active: true } });

// گرفتن نوبت نیازمند ورود است و فقط از راه فانکشن book:
// زمان پایان و مبلغ را سرور حساب می‌کند و ساعت پر را با ۴۰۹ رد می‌کند
await client.auth.login("patient@example.com", "«رمزی که هنگام ساخت پروژه دیدید»");
// نوبت باید داخل ساعت کاری کارشناس باشد (به وقت تهران)
const { data: hours } = await client.from("availability").list({
  filter: { staff_id: staff[0].id },
});
// مثلاً hours[0] = { weekday: "saturday", start_hour: "09:00", end_hour: "13:00" }
const booking = await client.request("POST", "/fn/book", {
  service_id: services[0].id,
  staff_id: staff[0].id,
  start_time: "2026-12-05T09:30:00+03:30", // یک شنبه، داخل همان بازه
});
// booking.end_time و booking.price_at_booking را سرور پر کرده است

// نوبت‌های خود کاربر — فقط مال خودش
const { data: mine } = await client.from("booking").list();

// لغو: ساعت برای دیگران آزاد می‌شود
await client.request("POST", "/fn/cancel_booking", { booking_id: booking.id });

کلید عمومی فقط ویترین را می‌خواند: خدمت، کارشناس و بازهٔ کاری. نوبت‌ها «فقط مال خود کاربر» هستند، پس برای گرفتن یا دیدن نوبت باید وارد شود، و نوبت را فقط فانکشن book می‌سازد تا تداخل با نوبت دیگران و ساعت کاری کارشناس سمت سرور سنجیده شود؛ لغو هم با فانکشن cancel_booking است. شمارهٔ تلفن کارشناس و هزینهٔ تمام‌شده حتی برای کاربر واردشده هم برنمی‌گردد.

قالب‌های دیگر

از همین قالب شروع کنید؛ بک‌اندش با من.

ماه اول رایگانبا پلناسپرسو

اعتبار هدیهٔ ثبت‌نام هزینه‌اش را می‌دهد؛ لازم نیست حتی یک تومان پرداخت کنید.

شروع رایگان با این قالب