یک نقطهٔ مشترک،
برای زمان.

دریافت زمان سرور

درخواست زیر زمان سیستم‌عامل سرور را به UTC برمی‌گرداند. این سرویس به کلید API یا حساب کاربری نیاز ندارد. زمان روی سرور خوانده می‌شود و پاسخ کش نمی‌شود.

مسیر کوتاه جایگزین: /api/getTime. درخواست‌های مرورگر از دامنه‌های دیگر نیز برای این دو مسیر مجاز هستند.

{
  "utc": "—",
  "unixTimeMilliseconds": null,
  "timeZone": "UTC"
}

ساختار پاسخ

پاسخ موفق با وضعیت 200 OK و نوع application/json ارسال می‌شود. هر دو نمایش زمان از یک نمونهٔ مشترک تولید می‌شوند.

نمونهٔ زندهٔ بالا به API همین سرور درخواست می‌فرستد؛ زمان نمایشی از ساعت دستگاه شما تولید نمی‌شود.

محاسبهٔ اختلاف ساعت

زمان دریافت پاسخ را مستقیماً برابر زمان سرور نگیرید؛ رفت‌وبرگشت شبکه تأخیر دارد. برای یک تخمین ساده، زمان محلی را پیش از ارسال (t0) و بلافاصله پس از دریافت (t1) ثبت کنید:

roundTripMs = t1 - t0
offsetMs = serverUnixMs - ((t0 + t1) / 2)
estimatedServerNowMs = localNowMs + offsetMs

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

نمونهٔ استفاده در C#

آدرس پایه را دامنهٔ واقعی سایت قرار دهید. یک نمونهٔ HttpClient را در طول عمر برنامه استفاده کنید. خطاهای شبکه و timeout باید در برنامهٔ فراخوان مدیریت شوند.

using System.Diagnostics;
using System.Net.Http.Json;

// Reuse this client for requests to Faratechno.
using var client = new HttpClient
{
    BaseAddress = new Uri("https://faratechno.net"),
    Timeout = TimeSpan.FromSeconds(10)
};

var t0 = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds();
var elapsed = Stopwatch.StartNew();
var response = await client.GetFromJsonAsync<ServerTime>("api/v1/time")
    ?? throw new InvalidOperationException("Empty time response.");
elapsed.Stop();
var t1 = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds();

if (response.TimeZone != "UTC" ||
    response.Utc.Offset != TimeSpan.Zero ||
    response.Utc.ToUnixTimeMilliseconds() != response.UnixTimeMilliseconds ||
    Math.Abs((t1 - t0) - elapsed.Elapsed.TotalMilliseconds) > 100)
    throw new InvalidOperationException("Invalid sample or local clock changed.");

double offsetMs = response.UnixTimeMilliseconds - ((t0 / 2.0) + (t1 / 2.0));
// Apply the offset in the application, not to the operating-system clock.
var estimatedUtc = DateTimeOffset.UtcNow.AddMilliseconds(offsetMs);

public sealed record ServerTime(
    DateTimeOffset Utc, long UnixTimeMilliseconds, string TimeZone);

آماده برای سرویس‌های بعدی

مسیر /api/v1 برای توسعهٔ APIها در نظر گرفته شده است. سرویس‌های ثبت محصول، دریافت به‌روزرسانی و حساب کاربری در مراحل بعدی، همراه با سیاست احراز هویت و مستندات خود اضافه می‌شوند؛ در نسخهٔ فعلی فقط سرویس زمان فعال است.