دامنه‌ی اختصاصی

نشانی پیش‌فرض هر پروژه api.fikaro.ir/{slug}/v1 است. با دامنه‌ی اختصاصی، همان API روی نام خودتان جواب می‌دهد:

https://api.example.ir/v1/products

همان کلیدها، همان قوانین، همان سهمیه. فقط نشانی عوض می‌شود — و اسم فیکارو از URLهای اپ شما بیرون می‌رود.

رایگان است، در همه‌ی پلن‌ها، تا پنج دامنه برای هر پروژه.

افزودن

در پنل پروژه، بخش دامنه‌ها ← افزودن دامنه. نام را وارد کنید — معمولاً یک زیردامنه مثل api.example.ir یا backend.example.ir. اگر آدرس کامل را بچسبانید (https://api.example.ir/v1) خودمان نام را از آن درمی‌آوریم.

بعد از افزودن، دو رکورد DNS می‌بینید که باید در پنل میزبان DNS دامنه‌تان ثبت کنید. هر سلول دکمه‌ی کپی دارد.

رکوردها را کجا ثبت کنم؟

جایی که NSهای دامنه به آن اشاره می‌کند — نه لزوماً جایی که دامنه را خریده‌اید.

• دامنه‌ی .ir: در nic.ir چیزی برای ثبت نیست؛ ایرنیک فقط نام‌سرورها را نگه می‌دارد. رکوردها را در همان سرویسی بگذارید که NSهای دامنه را به آن داده‌اید — معمولاً ابر آروان، DNS لیارا، کلادفلر، پارس‌پک، یا پنل هاست. اگر هنوز هیچ‌کدام را ندارید، DNS لیارا و آروان رایگان‌اند: دامنه را آنجا اضافه می‌کنید، NSهایی که می‌دهند را در nic.ir می‌گذارید، و از آن به بعد رکوردها را همان‌جا می‌سازید.
• دامنه‌ی .com و مانند آن: یا پنل DNS خود ثبت‌کننده (اگر NSهای خودش را دارد)، یا همان سرویس بیرونی.

اگر مطمئن نیستید، بپرسید NS دامنه کجاست:

nslookup -type=NS example.ir

خروجی نام سرویس را لو می‌دهد (*.arvancdn.ir، *.liara.ir، *.cloudflare.com، …).

فرم افزودن رکورد در این پنل‌ها همان سه ستون جدول فیکارو را می‌خواهد — نوع، نام رکورد، مقدار — به‌علاوه‌ی مدت زمان اعتبار (TTL) که هر عددی باشد فرقی نمی‌کند؛ پیش‌فرض پنل خوب است. بعضی پنل‌ها در «نام» فقط بخش زیردامنه را می‌خواهند (api به‌جای api.example.ir، و _fikaro.api به‌جای _fikaro.api.example.ir)؛ اگر نام کامل را رد کردند، همین است.

رکوردها

CNAME   api.example.ir            ->  api.fikaro.ir
TXT     _fikaro.api.example.ir    ->  fikaro-verify=<token>

CNAME ترافیک را به فیکارو می‌آورد. TXT ثابت می‌کند صاحب دامنه شمایید — بدون آن، هر کسی که دامنه‌ای را از قبل به این سرور اشاره داده بود می‌توانست آن را روی پروژه‌ی خودش ثبت کند. توکن مخفی نیست؛ همان چیزی است که در پنل می‌بینید.

دامنه‌ی اصلی (بدون زیردامنه) CNAME نمی‌پذیرد. برای example.ir به‌جای CNAME یک رکورد A به آدرسی که پنل نشان می‌دهد بگذارید. رکورد TXT همان است.

اگر دامنه پشت CDN یا پروکسی (مثل ابر آروان با «ابر» روشن، یا کلادفلر با ابر نارنجی) است، برای این رکورد حالت DNS-only را انتخاب کنید. گواهی HTTPS باید روی سرور فیکارو صادر شود و پروکسی جلوی آن را می‌گیرد.

بررسی و گواهی

رکوردها که ثبت شد، دکمه‌ی بررسی را بزنید. پنل می‌گوید کدام رکورد دیده شده و کدام هنوز نه. انتشار DNS معمولاً چند دقیقه است، گاهی تا یک ساعت؛ اگر خودتان نزدید، هر ده دقیقه یک‌بار ما بررسی می‌کنیم.

وقتی هر دو رکورد دیده شد، از Let's Encrypt گواهی HTTPS می‌گیریم. کمتر از یک دقیقه طول می‌کشد و صفحه خودش به‌روز می‌شود. گواهی نود روزه است و تمدیدش با ماست — سی روز مانده به انقضا، خودکار.

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

استفاده

نشانی پایه‌ی API را در اپ‌تان عوض کنید:

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

const db = createClient({
  baseUrl: "https://api.example.ir/v1",
  apiKey: "apck_...",
});

هیچ چیز دیگری فرق نمی‌کند: احراز هویت کاربران (/v1/auth/*)، فایل‌ها (/files/...)، فانکشن‌ها (/v1/fn/...) و همه‌ی رکوردها روی دامنه‌ی خودتان در دسترس‌اند. CORS هم مثل قبل باز است.

دو چیز که عمداً روی دامنه‌ی شما نیست: پنل فیکارو و API پلتفرم (/api/platform/*). دامنه‌ی شما فقط API پروژه‌ی شما را سرو می‌کند.

مستندات تولیدشده (OpenAPI، Postman، Bruno) فعلاً نشانی api.fikaro.ir را چاپ می‌کنند. هر دو نشانی هم‌زمان کار می‌کنند، پس چیزی نمی‌شکند؛ جایگزینی با دامنه‌ی خودتان در برنامه است.

محدودیت‌ها

• تا پنج دامنه برای هر پروژه.
• wildcard (*.example.ir) پشتیبانی نمی‌شود؛ هر نام را جداگانه اضافه کنید.
• زیردامنه‌های fikaro.ir قابل ثبت نیستند.
• نام‌های فارسی (IDN) پذیرفته می‌شوند و به شکل punycode ذخیره می‌شوند.

رفع اشکال

«رکورد CNAME یا A پیدا نشد» — رکورد هنوز منتشر نشده، یا در پنل DNS اشتباه ثبت شده. با nslookup api.example.ir یا dig چک کنید که به api.fikaro.ir یا آدرس آن می‌رسد. اگر تازه ثبت کرده‌اید، چند دقیقه صبر کنید.

«… به x.x.x.x اشاره می‌کند، نه به api.fikaro.ir» — دامنه به جای دیگری می‌رود؛ معمولاً یک رکورد A قدیمی کنار CNAME تازه مانده. رکورد قدیمی را حذف کنید.

«رکورد TXT روی _fikaro.… پیدا نشد» — نام رکورد را دقیقاً _fikaro (با زیرخط) و مقدار را کامل، با fikaro-verify= در ابتدا، ثبت کنید. بعضی پنل‌ها مقدار را داخل گیومه می‌خواهند؛ اشکالی ندارد.

«پاسخ روی http://… از فیکارو نمی‌آید» — چیزی جلوی سرور فیکارو نشسته: CDN با پروکسی روشن، یا یک هاست قدیمی که همان نام هنوز به آن می‌رود. حالت DNS-only را انتخاب کنید و دوباره بررسی بزنید.

«به محدودیت صدور گواهی Let's Encrypt رسیدیم» — چند بار پشت سر هم برای یک نام گواهی خواسته شده. کاری لازم نیست؛ خودمان یک ساعت بعد دوباره تلاش می‌کنیم.