تخطَّ إلى المحتوى

المطوّرون

ابنِ مع إنفوتاكس.

اربط أي نظام مالي بإحدى ثلاث طرق — دون استبدال الأنظمة. اختر ما يناسب كل منصّة، وامزجها عبر المجموعة.

  • مقتطف التضمين

    الصق وسم script واحداً في صفحة الماليات، وطابق الحقول المشتركة، فتتدفّق السجلات إلى إنفوتاكس. دون حاجة إلى مطوّرين.

  • Webhook

    سجّل نقطة نهاية إنفوتاكس في منصّتك واشترك في الأحداث. يُرسَل كل سجل جديد تلقائياً.

  • واجهة REST

    تكامل مباشرةً مع نقاط نهاية موثّقة عبر مفتاح Bearer — أرسِل السجلات واسحب ملخّصات الضرائب والتقارير.

مقتطف التضمين

<script src="https://cdn.invotax.qa/embed.js"
  data-client="acme-trading"
  data-key="pk_test_••••"
  data-system="odoo"></script>

واجهة REST

curl -X POST https://api-invotax.idealsolutions-apps.com/v1/documents \
  -H "Authorization: Bearer sk_live_••••" \
  -H "Content-Type: application/json" \
  -d '{"type":"INVOICE","issuedAt":"2027-01-14T09:00:00+03:00","deviceId":"dev_••••",
       "buyerName":{"en":"Acme","ar":"Acme"},
       "lines":[{"description":"Steel","quantity":"3","unitPrice":"7800.00"}]}'

نقاط النهاية الأساسية

POST/v1/documentsإنشاء فاتورة أو إشعار دائن/مدين أو مستند مبسّط
POST/v1/integrations/ingestسجل وارد من نظام متّصل
GET/v1/tax/summaryضريبة الهيئة المحتسبة لفترة
GET/v1/reports/categoriesإجماليات مصنّفة عبر الأنظمة

المصادقة

تستخدم مكالمات التكامل مفتاح Bearer (‏sk_test_… في البيئة التجريبية، و‏sk_live_… في الإنتاج). تستخدم جلسات البوابة ملف ارتباط HttpOnly. لا تكشف مفتاحاً سرياً في كود العميل — يستخدم مقتطف التضمين مفتاحاً قابلاً للنشر بدلاً من ذلك.

التحقق من توقيعات الـ Webhook

يحمل كل إرسال Webhook ترويسة X-InvoTax-Signature لتتأكّد نقطة النهاية لديك أنه صادر من إنفوتاكس ولم يُعدَّل أثناء النقل. المخطط قائم على HMAC لكنه ليس مطابقاً لِـ Stripe أو معظم المزوّدين — اقرأ طريقة اشتقاق المفتاح أدناه قبل بناء أداة التحقق.

الترويسة
X-InvoTax-Signature: t=<unix-seconds>,v1=<hex HMAC-SHA256>. الحقل t هو الطابع الزمني Unix بالثواني وقت توليد التوقيع؛ والحقل v1 هو توقيع HMAC-SHA256 مُرمَّز بالنظام الست عشري (hex).
المحتوى الموقَّع
يغطّي التوقيع السلسلة النصية بترميز UTF-8 "<t>.<raw body>" — الطابع الزمني من الترويسة، ثم نقطة حرفية، ثم البايتات الخام لجسم الطلب كما وردت تماماً. تحقّق من هذه البايتات الخام مباشرةً؛ لا تُعِد تسلسل JSON بعد تحليله.
مفتاح التوقيع — يختلف عن Stripe
لا تحتفظ إنفوتاكس بسر الـ Webhook الخاص بك كنص صريح أبداً، لذا وخلافاً لِـ Stripe ومعظم المزوّدين، لا تُوقَّع الإرسالات بالسر الخام نفسه. المفتاح هو SHA-256(السر) — بصمة SHA-256 المكوّنة من 32 بايت لسر whsec_... الذي عُرض عليك مرة واحدة عند الإنشاء أو التدوير. طبّق SHA-256 على سرّك قبل استخدامه كمفتاح HMAC، وإلا فشل التحقق بصمت.
الحماية من إعادة التشغيل والتوقيت
ارفض أي إرسال يكون فيه الحقل t أبعد من 5 دقائق عن ساعتك الحالية، وقارن التوقيع المحسوب لديك بـ v1 باستخدام مقارنة بزمن ثابت (constant-time) — لا تستخدم مقارنة نصية عادية أو ===.
صيغة الحمولة
يُرسِل كل تسليم جسم JSON بالشكل { id, event, occurredAt, data }. الحقل event هو أحد: invoice.cleared أو invoice.rejected أو reporting.deadline أو invoice.submission_result. تُرسَل الأحداث الثلاثة الأولى فقط لمستندات بيئة الإنتاج (live)، إلى نقاط نهاية نشِطة مشتركة في ذلك الحدث؛ ويحمل invoice.submission_result نتيجة الهيئة لفاتورة أُرسلت عبر واجهة تكامل الأنظمة الخارجية، في البيئتين التجريبية والإنتاج.

Node.js

const crypto = require('crypto');

// rawBody must be the exact bytes received (e.g. a Buffer from your raw
// body middleware) -- never the re-serialized, parsed JSON.
function verifyInvoTaxSignature(rawBody, signatureHeader, secret) {
  const signingKey = crypto.createHash('sha256').update(secret, 'utf8').digest();

  const parts = Object.fromEntries(signatureHeader.split(',').map((p) => p.split('=')));
  const { t, v1 } = parts;

  const toleranceSeconds = 5 * 60;
  if (Math.abs(Math.floor(Date.now() / 1000) - Number(t)) > toleranceSeconds) {
    throw new Error('signature timestamp outside tolerance');
  }

  const signedContent = Buffer.concat([Buffer.from(`${t}.`, 'utf8'), rawBody]);
  const expected = crypto.createHmac('sha256', signingKey).update(signedContent).digest('hex');

  const expectedBuf = Buffer.from(expected, 'utf8');
  const receivedBuf = Buffer.from(v1, 'utf8');
  const valid =
    expectedBuf.length === receivedBuf.length && crypto.timingSafeEqual(expectedBuf, receivedBuf);

  if (!valid) throw new Error('signature mismatch');
}

Python

import hashlib
import hmac
import time

# raw_body must be the exact bytes received on the wire -- never
# json.dumps(parsed_body).encode(), which can reorder or reformat.
def verify_invotax_signature(raw_body: bytes, signature_header: str, secret: str) -> None:
    signing_key = hashlib.sha256(secret.encode("utf-8")).digest()

    parts = dict(p.split("=", 1) for p in signature_header.split(","))
    t, v1 = parts["t"], parts["v1"]

    tolerance_seconds = 5 * 60
    if abs(int(time.time()) - int(t)) > tolerance_seconds:
        raise ValueError("signature timestamp outside tolerance")

    signed_content = f"{t}.".encode("utf-8") + raw_body
    expected = hmac.new(signing_key, signed_content, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(expected, v1):
        raise ValueError("signature mismatch")

الرابط الأساسي: https://api-invotax.idealsolutions-apps.com/v1 (التجريبي: sandbox-api-invotax…). الأرقام والمفاتيح المعروضة توضيحية.