تكامل API مخصص

المصادقة والتوقيع والصلاحيات

أرسل JSON إلى POST /api/integrations/commerce/v1/events/ مع Authorization: Bearer <your scoped API key>. يقبل schemaVersion 1 للمبالغ العشرية القديمة و2 للوحدات الصغرى الصحيحة؛ استخدم 2 للتكاملات الجديدة. افصل مفاتيح الاتصال والبيئة ولا تضع بيانات اعتماد في URL.

للإرسال الموقّع استخدم POST /api/integrations/commerce/webhooks/{connectionId}/ مع x-meshdex-timestamp بالثواني Unix وx-meshdex-signature بقيمة v1= متبوعة بـ HMAC-SHA256 سداسي لوقت الطلب ونقطة ونص JSON الخام باستخدام سر الاتصال. يجب ألا يبعد الطلب أكثر من خمس دقائق عن الوقت الحالي. وقّع البايتات المرسلة نفسها ولا تعِد التنسيق.

يلزم اتصال نشط وصلاحية مطابقة: commerce.events:write للكتابة وcommerce.events:read للحالة وcommerce.orders:read للطلبات وcommerce.catalog:read للكتالوج وcommerce.availability:read للإتاحة وcommerce.reconciliation:read للمطابقة. استخدم الحد الأدنى. ربط الكتالوج وتطبيق الاستيراد يحتاجان إدارة مساحة مخولة.

تعني 202 وضع الحدث في الطابور، لا ترحيله. احفظ معرفه. تعيد GET /api/integrations/commerce/v1/events/{eventId}/ الحالة والخطأ والنتيجة، وتقبل معرف الحدث الخارجي أيضًا. تعيد GET /api/integrations/commerce/v1/orders/?orderId=your-source-invoice-id روابط المحاسبة والمخزون. تعيد GET /api/integrations/commerce/v1/reconciliation/ المطابقة بصفحات؛ مرر nextCursor عبر after.

إعداد خدمات SaaS تلقائيًا

تعرض GET /api/integrations/commerce/v1/connector-setup/ عملة Ledger والضرائب المعتمدة باستخدام commerce.catalog:read، وكذلك نقص توجيه الحسابات والصلاحيات المطلوبة.

باستخدام commerce.catalog:write أرسل تعريفات الخدمات الموجودة بـ POST للعنوان نفسه مع externalProductId وname. ينشئ الربط خدمات Ledger بحساب الإيراد المعتمد، ويحافظ على المنتجات والربط الحالي ويطلب مراجعة التعارض. تبقى الأسعار والعملات معتمدة من المصدر لكل فاتورة.

يمكن لمفتاح صالح محدود إعداد الكتالوج لاتصال SaaS مسودة أو موقوف قبل التفعيل. إرسال الأحداث المالية يتطلب اتصالًا نشطًا. الاختبار لا يرحّل محاسبة فواتير أو دفعات.

للتقييم بعملة أجنبية أضف currency وdate مثل ?currency=USD&date=2026-01-01. تعيد الواجهة دليل سعر مؤرخ لوحدة معاملة إلى عملة Ledger الفعلية. يجب اعتماد سياسة السعر المرجعي صراحة وتثبيت الدليل قبل الإرسال الأول وإعادة استخدامه دون تغيير. تحويل تسوية البوابة مسار منفصل.

{
  "services": [
    {
      "externalProductId": "example-starter-monthly",
      "name": "Example Starter monthly"
    },
    {
      "externalProductId": "example-starter-yearly",
      "name": "Example Starter yearly"
    }
  ]
}

مبالغ الإصدار 2 والضرائب والصرف

أرسل externalEventId وeventType وschemaVersion: 2 وoccurredAt وsourceRevision كعدد صحيح متزايد ممثل بنص. المعرفات ثابتة للعملاء والفواتير والتحصيل والدائن والاسترداد والتسوية والإرجاع ضمن الاتصال. لا تغير الهوية أو البيانات عند الإعادة، ولا تستخدم حدثًا جديدًا لتغيير دفعة أو استرداد أو تسوية قائمة.

استخدم وحدات صغرى صحيحة: INR/USD/EUR/GBP/AUD/CAD/NZD/SGD/HKD/AED/SAR/CHF تستخدم 100 لكل وحدة؛ JPY واحدة. تُرفض العملات الأخرى والكميات الكسرية للمحاسبة الآلية. الكمية عدد صحيح موجب، وحد الفاتورة 200 بند. كل مبلغ وإجمالي لا يتجاوز 2147483647. الشحن بند مربوط صريح والخصم لكل بند.

يحدد كل بند unitPriceMinor وquantity وdiscountMinor وtax مع treatment من EXCLUSIVE أو INCLUSIVE أو EXEMPT أو ZERO_RATED وamountMinor وcomponents. لكل مكون name وrate وamountMinor. التقريب لأقرب وحدة صغرى والنصف للأعلى مع مطابقة دقيقة. totalMinor يساوي مجموع البنود بعد الخصم والضريبة؛ السعر الشامل يتضمنها. الضريبة الموجبة تتطلب taxRateId معتمدًا. يسمح ببند مخصوم بالكامل إذا بقي إجمالي الفاتورة موجبًا.

تتطلب GST الحقول tax.countryCode: IN وHSN/SAC وplaceOfSupply، وإما IGST أو CGST وSGST معًا دون خلط. يجب أن تكون المعدلات وحسابات المستحق الضريبي نشطة ومطابقة للمساحة. لا تُستنتج الضريبة من العملة. يحدد الدائن والاسترداد taxMinor وtaxPayableAccountId لعكسها.

تتضمن أحداث العملة الأجنبية baseCurrency وexchangeRate موجبًا وexchangeRateSource وexchangeRateDate. يحوّل السعر وحدة معاملة أو تسوية إلى عملة Ledger الأساسية. يستخدم النقد سعره الفعلي وتحتفظ عكسات الذمم والدائن بسعر الفاتورة. تُوزع القيمة الدفترية المتبقية للمبالغ الجزئية دون بقايا عند الإغلاق. تتطلب الفروق حسابات ربح وخسارة صرف، ولا تُستبدل العملة أو السعر ضمنيًا.

يجوز للمصدر الذي يحسب GST الهندية مجمعة تسجيل فرق وحدة صغرى واحدة بين CGST وSGST باستخدام tax.roundingMethod: AGGREGATE وroundingAdjustmentMinor: 1 أو -1 على مكون واحد فقط. يلزم تساوي المعدلين ومطابقة الضريبة الأصلية وكل تفاصيل GST. تُرفض فروق أكبر أو غير مرتبطة؛ تبقى ضريبة الفاتورة وإجماليها دون تغيير.

أمثلة مادية ورقمية وSaaS

الأمثلة خيالية ومعفاة ضريبيًا للتوضيح. استبدل المعرفات والأسعار بقيم المصدر واعتمد ربط product-1 وservice-1 وplan-pro أولًا. اختر مرجعية الفاتورة Source. يُستخدم المخزون فقط مع ربط Supply stock المعتمد؛ الرقمي وSaaS خدمات مع Ledger فقط.

{
  "externalEventId": "example-physical",
  "eventType": "invoice.created",
  "schemaVersion": 2,
  "sourceRevision": "1",
  "occurredAt": "2026-10-14T10:00:00Z",
  "data": {
    "invoiceId": "invoice-physical",
    "invoiceNumber": "SOURCE-PHYSICAL",
    "invoiceAuthority": "SOURCE",
    "documentReference": "https://billing.example.com/invoices/invoice-physical",
    "currency": "INR",
    "customer": {
      "id": "customer-1",
      "name": "Example Customer",
      "email": "[email protected]",
      "billingAddress": {
        "countryCode": "IN",
        "regionCode": "KA"
      }
    },
    "issueDate": "2026-10-14",
    "dueDate": "2026-10-14",
    "lines": [
      {
        "productId": "product-1",
        "description": "Example physical product",
        "quantity": 2,
        "unitPriceMinor": 5000,
        "discountMinor": 0,
        "tax": {
          "treatment": "EXEMPT",
          "amountMinor": 0,
          "components": []
        }
      }
    ],
    "totalMinor": 10000
  }
}

{
  "externalEventId": "example-digital",
  "eventType": "invoice.created",
  "schemaVersion": 2,
  "sourceRevision": "1",
  "occurredAt": "2026-10-14T10:00:00Z",
  "data": {
    "invoiceId": "invoice-digital",
    "invoiceNumber": "SOURCE-DIGITAL",
    "invoiceAuthority": "SOURCE",
    "documentReference": "https://billing.example.com/invoices/invoice-digital",
    "currency": "INR",
    "customer": {
      "id": "customer-1",
      "name": "Example Customer",
      "email": "[email protected]",
      "billingAddress": {
        "countryCode": "IN",
        "regionCode": "KA"
      }
    },
    "issueDate": "2026-10-14",
    "dueDate": "2026-10-14",
    "lines": [
      {
        "productId": "service-1",
        "description": "Digital service",
        "quantity": 1,
        "unitPriceMinor": 10000,
        "discountMinor": 0,
        "tax": {
          "treatment": "EXEMPT",
          "amountMinor": 0,
          "components": []
        }
      }
    ],
    "totalMinor": 10000
  }
}

{
  "externalEventId": "example-saas",
  "eventType": "subscription.renewed",
  "schemaVersion": 2,
  "sourceRevision": "1",
  "occurredAt": "2026-10-14T10:00:00Z",
  "data": {
    "invoiceId": "invoice-saas",
    "invoiceNumber": "SOURCE-SAAS",
    "invoiceAuthority": "SOURCE",
    "documentReference": "https://billing.example.com/invoices/invoice-saas",
    "currency": "INR",
    "customer": {
      "id": "customer-1",
      "name": "Example Customer",
      "email": "[email protected]",
      "billingAddress": {
        "countryCode": "IN",
        "regionCode": "KA"
      }
    },
    "issueDate": "2026-10-14",
    "dueDate": "2026-10-14",
    "lines": [
      {
        "productId": "plan-pro",
        "description": "Monthly SaaS renewal",
        "quantity": 1,
        "unitPriceMinor": 10000,
        "discountMinor": 0,
        "tax": {
          "treatment": "EXEMPT",
          "amountMinor": 0,
          "components": []
        }
      }
    ],
    "totalMinor": 10000,
    "subscriptionId": "subscription-1",
    "billingPeriod": {
      "cycle": "monthly",
      "start": "2026-10-14",
      "end": "2026-11-14"
    }
  }
}

{
  "externalEventId": "example-yearly",
  "eventType": "subscription.renewed",
  "schemaVersion": 2,
  "sourceRevision": "1",
  "occurredAt": "2026-10-14T10:00:00Z",
  "data": {
    "invoiceId": "invoice-yearly",
    "invoiceNumber": "SOURCE-YEARLY",
    "invoiceAuthority": "SOURCE",
    "documentReference": "https://billing.example.com/invoices/invoice-yearly",
    "currency": "INR",
    "customer": {
      "id": "customer-1",
      "name": "Example Customer",
      "email": "[email protected]",
      "billingAddress": {
        "countryCode": "IN",
        "regionCode": "KA"
      }
    },
    "issueDate": "2026-10-14",
    "dueDate": "2026-10-14",
    "lines": [
      {
        "productId": "plan-pro",
        "description": "Yearly SaaS renewal",
        "quantity": 1,
        "unitPriceMinor": 10000,
        "discountMinor": 0,
        "tax": {
          "treatment": "EXEMPT",
          "amountMinor": 0,
          "components": []
        }
      }
    ],
    "totalMinor": 10000,
    "subscriptionId": "subscription-1",
    "billingPeriod": {
      "cycle": "yearly",
      "start": "2026-10-14",
      "end": "2027-10-14"
    }
  }
}

دورة الفواتير والاشتراكات والاسترداد

• ينشئ customer.upserted عميلًا ضمن الاتصال أو يزامنه بالمراجعات: اسم الفوترة والاتصال والعنوان والهوية الضريبية. لا تُدمج العملاء اليدوية أو غير المرتبطة تلقائيًا.
• تنشئ invoice.created وorder.created وsubscription.renewed فواتير. تطبق invoice.updated وorder.updated مراجعات المسودات المدعومة. تُهمل المراجعات القديمة وتُراجع المتعارضة. تُصحح الفواتير المرحّلة بأحداث دائن صريحة أو تعديلات Ledger المعتمدة دون استبدالها.
• استخدم معرف فاتورة مصدر مستقلًا لكل فترة شهرية أو سنوية. أرسل فواتير التناسب أو تغيير الخطة بالمبالغ الفعلية والفترة المناسبة؛ لا يحسب MeshDex جداول الاشتراك أو الاستحقاقات. تحدّث أحداث إنشاء الاشتراك وتغييره وإلغائه المراجع مع accountingEffect: NONE. إلغاء التجديد المستقبلي لا يرد أو يلغي فترة مدفوعة.
• تلغي invoice.cancelled وorder.cancelled المسودات غير المدفوعة وتحرر الحجوزات غير المنفذة. السجلات المرحّلة أو المدفوعة أو المنفذة تتطلب مسارات دائن أو استرداد أو إرجاع صريحة.
• يتضمن payment.captured الحقول invoiceId وpaymentId وcurrency وamountMinor وpaidAt الاختياري، ويسجل نقدًا محصلًا مؤكدًا في حساب البنك أو التسوية. التفويض والدفعات الفاشلة مراجع فقط.
• يتضمن credit.issued الحقول invoiceId وcreditId وcurrency وamountMinor وtaxMinor وreason وcreditedAt الاختياري. يخفض الإيراد أو الذمم ولا يعيد النقد.
• يتضمن refund.completed الحقول invoiceId وrefundId وcurrency وamountMinor وtaxMinor وreason وcompletedAt ويسجل استرداد البوابة المؤكد والدائن المقابل. أدرج creditId لإعادة استخدام دائن مطابق؛ لا يستهلكه سوى استرداد نقدي مطابق واحد. وإلا يُنشأ دائن منفصل. لا تكرر المعرفات الأثر. أحداث إنشاء الاسترداد أو فشله مراجع فقط.
• تُدعم استردادات جزئية متعددة ضمن النقد المسجل وحدود الدائن والضريبة المتبقية. تستخدم المرتجعات return.received مع orderId وreturnId وlines وqualityApproved؛ الاسترداد المالي لا يعيد المخزون. تنتظر المرتجعات الفحص افتراضيًا، ولا يُعتمد فحص المصدر إلا بسياسة موافقة مصدر موثوق يختارها المسؤول.

الحالات والأخطاء والاسترداد الآمن

تعني RECEIVED وPROCESSING عمل الطابور وWAITING_DEPENDENCY غياب سجل سابق. تعني COMPLETED اكتمال المعالجة؛ افحص result.accountingEffect لأن الاختبارات والمراجع قد تنتهي بـ NONE. تتطلب REVIEW_REQUIRED تصحيح المشغّل وRETRYABLE_FAILED عطلًا مؤقتًا وDEAD_LETTER استردادًا.

400 للبيانات أو الضرائب أو الأحداث غير الصالحة، و401 لبيانات اعتماد غير صالحة أو منتهية أو ملغاة، و403 للصلاحية المفقودة، و409 لهوية مكررة بمحتوى مختلف، و402 لسعة الخطة، و429 لمعدل الطلبات. أعد الأخطاء المؤقتة بتأخير متزايد مع الهوية والنص نفسيهما؛ لا تكرر أخطاء التحقق عشوائيًا.

سحب الوصول للاتصال أو الوحدة بعد القبول يوقف المعالجة. التوقيع والإشعارات لا تعني حركة نقد البوابة؛ تؤكدها أحداث تحصيل أو استرداد المصدر فقط. تعرض المطابقة صفحة الفواتير الحالية وآخر 25 نتيجة تسوية أو نزاع؛ استخدم مرشحات قيود Ledger للأقدم.

يتطلب الإعداد المُدار تحقق المسؤول قبل الاستخدام الحي. الاعتراف بإيراد مؤجل اختياري معتمد من محاسب ولا يجدول تجديدًا أو ينفذ استرداد بوابة. تطبيق المصدر مسؤول عن الفوترة والاستحقاقات والنقد الفعلي.

أدلة ذات صلة

• تكاملات التجارة
• الإعداد المشترك للتجارة
• تكامل Shopify
• تكامل WordPress وWooCommerce
• محاسبة التجارة والمخزون