API ترازیا

با این API می‌توانید سایت، اپلیکیشن یا فروشگاه اینترنتی خود را به حسابداری وصل کنید: اشخاص و کالاها را بخوانید و بنویسید، موجودی و قیمت را همگام کنید و سفارش‌ها را به‌صورت فاکتور فروش ثبت کنید. همه اسناد حسابداری و انبار همان‌طور ساخته می‌شوند که از داخل برنامه.

در برنامه به تنظیمات ← API و فروشگاه اینترنتی بروید و یک کلید با دسترسی‌های لازم بسازید.
کلید را فقط سمت سرور نگه دارید؛ هرگز در کد مرورگر یا اپ موبایل قرار ندهید.
درخواست‌ها را به https://YOUR-DOMAIN/api/v1 بفرستید.

احراز هویت

کلید را در سرآیند Authorization بفرستید. هر کلید به یک کسب‌وکار تعلق دارد و با مجوزهای کاربری که آن را ساخته کار می‌کند؛ پس هم دسترسی (scope) کلید و هم نقش آن کاربر بررسی می‌شود.

curl https://YOUR-DOMAIN/api/v1/products?q=روغن \
  -H "Authorization: Bearer dk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

دسترسی	کاربرد
parties:read	خواندن اشخاص و مانده
parties:write	ثبت شخص
products:read	خواندن کالا، قیمت و موجودی
products:write	ثبت کالا
invoices:read	خواندن فاکتورها
invoices:write	ثبت فاکتور فروش و سفارش

قراردادها

مبالغ همیشه به ریال و به‌صورت رشته هستند (مثلاً "18500000") تا اعداد بزرگ دقیق بمانند. در ورودی، عدد یا رشته پذیرفته می‌شود.
مقادیر کالا رشته اعشاری‌اند (تا ۴ رقم اعشار).
تاریخ‌ها میلادی با قالب YYYY-MM-DD؛ تبدیل به شمسی با شماست.
صفحه‌بندی با page و limit؛ وقتی تعداد نتایج کمتر از limit شد، صفحه آخر است.
محدودیت: ۱۲۰ درخواست در دقیقه برای هر کلید.
پاسخ موفق همیشه داخل data است و خطا داخل error.

خطاها

{ "error": { "code": "invalid", "message": "موجودی «روغن موتور» در انبار مرکزی کافی نیست" } }

HTTP	code	توضیح
400	bad_json / bad_kind	بدنه یا پارامتر نامعتبر
401	unauthorized / bad_signature	کلید نامعتبر یا باطل‌شده؛ امضای وب‌هوک نادرست
402	read_only	اشتراک کسب‌وکار تمام شده؛ فقط خواندن ممکن است
403	forbidden / module	کلید این دسترسی را ندارد، یا سازنده کلید مجوز ندارد، یا API در طرح فعال نیست
404	not_found	رکورد پیدا نشد
422	invalid	خطای اعتبارسنجی یا قاعده حسابداری (مثلاً موجودی کافی نیست)؛ message فارسی و قابل نمایش است
429	rate_limited	بیش از ۱۲۰ درخواست در دقیقه برای هر کلید

GET/partiesفهرست اشخاصparties:read

اشخاص (مشتری، تأمین‌کننده و…) به ترتیب کد. جستجو روی نام، کد و تلفن.

q	string	عبارت جستجو
page	int	شماره صفحه، از ۱
limit	int	تعداد در صفحه، حداکثر ۲۰۰ (پیش‌فرض ۵۰)

پاسخ

{
  "data": [
    { "id": "6f1c…", "code": "0001", "kind": "person", "name": "علی رضایی",
      "national_id": "0012345678", "economic_code": null, "roles": ["customer"],
      "phones": ["09121234567"], "email": null, "city": "تهران",
      "address": "…", "postal_code": null, "active": true }
  ],
  "page": 1, "limit": 50
}

GET/parties/{id}یک شخص با مانده حسابparties:read

اگر سازنده کلید مجوز دیدن مانده اشخاص را داشته باشد، فیلد balance (ریال، مثبت = بدهکار) هم برمی‌گردد.

پاسخ

{ "data": { "id": "6f1c…", "name": "علی رضایی", "…": "…", "balance": "12500000" } }

POST/partiesثبت شخصparties:write

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

بدنه درخواست

{
  "kind": "person",
  "name": "علی رضایی",
  "national_id": "0012345678",
  "roles": ["customer"],
  "phones": ["09121234567"],
  "city": "تهران",
  "address": "خیابان …"
}

پاسخ

{ "data": { "id": "6f1c…" } }   // 201 Created

GET/productsفهرست کالاها با موجودیproducts:read

sku همان کد کالاست. stock جمع موجودی همه انبارهاست (برای خدمات برنمی‌گردد).

q	string	نام، کد یا بارکد
page	int
limit	int

پاسخ

{
  "data": [
    { "id": "a2b9…", "code": "1001", "sku": "1001", "barcode": "6260000000017",
      "name": "روغن موتور ۴ لیتری", "kind": "goods", "unit": "عدد",
      "sale_price": "18500000", "tax_rate": "10", "active": true, "stock": "42" }
  ],
  "page": 1, "limit": 50
}

GET/products/{id}یک کالاproducts:read

برای همگام‌سازی قیمت و موجودی در فروشگاه اینترنتی.

پاسخ

{ "data": { "id": "a2b9…", "sku": "1001", "sale_price": "18500000", "stock": "42", "…": "…" } }

POST/productsثبت کالاproducts:write

sale_price به ریال است. tax_rate درصد مالیات ارزش افزوده.

بدنه درخواست

{ "sku": "1002", "name": "فیلتر روغن", "unit": "عدد", "sale_price": 3200000, "tax_rate": 10, "barcode": "6260000000024" }

پاسخ

{ "data": { "id": "c71e…" } }   // 201 Created

GET/invoicesفهرست فاکتورهاinvoices:read

تاریخ‌ها میلادی با قالب YYYY-MM-DD هستند.

kind	string	sale (پیش‌فرض)، sale_return، purchase، purchase_return
from	date	از تاریخ
to	date	تا تاریخ
page	int
limit	int

پاسخ

{
  "data": [
    { "id": "e0d4…", "kind": "sale", "number": 1024, "date": "2026-10-20", "due_date": null,
      "party_id": "6f1c…", "status": "confirmed", "subtotal": "37000000", "discount": "0",
      "tax": "3700000", "total": "40700000", "external_ref": "woo:5531",
      "moodian_status": "accepted", "tax_id": "A1B2C3…" }
  ],
  "page": 1, "limit": 50
}

GET/invoices/{id}یک فاکتور با ردیف‌هاinvoices:read

پاسخ

{ "data": { "id": "e0d4…", "…": "…", "lines": [
  { "product_id": "a2b9…", "description": "", "quantity": "2", "unit_price": "18500000",
    "discount": "0", "tax": "3700000", "total": "40700000" } ] } }

POST/invoicesثبت فاکتور فروش (سفارش)invoices:write

مشتری را با party_id بدهید یا با customer؛ در حالت دوم مشتری با شماره موبایل پیدا یا ساخته می‌شود. کالا با product_id یا sku (کد یا بارکد). اگر unit_price نفرستید قیمت فروش کالا استفاده می‌شود. با confirm=true فاکتور تأیید می‌شود و سند و خروج انبار ثبت می‌شود؛ وگرنه پیش‌نویس می‌ماند. external_ref کلید یکتایی است: ارسال دوباره همان سفارش، فاکتور قبلی را برمی‌گرداند (کد 200 و created=false).

بدنه درخواست

{
  "external_ref": "order-5531",
  "customer": { "name": "مریم احمدی", "phone": "09123334444", "city": "شیراز", "address": "…" },
  "lines": [
    { "sku": "1001", "quantity": 2 },
    { "sku": "1002", "quantity": 1, "unit_price": 3000000, "discount": 200000 }
  ],
  "shipping": 500000,
  "discount_code": "NOROOZ",
  "notes": "تحویل عصر",
  "confirm": true
}

پاسخ

{ "data": { "id": "e0d4…", "number": 1025, "status": "confirmed", "total": "…" }, "created": true }   // 201

اتصال ووکامرس (بدون برنامه‌نویسی)

در ترازیا: تنظیمات ← API و فروشگاه اینترنتی ← فعال‌سازی اتصال. آدرس تحویل و رمز نمایش داده می‌شود. اگر قیمت‌های فروشگاه تومان است، گزینه مربوط را روشن کنید.
در وردپرس: ووکامرس ← پیکربندی ← پیشرفته ← وب‌هوک‌ها ← افزودن. موضوع: «سفارش ایجاد شد» (و در صورت نیاز «سفارش به‌روز شد»)، آدرس تحویل و رمز را وارد کنید، نسخه API: WP REST API v3.
SKU هر محصول در ووکامرس باید با کد کالا یا بارکد آن در ترازیا یکی باشد.

فقط سفارش‌های با وضعیت processing، completed یا on-hold ثبت می‌شوند. مشتری با موبایل پیدا یا ساخته می‌شود، هزینه ارسال به‌صورت اضافات فاکتور و تخفیف ردیف‌ها ثبت می‌شود. هر سفارش با شناسه woo:ORDER_ID فقط یک بار فاکتور می‌شود، حتی اگر وب‌هوک چند بار برسد. امضای HMAC-SHA256 هر درخواست بررسی می‌شود.

فروشگاه‌های دیگر

برای هر فروشگاه دیگری (اختصاصی، دیجی‌کالا مارکت‌پلیس با واسط، اپ موبایل) پس از پرداخت موفق، سفارش را با POST /invoices و یک external_ref یکتا بفرستید. برای همگام‌سازی موجودی، هر چند دقیقه GET /products را بخوانید.

// Node.js
const res = await fetch("https://YOUR-DOMAIN/api/v1/invoices", {
  method: "POST",
  headers: { "Authorization": `Bearer ${process.env.DAFTARA_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    external_ref: `shop-${order.id}`,
    customer: { name: order.name, phone: order.mobile },
    lines: order.items.map((i) => ({ sku: i.sku, quantity: i.qty, unit_price: i.priceRial })),
    shipping: order.shippingRial,
    confirm: true,
  }),
});
const { data, error } = await res.json();

# PHP
$ch = curl_init("https://YOUR-DOMAIN/api/v1/products?limit=200&page=1");
curl_setopt_array($ch, [
  CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("DAFTARA_KEY")],
  CURLOPT_RETURNTRANSFER => true,
]);
$products = json_decode(curl_exec($ch), true)["data"];

ورود به برنامه