مستندات توسعه‌دهنده چرتکه

# آدرس پایه هلو: http://[IP]:8080/TncHoloo/api  (نام دیتابیس هلو را از پیکربندی بگیرید)

# ۱) لاگین — رمز عبور را Base64 کنید
curl -X POST "http://[IP-Server-Hello]:8080/TncHoloo/api/Login" \
  -H "Content-Type: application/json" \
  -d '{"userinfo":{"username":"admin","userpass":"<Base64 رمز>","dbname":"Holoo1"}}'

# پاسخ موفق:
# {"Login":{"State":"True","Token":"Bearer <token>","ErrorCode":0,"Error":""}}

# ۲) برای همه متدها لازم است:
#    Authorization: Bearer <token>
#    Content-Type: application/json

// وبهوک چرتکه ← درج فاکتور در هلو (Node.js / Next.js)
export async function POST(req) {
  // ۱) تأیید امضای X-Chortke-Signature — کد بخش «وبهوک» بالا
  const payload = await req.json();
  if (payload.event !== "document.created") return Response.json({ ok: true });
  const d = payload.data;

  const holo = "http://[IP-Server-Hello]:8080/TncHoloo/api";
  const token = "<Token-از-لاگین>"; // با لاگین گرفته و کش کنید

  const body = {
    invoiceinfo: [{
      Type: "3", // 1=فروش  2=برگشت از فروش  3=خرید  4=برگشت از خرید
      customererpcode: d.buyerErpCode, // ErpCode طرف‌حساب ثبت‌شده در هلو
      date: "2026-09-16",              // میلادی YYYY-MM-DD (تاریخ شمسی را تبدیل کنید)
      time: "10:30",
      Cash: Number(d.finalAmount),
      Discount: 0,
      detailinfo: {
        ProductErpCode: d.itemErpCode, // ErpCode کالای ثبت‌شده در هلو
        few: Number(d.quantity ?? 1),
        price: Number(d.finalAmount),
        levy: 0,
        scot: 0,
      },
    }],
  };

  await fetch(`${holo}/Invoice/Invoice`, {
    method: "POST",
    headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
    body: JSON.stringify(body),
  });
  return Response.json({ ok: true });
}

POST http://[IP]:8080/TncHoloo/api/webhook/subscribe
Content-Type: application/json

{"subscriptions":[{"url":"https://server.com/hook","tablename":"product","apikey":"<کلید ثابت>"}]}

# tablename مجاز: customer | product | mainGroup | sideGroup | resInvoice
# اعلان دریافتی: {"Dbname":"Holoo1","Table":"product","operation":"create|update|delete","changedfields":"[...]"}

# آدرس پایه سپیدار: http://localhost:7373 (از تنظیمات «حالت سرویس‌دهنده» قابل تغییر است)

# ۱) ثبت دستگاه (یک‌بار) — پاسخ شامل کلید عمومی (قالب XML / RSA) برای رمزنگاری است
curl -X POST "http://[IP-Sepidar]:7373/api/Devices/Register" \
  -H "Content-Type: application/json" \
  -d '{"DeviceName":"Chortke"}'

# ۲) لاگین
#    برای هر درخواست یک GUID جدید به‌عنوان ArbitraryCode بسازید:
#    EncArbitraryCode = Base64( RSA-PKCS1-v1_5(ArbitraryCode, کلید عمومی) )
curl -X POST "http://[IP-Sepidar]:7373/api/users/login" \
  -H "Authorization: Bearer <JWT>" \
  -H "GenerationVersion: 1" \
  -H "IntegrationID: <شناسه-دستگاه-Registered>" \
  -H "ArbitraryCode: <GUID-جدید>" \
  -H "EncArbitraryCode: <Base64-RSA>" \
  -H "Content-Type: application/json" \
  -d '{"UserName":"<نام کاربری>","PasswordHash":"<MD5-رمز>"}'

# ۳) برای همه متدها: Authorization: Bearer JWT + GenerationVersion + IntegrationID + ArbitraryCode + EncArbitraryCode

// وبهوک چرتکه ← ثبت فاکتور در سپیدار (Node.js / Next.js)
// توابع Register/Login و encryptRSA را طبق مستندات رسمی سپیدار پیاده کنید.
export async function POST(req) {
  // ۱) تأیید امضای X-Chortke-Signature — کد بخش «وبهوک» بالا
  const payload = await req.json();
  if (payload.event !== "document.created") return Response.json({ ok: true });
  const d = payload.data;

  const headers = {
    "Content-Type": "application/json",
    Authorization: "Bearer <JWT-از-لاگین>",
    GenerationVersion: "1",
    IntegrationID: "<IntegrationID-از-Register>",
    ArbitraryCode: crypto.randomUUID(),
    EncArbitraryCode: encryptRSA(crypto.randomUUID()), // RSA PKCS#1 v1.5 + Base64
  };

  const body = {
    GUID: crypto.randomUUID(),     // جلوگیری از ثبت تکراری (Idempotency)
    CustomerRef: d.customerRef,    // شناسه مشتری ثبت‌شده در سپیدار
    SaleTypeRef: d.saleTypeRef ?? 1,
    DiscountOnCustomer: 0,
    Price: Number(d.finalAmount),  // مبلغ ناخالص
    Discount: 0,
    Tax: 0,
    Duty: 0,
    Addition: 0,
    Items: [{
      ItemRef: d.itemRef,          // شناسه کالا در سپیدار
      StockRef: 0,
      Quantity: Number(d.quantity ?? 1),
      SecondaryQuantity: 0,
      Fee: Number(d.finalAmount),
      Description: d.invoiceNumber,
    }],
  };

  await fetch("http://[IP-Sepidar]:7373/api/invoices/", {
    method: "POST",
    headers,
    body: JSON.stringify(body),
  });
  return Response.json({ ok: true });
}

// وبهوک چرتکه ← ایجاد فاکتور در دیدار (Node.js / Next.js)
const API_KEY = "<کلید-API-دیدار>";

export async function POST(req) {
  // تأیید امضا — کد بخش «وبهوک» بالا
  const payload = await req.json();
  if (payload.event !== "document.created") return Response.json({ ok: true });
  const d = payload.data;

  const body = {
    Items: [{
      ProductId: d.productId,           // از Search Products / Get Products By Code
      Title: d.title ?? "فاکتور چرتکه",
      Quantity: Number(d.quantity ?? 1),
      Unit: d.unit ?? "عدد",
      UnitPrice: Number(d.finalAmount),
      Discount: 0,
      DiscountPercent: 0,
      DiscountType: "Amount",
      TaxPercent: d.taxPercent ?? 0,
    }],
    SellerInfo: {
      SellerName: "<نام فروشنده>",
      BizDomainId: "<BizDomainId فروشنده>", // الزامی
    },
    BuyerInfo: {
      BuyerType: "Company",
      BuyerName: d.buyer,
      BuyerEconomicCode: d.buyerEconomicCode ?? "",
    },
    IssueDate: "2026-09-16T10:30:00.000Z",
  };

  await fetch(`https://app.didar.me/api/AccountingInvoice/Create?apikey=${API_KEY}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });
  return Response.json({ ok: true });
}

// وبهوک چرتکه ← ثبت فاکتور در حسابفا (Node.js / Next.js)
export async function POST(req) {
  // تأیید امضا — کد بخش «وبهوک» بالا
  const payload = await req.json();
  if (payload.event !== "document.created") return Response.json({ ok: true });
  const d = payload.data;

  const res = await fetch("https://api.hesabfa.com/v1/invoice/save", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      apiKey: "<apiKey>",        // تنظیمات حسابفا (بخش API)
      loginToken: "<loginToken>", // یا userId + password
      invoice: {
        number: d.invoiceNumber ?? "",
        date: "2026-09-16 10:30:00",      // میلادی
        dueDate: "2026-09-16 10:30:00",
        contactCode: d.buyerContactCode,  // کد شخص در حسابفا
        contactTitle: d.buyer,
        invoiceType: 1,  // نوع فاکتور از جدول TypesTable (۰=فروش، ۱=خرید، …)
        status: 2,
        invoiceItems: [{
          itemCode: d.itemCode,
          description: d.title ?? "فاکتور چرتکه",
          unit: "عدد",
          quantity: Number(d.quantity ?? 1),
          unitPrice: Number(d.finalAmount),
          discount: 0,
          tax: 0,
        }],
      },
    }),
  });

  const data = await res.json();
  if (!data.Success) console.error(data.ErrorCode, data.ErrorMessage);
  return Response.json({ ok: true });
}

chtk_abc123def456_4f3d…(48 کاراکتر hex)

Authorization: Bearer chtk_abc123def456_<48-char-secret>

curl -G "https://chortkey.ir/api/v1/documents" \
  -H "Authorization: Bearer chtk_abc123def456_<48-char-secret>" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20" \
  --data-urlencode "search=فاکتور شماره";

// Node.js یا Next.js (Route Handler / Server Action)
const TOKEN = "chtk_abc123def456_<48-char-secret>";

const res = await fetch("https://chortkey.ir/api/v1/documents?page=1&limit=20&search=فاکتور", {
  headers: { Authorization: "Bearer " + TOKEN },
});

const result = await res.json();
console.log(result.data.items);

# Python 3 (با نصب: pip install requests)
import requests

TOKEN = "chtk_abc123def456_<48-char-secret>"

res = requests.get(
    "https://chortkey.ir/api/v1/documents",
    headers={"Authorization": "Bearer " + TOKEN},
    params={"page": 1, "limit": 20},
)
data = res.json()
print(data["data"]["items"])

<?php
// PHP یا افزونه WordPress
$TOKEN = "chtk_abc123def456_<48-char-secret>";

$args = array(
  "timeout" => 15,
  "headers" => array("Authorization" => "Bearer " . $TOKEN),
);
$response = wp_remote_get(
  "https://chortkey.ir/api/v1/documents?page=1&limit=20",
  $args
);
$body = json_decode(wp_remote_retrieve_body($response), true);
print_r($body["data"]["items"]);

curl "https://chortkey.ir/api/v1/usage" \
  -H "Authorization: Bearer chtk_abc123def456_<48-char-secret>";

{
  "success": true,
  "data": {
    "totalDocuments": 42,
    "currentPeriodDocuments": 7,
    "byStatus": [
      { "status": "draft", "count": 20 },
      { "status": "approved", "count": 15 },
      { "status": "rejected", "count": 7 }
    ],
    "byThreeWayMatch": [
      { "threeWayMatch": "تأیید شد", "count": 30 },
      { "threeWayMatch": "-", "count": 12 }
    ]
  },
  "meta": {
    "organizationId": "org-xxxx",
    "apiVersion": "v1"
  }
}

# فاکتورهای قطعی فروشِ یک ماه
curl "https://chortkey.ir/api/v1/accounting/invoices?docType=sale&status=final&fromJ=1404/01/01&toJ=1404/01/31&limit=100" \
  -H "Authorization: Bearer chtk_abc123def456_<48-char-secret>"

# همان، ولی با ردیف‌های کالا — برای ساخت فاکتور در هلو/سپیدار/حسابفا لازم است.
# بدون این پارامتر، پاسخ فقط سرِ فاکتور است و items خالی می‌ماند.
curl "https://chortkey.ir/api/v1/accounting/invoices?docType=sale&status=final&limit=100&include=items" \
  -H "Authorization: Bearer chtk_abc123def456_<48-char-secret>"

# تراز آزمایشی (بدون صفحه‌بندی — همهٔ سطرها برمی‌گردد)
curl "https://chortkey.ir/api/v1/accounting/trial-balance" \
  -H "Authorization: Bearer chtk_abc123def456_<48-char-secret>"

# پاسخ هر دو: { "success": true, "data": ..., "meta": { "organizationId": "<uuid>", ... } }

{
  "event": "document.created",
  "data": {
    "id": "uuid",
    "invoiceNumber": "1234",
    "seller": "شرکت الف",
    "buyer": "شرکت ب",
    "issueDateJ": "1404/01/15",
    "finalAmount": 12500000,
    "threeWayMatch": "-"
  },  "sentAt": "2026-09-16T10:30:00.000Z"
}

{
  "event": "invoice.finalized",
  "data": {
    "id": "uuid",
    "docType": "sale",
    "number": "1404-12",
    "issueDateJ": "1404/01/15",
    "dueDateJ": "1404/02/15",
    "contactId": "uuid",
    "currency": "ریال",
    "subtotal": 11363636,
    "discount": 0,
    "vat": 1136364,
    "finalAmount": 12500000,
    "paidAmount": 0,
    "items": [
      {
        "description": "خدمات پشتیبانی",
        "itemId": "uuid",
        "quantity": 1,
        "unitPrice": 11363636,
        "discount": 0,
        "total": 11363636,
        "taxRate": 10,
        "vat": 1136364
      }
    ]
  },
  "sentAt": "2026-09-16T10:30:00.000Z"
}

X-Chortke-Signature: t=1770000000,v1=<64-char-hmac-sha256>

// تأیید امضای وبهوک در Node.js / Next.js
import { createHmac, timingSafeEqual } from "crypto";

export function verifyWebhook(rawBody, signatureHeader, secret) {
  const parts = signatureHeader.split(",");
  const timestamp = String(parts.find((p) => p.startsWith("t="))?.slice(2) ?? "");
  const signature = parts.find((p) => p.startsWith("v1="))?.slice(3) ?? "";

  // ضد بازپخش: بازه زمانی ۵ دقیقه
  const now = Math.floor(Date.now() / 1000);
  if (now - Number(timestamp) > 300) return false;

  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(signature, "hex");
  const b = Buffer.from(expected, "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}

// در Route Handler:
export async function POST(req) {
  const rawBody = await req.text();
  const header = req.headers.get("x-chortke-signature") ?? "";
  const ok = verifyWebhook(rawBody, header, "YOUR_WEBHOOK_SECRET");
  if (!ok) return new Response("invalid signature", { status: 401 });
  const payload = JSON.parse(rawBody);
  // حالا payload.event === "document.created"
  return new Response("ok", { status: 200 });
}

# دریافت‌کننده وبهوک با FastAPI / Flask
import hashlib
import hmac
import time
from fastapi import FastAPI, Request, Header

app = FastAPI()
WEBHOOK_SECRET = "YOUR_WEBHOOK_SECRET"

@app.post("/webhook")
async def webhook(request: Request, x_chortke_signature: str = Header("")):
    raw_body = (await request.body()).decode()
    parts = dict(p.split("=", 1) for p in x_chortke_signature.split(","))
    ts = int(parts.get("t", "0"))
    signature = parts.get("v1", "")

    if int(time.time()) - ts > 300:
        return {"error": "expired"}

    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        raw_body.encode(),
        hashlib.sha256,
    ).hexdigest()

    if not hmac.compare_digest(signature, expected):
        return {"error": "invalid"}, 401

    payload = await request.json()
    # payload["event"] == "document.created"
    return {"ok": True}

<?php
// دریافت‌کننده وبهوک در PHP / WordPress
define("WEBHOOK_SECRET", "YOUR_WEBHOOK_SECRET");

$rawBody = file_get_contents("php://input");
$signatureHeader = $_SERVER["HTTP_X_CHORTKE_SIGNATURE"] ?? "";
$secret = constant("WEBHOOK_SECRET");

$parts = [];
foreach (explode(",", $signatureHeader) as $item) {
    [$k, $v] = explode("=", $item, 2);
    $parts[$k] = $v;
}
if (time() - (int)($parts["t"] ?? 0) > 300) {
    http_response_code(401);
    exit;
}
$expected = hash_hmac("sha256", $rawBody, $secret);
if (!hash_equals($expected, $parts["v1"] ?? "")) {
    http_response_code(401);
    exit;
}
$payload = json_decode($rawBody, true);
// $payload["event"] === "document.created"
http_response_code(200);
echo "ok";