مستندات

داده‌ی عمومی

داده‌ی عمومی پروفایل

JSON، Markdown، vCard، کد QR، کارت ویزیت چاپی و کارت قابل‌جاسازی برای هر پروفایل عمومی، بدون کلید API.

هر صفحه‌ی پروفایل عمومی نسخه‌های ماشین‌خوان دارد که از همان داده‌ی نمایش‌داده‌شده در صفحه ساخته می‌شوند. کلید API نمی‌خواهند و برای استفاده‌ی سایت‌های دیگر هستند. ایمیل هیچ‌وقت در آن‌ها نیست.

قالب آدرس نوع محتوا
JSON https://avatarak.ir/{username}.json application/json
Markdown https://avatarak.ir/{username}.md text/markdown
vCard 3.0 https://avatarak.ir/{username}.vcf text/vcard (با نام {username}.vcf دانلود می‌شود)
کارت قابل‌جاسازی https://avatarak.ir/{username}.card text/html
کد QR https://avatarak.ir/{username}.qr image/svg+xml
تصویر اشتراک‌گذاری https://avatarak.ir/{username}/share.svg image/svg+xml (۱۰۸۰×۱۳۵۰)
کارت چاپی https://avatarak.ir/{username}/print text/html

اگر پروفایل وجود نداشته باشد یا کاربر صفحه را خاموش کرده باشد، همه‌ی قالب‌ها 404 می‌دهند.

JSON

curl https://avatarak.ir/javid.json
{
  "username": "javid",
  "url": "https://avatarak.ir/javid",
  "display_name": "جاوید میرزایی",
  "name_fa": "جاوید میرزایی",
  "name_en": "Javid Mirzaei",
  "headline": "Full-stack engineer",
  "location": "Tehran",
  "bio": "Founder and engineer.",
  "website": "https://javid.example.ir",
  "avatar_url": "https://avatarak.ir/javid/avatar?s=512&v=Kx3Qm1",
  "verified": true,
  "socials": { "github": "https://github.com/javid" },
  "links": [
    { "label": "Portfolio", "url": "https://javid.example.ir/work", "description": "My projects.", "image": "https://avatarak.ir/thumb/9c1f..." }
  ],
  "verified_accounts": [
    { "network": "website", "identifier": "javid.example.ir", "url": "https://javid.example.ir" },
    { "network": "telegram", "identifier": "javid_t", "url": "https://t.me/javid_t" }
  ],
  "gallery": [
    { "url": "https://avatarak.ir/javid/gallery/7/full", "thumb_url": "https://avatarak.ir/javid/gallery/7/thumb", "caption": "Our office", "width": 1600, "height": 1067 }
  ],
  "sections": [
    { "title": "Opening hours", "body": "Sat–Wed, 9 to 17" }
  ],
  "created_at": "2026-11-01T10:12:00+00:00",
  "updated_at": "2026-11-17T20:41:00+00:00"
}
فیلد نکته
avatar_url وقتی کاربر عکسش را مخفی کرده null است
verified اگر صاحب حداقل یک ایمیل را تأیید کرده باشد true است
socials شبکه ← آدرس کامل (برخلاف REST API که نام کاربری برمی‌گرداند)
links[].image فقط وقتی کاربر تصویر کنار لینک‌ها را روشن کرده باشد هست
verified_accounts حساب‌هایی که کاربر ثابت کرده مال خودش است: حساب‌های تأییدشده را ببینید
gallery عکس‌هایی که مالک اضافه کرده، به ترتیب؛ اگر پنهان باشد خالی است. اندازه‌ی کامل حداکثر ۱۶۰۰ پیکسل است
sections بخش‌های متنی آزاد که مالک نوشته (title و body؛ متن ساده)
language fa یا en: زبانِ متن‌های این پاسخ
languages زبان‌هایی که صفحه دارد؛ پروفایل دوزبانه یک شیء translations هم دارد

زبان‌ها

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

  • تک‌زبانه: کل صفحه، شامل برچسب‌ها و جهت متن، همیشه به همان زبان است، هر زبانی که بازدیدکننده استفاده کند. متن‌ها هرگز قاطی نمی‌شوند.
  • دوزبانه: هر متن دو نسخه دارد. بازدیدکننده نسخه‌ی هم‌زبان خودش را می‌بیند (با ?lang=fa یا ?lang=en هم می‌شود صریح انتخاب کرد)، صفحه سوییچ زبان دارد و برای موتورهای جست‌وجو لینک‌های hreflang اضافه می‌شود. اگر یک نسخه خالی باشد، نسخه‌ی دیگر نشان داده می‌شود.

فیلد language می‌گوید متن‌های پاسخ به چه زبانی است و languages فهرست زبان‌های صفحه را می‌دهد. روی پروفایل دوزبانه، /{username}.json یک شیء translations با هر دو نسخه هم دارد و .json، .md و .vcf پارامتر ?lang= را می‌پذیرند. REST API هم ?lang= را می‌پذیرد.

فیلدهایی که کاربر خالی گذاشته null، شیء خالی یا فهرست خالی‌اند.

استفاده از مرورگر

این endpointها Access-Control-Allow-Origin: * می‌فرستند، پس از هر صفحه‌ی وب می‌توانید بخوانیدشان:

const profile = await (await fetch('https://avatarak.ir/javid.json')).json();
document.querySelector('#name').textContent = profile.display_name;

کارت قابل‌جاسازی

یک کارت پروفایل کوچک که می‌توانید در صفحه‌ی خودتان بگذارید:

<iframe src="https://avatarak.ir/javid.card" width="380" height="104" style="border:0" loading="lazy"></iframe>

همین کد در پنجره‌ی جزئیات بیشتر هر صفحه‌ی پروفایل هم هست، همراه با یک کد QR قابل‌دانلود از آدرس پروفایل (در خود مرورگر ساخته می‌شود).

کد QR، کارت ویزیت و تصویر اشتراک‌گذاری

/{username}.qr یک کد QR برداری (vector) از آدرس پروفایل است، پس در هر اندازه‌ی چاپی واضح می‌ماند.

پارامتر پیش‌فرض توضیح
size 512 عرض و ارتفاع به پیکسل، 64 تا 2048
fg و bg 101517 و ffffff رنگ‌ها به‌صورت هگز (1D4FC4 یا #abc). جفت‌رنگی که کنتراست آن زیر ۳ به ۱ باشد با 422 رد می‌شود، چون گوشی نمی‌تواند آن را اسکن کند.
margin 2 عرض حاشیه‌ی سفید به‌صورت واحد ماژول، 0 تا 8
content آدرس پروفایل با vcard به‌جای آدرس، کارت مخاطب را کد می‌کند (اگر برای اسکن مطمئن بیش‌ازحد فشرده باشد، به آدرس برمی‌گردد)
download با 1 به‌صورت فایل دانلودی ارسال می‌شود

/{username}/share.svg یک کارت عمودی (عکس یا حروف اول، نام، عنوان و کد QR) برای پست یا استوری است؛ برای ذخیره ?download=1 را اضافه کنید. /{username}/print یک کارت ویزیت ۸۵×۵۵ میلی‌متری آماده‌ی چاپ است؛ با ?sheet=1 یک برگه‌ی A4 شامل ده کارت می‌گیرید.

هدرها و محدودیت

هدر مقدار
Cache-Control public, max-age=300
Access-Control-Allow-Origin *
X-Robots-Tag noindex, nofollow، مگر اینکه کاربر ایندکس شدن در موتورهای جست‌وجو را اجازه داده باشد

محدودیت: ۶۰ درخواست در دقیقه برای هر آدرس IP. نتیجه را سمت خودتان کش کنید و برای هر بازدید صفحه درخواست ندهید.