DocMaker DocMakerDEVELOPERS
فقط خواندنی صفحه اصلی
DocMakerراهنمای توسعه‌دهندگان DocMaker
داده عمومی

راهنمای توسعه‌دهندگان DocMaker

دریافت و نمایش داده‌های عمومی اسناد منتشرشده در وب‌سایت و نرم‌افزار شما

بدون کلید دسترسیفقط خواندنیCORS120 req/min
نشانی اصلی

تمام نمونه‌ها از دامنه اصلی DocMaker استفاده می‌کنند. در محیط توسعه نیز خروجی عمومی روی همین دامنه قابل مصرف است.

GEThttps://docmaker.ir/data

فهرست سندهای مادر منتشرشده، ترجمه‌ها و اطلاعات سازنده.

GEThttps://docmaker.ir/data/<slug-or-uuid>

جزئیات کامل یک سند و آرایه صفحات و ماژول‌های آن.

پارامترها

نامنوعتوضیحنمونه
pageintegerشماره صفحه فهرست1
per_pageintegerتعداد نتیجه؛ بین ۱ تا ۳۰12
qstringجستجو در عنوان، آدرس و شرکتniawell
langstringانتخاب ترجمه منتشرشدهfa
typestringنوع سندcatalog
companystringslug شرکتlegacy-4

ساختار پاسخ

پاسخ جزئیات سند در کلید data قرار دارد. هر صفحه شامل آرایه blocks است و مقدار type مشخص می‌کند کدام ماژول باید رندر شود.

dataobjecttitlestringcompanyobjecttranslationsarraycontent.pagesarraypages[].blocksarray
{
  "ok": true,
  "data": {
    "title": "Catalog title",
    "language": "fa",
    "company": { "name": "Company name" },
    "content": {
      "pages": [
        { "blocks": [
          { "type": "heading", "content": "عنوان" },
          { "type": "specs", "content": [] }
        ] }
      ]
    }
  }
}
رندر رسمی DocMaker

همان ظاهر واقعی کاتالوگ، بدون بازطراحی دستی

این روش از همان کلاس‌ها و همان فایل استایل صفحه عمومی کاتالوگ استفاده می‌کند. بنابراین جدول دینامیک، ویژگی‌ها، تصاویر، فرمول، مشخصات، ابعاد، سربرگ و پاورقی با ظاهر واقعی DocMaker نمایش داده می‌شوند؛ نه با یک CSS نمونه و متفاوت.

روش پیشنهادی

سه فایل رسمی Font Awesome، استایل رندر سند و رندرر عمومی را اضافه کنید؛ سپس خروجی /data/<slug> را مستقیماً رندر کنید.

پیش‌نمایش با استایل واقعی کاتالوگهمان کلاس‌های document.html
<link rel="stylesheet"
      href="https://docmaker.ir/static/vendor/fontawesome/css/all.min.css">
<link rel="stylesheet"
      href="https://docmaker.ir/static/fonts/font.css">
<link rel="stylesheet"
      href="https://docmaker.ir/static/css/document-renderer.css">

<div id="docmaker-catalog" aria-live="polite"></div>

<script src="https://docmaker.ir/static/js/catalog-api-renderer.js" defer></script>
/* فقط برای قرارگیری کاتالوگ داخل صفحه شما؛
   ظاهر بلوک‌ها از document-renderer.css می‌آید. */
#docmaker-catalog {
  width: min(100%, 794px);
  margin-inline: auto;
}
#docmaker-catalog .doc-page {
  max-width: 100%;
}
@media (max-width: 820px) {
  #docmaker-catalog {
    overflow: hidden;
  }
  #docmaker-catalog .doc-page {
    transform-origin: top center;
  }
}
document.addEventListener('DOMContentLoaded', async () => {
  const target = document.querySelector('#docmaker-catalog');
  try {
    await DocMakerCatalogRenderer.fetchAndRender(
      target,
      'https://docmaker.ir/data/YOUR_DOCUMENT_SLUG'
    );
  } catch (error) {
    target.textContent = 'خطا در دریافت کاتالوگ: ' + error.message;
  }
});
جدول دینامیک واقعی

رندر dynamic_specs با همان ساختار mainTable، مدل‌های چهارتایی، ادغام مقادیر تکراری و کلاس‌های واقعی کاتالوگ.

تمام Content Typeها

رندرر آماده، ۱۶ نوع محتوای واقعی ویرایشگر را می‌شناسد و از همان نام کلاس‌های قالب عمومی استفاده می‌کند.

رنگ و قالب خود سند

متغیرهای --doc-accent، اندازه متن، فاصله صفحه و preset از داده خود سند اعمال می‌شوند.

مرجع کامل بلوک‌ها

انواع محتوای داخل pages[].blocks

هر بلوک چهار فیلد مشترک دارد: id شناسه یکتا، type نام ماژول، content داده اصلی و settings تنظیمات نمایشی. رندرر شما باید نوع‌های ناشناخته را نادیده بگیرد تا با نسخه‌های آینده سازگار بماند.

{
  "id": "block-uuid",
  "type": "heading",
  "content": "عنوان بخش",
  "settings": { "align": "start" }
}
  • idبرای key در React و اتصال ویرایش‌ها استفاده کنید.
  • typeانتخاب می‌کند کدام کامپوننت یا تابع رندر اجرا شود.
  • contentبسته به نوع می‌تواند string، object یا array باشد.
  • settingsتنظیمات اختیاری نمایش است؛ همیشه مقدار پیش‌فرض داشته باشید.
الگوی پیشنهادی رندر

در JavaScript یا React یک map از نام type به renderer بسازید. اگر type شناخته‌شده نبود، آن بلوک را رد کنید و خطای کل صفحه ایجاد نکنید.

heading

عنوان

برای تیترهای اصلی و فرعی سند استفاده می‌شود. مقدار content یک رشته ساده است و سطح تیتر از settings.level تعیین می‌شود.

ساختار contentstring
فیلدهای مهم settingslevel: 1 تا 6، align: start | center | end | left | right
نمونه JSON بلوک
{
  "id": "block-1",
  "type": "heading",
  "content": "مشخصات فنی",
  "settings": {
    "level": 2,
    "align": "start"
  }
}

برای ساخت فهرست، عنوان صفحه و سئو بهتر است متن content بدون HTML باشد.

richtext / html

متن و HTML

محتوای متنی قالب‌بندی‌شده. richtext نوع اصلی است و html به‌عنوان نام سازگار با نسخه‌های قدیمی پذیرفته می‌شود.

ساختار contentstring شامل HTML مانند p، ul، ol، strong، em، a و table
فیلدهای مهم settingsalign و تنظیمات تایپوگرافی مانند fontSize، lineHeight و spacing
نمونه JSON بلوک
{
  "id": "block-2",
  "type": "richtext",
  "content": "<p>این دستگاه برای <strong>کار مداوم</strong> طراحی شده است.</p><ul><li>راندمان بالا</li><li>نصب آسان</li></ul>",
  "settings": {
    "align": "start",
    "fontSize": 16,
    "lineHeight": 1.9
  }
}

هنگام تزریق در DOM، HTML را فقط از خروجی مورد اعتماد DocMaker بگیرید و برای داده‌های خارجی دوباره پاک‌سازی کنید.

callout

نکته، هشدار و پیام برجسته

یک متن HTML برجسته برای نکته فنی، هشدار ایمنی، پیام موفقیت یا خطا.

ساختار contentstring شامل HTML
فیلدهای مهم settingstone: info | success | warning | danger، align و semantic
نمونه JSON بلوک
{
  "id": "block-3",
  "type": "callout",
  "content": "<p><strong>هشدار:</strong> پیش از نصب، برق ورودی را قطع کنید.</p>",
  "settings": {
    "tone": "warning",
    "align": "start"
  }
}

رنگ و آیکون را بر اساس tone انتخاب کنید؛ متن هشدار را تنها با رنگ مشخص نکنید و آیکون/عنوان هم داشته باشید.

image

تصویر تکی

نمایش یک تصویر با متن جایگزین، زیرنویس، اندازه و نحوه برازش قابل کنترل.

ساختار contentobject: url، name، alt
فیلدهای مهم settingswidth درصدی، height، fit: contain | cover | fill | scale-down، align و caption
نمونه JSON بلوک
{
  "id": "block-4",
  "type": "image",
  "content": {
    "url": "https://docmaker.ir/static/example/product.webp",
    "name": "product.webp",
    "alt": "نمای جلوی محصول"
  },
  "settings": {
    "width": 70,
    "height": "auto",
    "fit": "contain",
    "align": "center",
    "caption": "نمای جلوی محصول"
  }
}

همیشه alt معنادار قرار دهید و loading="lazy" و decoding="async" را در خروجی وب فعال کنید.

image_grid

گالری یا تصاویر کنار هم

آرایه‌ای از تصاویر که می‌تواند به‌صورت یک تا چهار ستون، با ارتفاع خودکار یا ثابت نمایش داده شود.

ساختار contentarray از objectهای url، name، alt، width، height، span، fit، x و y
فیلدهای مهم settingscolumns، gap، fit، height، autoHeight، width و align
نمونه JSON بلوک
{
  "id": "block-5",
  "type": "image_grid",
  "content": [
    {
      "url": "https://docmaker.ir/static/example/front.webp",
      "alt": "نمای جلو",
      "span": 1,
      "fit": "contain",
      "x": 50,
      "y": 50
    },
    {
      "url": "https://docmaker.ir/static/example/back.webp",
      "alt": "نمای پشت",
      "span": 1,
      "fit": "contain",
      "x": 50,
      "y": 50
    }
  ],
  "settings": {
    "columns": 2,
    "gap": 16,
    "autoHeight": true,
    "width": 100,
    "align": "center"
  }
}

در برخی داده‌های قدیمی ممکن است آرایه تصاویر داخل content.images باشد؛ رندرر مقاوم بهتر است هر دو شکل را پشتیبانی کند.

signature

امضا یا مهر

از نظر داده شبیه image است اما برای امضا، مهر و عنوان زیر آن طراحی شده است.

ساختار contentobject: url، name، alt
فیلدهای مهم settingswidth، height، fit، align، label و caption
نمونه JSON بلوک
{
  "id": "block-6",
  "type": "signature",
  "content": {
    "url": "https://docmaker.ir/static/example/signature.webp",
    "name": "signature.webp",
    "alt": "امضای مدیر فنی"
  },
  "settings": {
    "width": 35,
    "height": "auto",
    "fit": "contain",
    "align": "end",
    "label": "مدیر فنی"
  }
}

برای حفظ شفافیت مهر یا امضا، PNG یا WebP شفاف مناسب‌تر است.

table

جدول معمولی

جدول ساده دوبعدی. ردیف اول معمولاً سرستون‌هاست و سایر ردیف‌ها داده هستند.

ساختار contentarray دوبعدی؛ هر عضو یک ردیف و هر مقدار یک سلول است
فیلدهای مهم settingsstriped و repeatHeader
نمونه JSON بلوک
{
  "id": "block-7",
  "type": "table",
  "content": [
    [
      "مدل",
      "توان",
      "ولتاژ"
    ],
    [
      "NX-18",
      "18 kW",
      "380V"
    ],
    [
      "NX-22",
      "22 kW",
      "400V"
    ]
  ],
  "settings": {
    "striped": true,
    "repeatHeader": true
  }
}

برای موبایل جدول را داخل ظرف overflow-x:auto قرار دهید و سرستون‌ها را با th رندر کنید.

specs

مشخصات کلیدی

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

ساختار contentarray از objectهای label و value
فیلدهای مهم settingsمعمولاً خالی؛ تنظیمات تایپوگرافی عمومی قابل استفاده است
نمونه JSON بلوک
{
  "id": "block-8",
  "type": "specs",
  "content": [
    {
      "label": "توان نامی",
      "value": "22 kW"
    },
    {
      "label": "درجه حفاظت",
      "value": "IP65"
    },
    {
      "label": "گارانتی",
      "value": "24 ماه"
    }
  ],
  "settings": {}
}

این نوع را می‌توان به‌صورت dl/dt/dd یا جدول دو ستونه دسترس‌پذیر رندر کرد.

columns

ستون‌بندی محتوا

چند قطعه HTML را در ستون‌های مستقل قرار می‌دهد و در موبایل می‌تواند زیر هم نمایش داده شود.

ساختار contentarray از رشته‌های HTML؛ تعداد معمولاً 2 تا 4
فیلدهای مهم settingscount و stackMobile
نمونه JSON بلوک
{
  "id": "block-9",
  "type": "columns",
  "content": [
    "<h3>مزایا</h3><p>راندمان بالا و نگهداری آسان.</p>",
    "<h3>کاربرد</h3><p>تابلو برق و خطوط تولید.</p>"
  ],
  "settings": {
    "count": 2,
    "stackMobile": true
  }
}

اگر stackMobile فعال است، در عرض کم grid-template-columns را به یک ستون تبدیل کنید.

formula

فرمول و رابطه ریاضی

رشته‌ی فرمول که می‌تواند متن ریاضی ساده یا ورودی TeX/LaTeX باشد. برای نمایش حرفه‌ای از MathJax یا KaTeX استفاده کنید.

ساختار contentstring مانند E = mc² یا \(P = V \times I\)
فیلدهای مهم settingsمعمولاً خالی؛ fontSize، align و spacing قابل استفاده است
نمونه JSON بلوک
{
  "id": "block-10",
  "type": "formula",
  "content": "\\(P = V \\times I\\)",
  "settings": {
    "fontSize": 22,
    "align": "center"
  }
}

قبل از اجرای MathJax، content را با textContent وارد کنید یا فقط دستورهای مجاز TeX را بپذیرید.

standards

استانداردها و گواهی‌ها

شناسه یا شماره استانداردها را نگهداری می‌کند تا لوگو/نشان متناظر از کتابخانه دارایی‌ها نمایش داده شود.

ساختار contentarray از string یا number مانند IEC، CE یا شماره فایل نشان
فیلدهای مهم settingssemantic: standards
نمونه JSON بلوک
{
  "id": "block-11",
  "type": "standards",
  "content": [
    "CE",
    "IEC-61439",
    "ISO-9001"
  ],
  "settings": {
    "semantic": "standards"
  }
}

اگر برای یک شناسه تصویر موجود نیست، متن استاندارد را به‌عنوان fallback نشان دهید.

features_applications

ویژگی‌ها و کاربردها

دو فهرست مستقل برای مزایا/ویژگی‌های محصول و محیط‌های کاربرد آن.

ساختار contentobject با دو آرایه features و applications
فیلدهای مهم settingssemantic: features_applications و تنظیمات تایپوگرافی
نمونه JSON بلوک
{
  "id": "block-12",
  "type": "features_applications",
  "content": {
    "features": [
      "حفاظت چندمرحله‌ای",
      "راندمان بالا"
    ],
    "applications": [
      "خط تولید",
      "تابلو برق صنعتی"
    ]
  },
  "settings": {
    "semantic": "features_applications"
  }
}

هر فهرست ممکن است خالی باشد؛ فقط بخش‌هایی را رندر کنید که حداقل یک عضو دارند.

model_encoding

کدگذاری مدل

بخش‌های یک نام مدل را به معنی هر قطعه از کد متصل می‌کند.

ساختار contentarray از objectهای model و meaning
فیلدهای مهم settingssemantic: model_encoding
نمونه JSON بلوک
{
  "id": "block-13",
  "type": "model_encoding",
  "content": [
    {
      "model": "NX",
      "meaning": "خانواده محصول"
    },
    {
      "model": "22",
      "meaning": "توان نامی 22 کیلووات"
    },
    {
      "model": "P",
      "meaning": "سه‌فاز"
    }
  ],
  "settings": {
    "semantic": "model_encoding"
  }
}

ترتیب آرایه مهم است و باید از چپ به راست مطابق کد واقعی مدل حفظ شود.

dynamic_specs

جدول دینامیک چندمدلی

کامل‌ترین نوع جدول برای مقایسه چند مدل. سطرها در بخش‌ها گروه‌بندی می‌شوند و values مقدار هر ویژگی را برای هر مدل نگه می‌دارد.

ساختار contentobject شامل models و sections؛ هر section دارای name، subtitle و features است؛ هر feature شامل name، values و allSame است
فیلدهای مهم settingssemantic: dynamic_specs و repeatHeader
نمونه JSON بلوک
{
  "id": "block-14",
  "type": "dynamic_specs",
  "content": {
    "models": [
      "NX-18",
      "NX-22"
    ],
    "sections": [
      {
        "name": "مشخصات الکتریکی",
        "subtitle": "ورودی",
        "features": [
          {
            "name": "توان نامی",
            "values": {
              "NX-18": "18 kW",
              "NX-22": "22 kW"
            },
            "allSame": false
          },
          {
            "name": "فرکانس",
            "values": {
              "NX-18": "50 Hz",
              "NX-22": "50 Hz"
            },
            "allSame": true
          }
        ]
      }
    ]
  },
  "settings": {
    "semantic": "dynamic_specs",
    "repeatHeader": true
  }
}

مدل‌ها را از content.models بخوانید، سپس برای هر feature مقدار values[model] را پیدا کنید. allSame فقط یک راهنمای بهینه‌سازی نمایش است و نباید جای values را بگیرد.

dimensions

ابعاد محصول

طول، عرض و ارتفاع را با واحد اصلی و در صورت نیاز واحدهای جایگزین نگهداری می‌کند.

ساختار contentobject: length، width، height، unit و other_units
فیلدهای مهم settingssemantic: dimensions
نمونه JSON بلوک
{
  "id": "block-15",
  "type": "dimensions",
  "content": {
    "length": "510",
    "width": "220",
    "height": "440",
    "unit": "mm",
    "other_units": [
      {
        "unit": "in",
        "length": "20.08",
        "width": "8.66",
        "height": "17.32"
      }
    ]
  },
  "settings": {
    "semantic": "dimensions"
  }
}

مقادیر ممکن است string باشند؛ برای محاسبه ابتدا با Number تبدیل و نامعتبر بودن را بررسی کنید.

page_break

شکست صفحه

یک دستور چیدمان است و محتوای دیداری ندارد. هر بلوک بعد از آن باید از صفحه تازه شروع شود.

ساختار contentرشته خالی یا null
فیلدهای مهم settingsobject خالی
نمونه JSON بلوک
{
  "id": "block-16",
  "type": "page_break",
  "content": "",
  "settings": {}
}

در HTML معمولی می‌توانید آن را نمایش ندهید؛ برای چاپ از break-after: page یا page-break-after: always استفاده کنید.

اتصال با زبان‌ها

در همه نمونه‌ها پاسخ شبکه و وضعیت HTTP بررسی شده است. این کدها فقط داده را دریافت می‌کنند و چیزی در DocMaker تغییر نمی‌دهند.

Fetch API
async function loadDocuments() {
  const response = await fetch('https://docmaker.ir/data?lang=fa&per_page=6', {
    headers: { Accept: 'application/json' }
  });

  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  const payload = await response.json();
  return payload.data;
}

loadDocuments().then(console.log).catch(console.error);
React Hook
import { useEffect, useState } from 'react';

export default function PublishedDocuments() {
  const [documents, setDocuments] = useState([]);
  const [error, setError] = useState('');

  useEffect(() => {
    const controller = new AbortController();
    fetch('https://docmaker.ir/data?per_page=6', {
      signal: controller.signal,
      headers: { Accept: 'application/json' }
    })
      .then(response => {
        if (!response.ok) throw new Error(`HTTP ${response.status}`);
        return response.json();
      })
      .then(payload => setDocuments(payload.data))
      .catch(error => error.name !== 'AbortError' && setError(error.message));

    return () => controller.abort();
  }, []);

  if (error) return <p>{error}</p>;
  return <ul>{documents.map(item => <li key={item.uuid}>{item.title}</li>)}</ul>;
}
Python / Flask
from flask import Flask, jsonify
import requests

app = Flask(__name__)

@app.get('/published-documents')
def published_documents():
    response = requests.get(
        'https://docmaker.ir/data',
        params={'lang': 'fa', 'per_page': 6},
        headers={'Accept': 'application/json'},
        timeout=15,
    )
    response.raise_for_status()
    return jsonify(response.json()['data'])
PHP
<?php
$url = 'https://docmaker.ir/data?lang=fa&per_page=6';
$context = stream_context_create([
  'http' => [
    'method' => 'GET',
    'header' => "Accept: application/json\r\n",
    'timeout' => 15
  ]
]);

$json = file_get_contents($url, false, $context);
if ($json === false) {
  throw new RuntimeException('Unable to load published documents.');
}

$documents = json_decode($json, true, 512, JSON_THROW_ON_ERROR)['data'];
foreach ($documents as $document) {
  echo htmlspecialchars($document['title']) . "<br>";
}
cURL
curl --request GET \
  --url 'https://docmaker.ir/data?lang=fa&per_page=6' \
  --header 'Accept: application/json'

متن و HTML پویا

این نمونه، بلوک‌های heading و richtext/html را با همان کلاس‌های واقعی کاتالوگ رندر می‌کند. هیچ استایل جداگانه‌ای برای شبیه‌سازی نوشته نشده است.

پیش‌نمایش زنده
<div id="catalog-text" class="template-niawell" dir="rtl">
  <main class="doc-content"></main>
</div>
@import url('https://docmaker.ir/static/css/document-renderer.css');

#catalog-text {
  --doc-accent: #2657a4;
  --doc-body-size: 15px;
  --doc-heading-size: 20px;
}
const blocks = data.content.pages
  .flatMap(page => page.blocks || [])
  .filter(block => ['heading', 'richtext', 'html'].includes(block.type));

const main = document.querySelector('#catalog-text .doc-content');
main.innerHTML = blocks.map(block =>
  DocMakerCatalogRenderer.renderBlockHTML(block, { direction: 'rtl' })
).join('');

پیام و هشدار پویا

هشدار و نکته با کلاس‌های واقعی block-callout، rich-content و tone-* رندر می‌شوند.

پیش‌نمایش زنده
<div id="catalog-callout" class="template-niawell" dir="rtl">
  <main class="doc-content"></main>
</div>
@import url('https://docmaker.ir/static/css/document-renderer.css');
#catalog-callout { --doc-accent: #2657a4; }
const block = data.content.pages
  .flatMap(page => page.blocks || [])
  .find(item => item.type === 'callout');

document.querySelector('#catalog-callout .doc-content').innerHTML =
  block ? DocMakerCatalogRenderer.renderBlockHTML(block, { direction: 'rtl' }) : '';

جدول دینامیک

این همان جدول واقعی کاتالوگ است: مدل‌ها چهارتایی گروه‌بندی می‌شوند، مقادیر یکسان ادغام می‌شوند و کلاس‌های mainTable، dynamic-section-group و dynamic-parameter-cell عیناً استفاده می‌شوند.

پیش‌نمایش زنده
<div id="catalog-specs" class="template-niawell" dir="rtl">
  <main class="doc-content"></main>
</div>
@import url('https://docmaker.ir/static/css/document-renderer.css');
#catalog-specs { --doc-accent: #2657a4; overflow-x: auto; }
#catalog-specs .doc-content { min-width: 700px; }
const block = data.content.pages
  .flatMap(page => page.blocks || [])
  .find(item => item.type === 'dynamic_specs');

const main = document.querySelector('#catalog-specs .doc-content');
main.innerHTML = block
  ? DocMakerCatalogRenderer.renderBlockHTML(block, { direction: 'rtl' })
  : '<p>جدول دینامیک در این سند وجود ندارد.</p>';

فهرست دینامیک

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

پیش‌نمایش زنده
<div id="catalog-features" class="template-niawell" dir="rtl">
  <main class="doc-content"></main>
</div>
@import url('https://docmaker.ir/static/css/document-renderer.css');
#catalog-features { --doc-accent: #2657a4; }
const block = data.content.pages
  .flatMap(page => page.blocks || [])
  .find(item => item.type === 'features_applications');

document.querySelector('#catalog-features .doc-content').innerHTML =
  block ? DocMakerCatalogRenderer.renderBlockHTML(block, { direction: 'rtl' }) : '';

خطاها و محدودیت‌ها

200درخواست موفق
304نسخه کش‌شده معتبر است
404سند عمومی پیدا نشد
429تعداد درخواست بیش از حد مجاز
برای عملیات مدیریتی استفاده نکنید

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