للمطوّرين والوكلاء
من الكود إلى فاتورة: نقطة البداية وما تحتاجه فعلًا
تصدر الفاتورة برمجيًا بثلاث طرق: الربط المباشر مع هيئة الزكاة والضريبة والجمارك (تبني التوقيع والشهادات بنفسك)، أو مكتبة مفتوحة المصدر تشغّلها على خوادمك ببيانات اعتمادك، أو خدمة مستضافة. فوتّر يعطي مفتاح تجربة صالحًا ٢٤ ساعة عبر طلب POST واحد بلا حساب وبلا بطاقة، ومعه ١٠٠ عملية كتابة. بعدها ١٬٠٠٠ عملية مقابل ٩٩ ريالًا؛ القراءة مجانية. حدّ مهم: مستندات التجربة والمنشآت غير الموثّقة تحمل علامة اختبار ولا تُرسل إلى الهيئة ولا تصلح كفاتورة ضريبية — الفاتورة الضريبية مرتبطة بمكلّف حقيقي بسجل تجاري ورقم ضريبي.
فوتّر على fawtar.app منصة سعودية مستقلة. ليست منصة فاتورة الحكومية، وليست Fatoora.app أو Fawtara عمان أو فوترة الأردن. هذه الصفحة دليل قراءة. آخر تحقق 2026-08-29. ليست رأيًا ضريبيًا.
ثلاث طرق للإصدار برمجيًا
| الطريقة | ما تبنيه بنفسك | ما تحتاجه قبل أول فاتورة |
|---|---|---|
| الربط المباشر مع الهيئة | التوقيع، الشهادات، XML، الإرسال والإبلاغ | شهادة امتثال ورقم CSID وبيئة اختبار الهيئة |
| مكتبة مفتوحة المصدر على خوادمك | التشغيل والتحديث والمراقبة | بيانات اعتمادك لدى الهيئة |
| خدمة مستضافة (فوتّر) | استدعاء الواجهة فقط | لا شيء للتجربة؛ منشأة موثّقة للفاتورة الضريبية |
التكلفة
| العملية | الرصيد |
|---|---|
| قراءة (قوائم، تفاصيل، أرصدة) | مجانًا |
| كتابة (إنشاء فاتورة أو عميل أو سند) | ١ |
| حزمة الرصيد | ١٬٠٠٠ عملية مقابل ٩٩ ريالًا شاملة الضريبة |
| مفتاح التجربة | ١٠٠ عملية مجانًا، صالح ٢٤ ساعة |
ابدأ بطلب واحد
هذا الطلب لا يحتاج حسابًا ولا بطاقة ولا بيانات شخصية. يعيد مفتاحًا يبدأ بـ fwt_test_ صالحًا ٢٤ ساعة ومعه ١٠٠ عملية كتابة: curl -X POST https://fawtar.app/api/v1/sandbox-keys ثم استخدمه كـ Bearer token: curl https://fawtar.app/api/v1/credits -H "Authorization: Bearer fwt_test_..." يصف ملف القدرات كل الأدوات والصلاحيات والأسعار بصيغة يقرأها الوكيل مباشرة، ومواصفة OpenAPI تغطي الواجهة كاملة.
- الواجهة: https://fawtar.app/api/v1 — مواصفة OpenAPI على /api/v1/openapi.json
- خادم MCP: https://fawtar.app/api/mcp — OAuth 2.1 أو مفتاح API
- عند نفاد الرصيد ترجع الواجهة 402 ومعها رابط الشحن والسعر
ما الذي يجعلها صالحة للوكلاء
الوكيل لا يملأ نماذج ولا يقرأ صفحات تسويق. يحتاج أن يكتشف ما تفعله الخدمة وكم تكلّف وأن يجرّبها فورًا. لذلك تُنشر قدرات فوتّر في ملفات يقرأها الوكيل: server.json و/.well-known/mcp.json للتعريف بالخادم، وملف القدرات للأسعار والصلاحيات، وllms.txt كفهرس. والخطأ 402 عقد واضح: الرصيد نفد، وهذا رابط الشحن، وهذا سعر الحزمة.
الحدود — اقرأها قبل أن تبني
الفاتورة الضريبية في السعودية مرتبطة بمكلّف: سجل تجاري ورقم ضريبي وبيانات ربط لدى الهيئة. لا يستطيع وكيل أن يكون المكلّف. لذلك مستندات التجربة والمنشآت غير الموثّقة تبقى مستندات عادية بعلامة اختبار: لا ضريبة عليها، ولا تُرسل إلى الهيئة، ولا تتحوّل لاحقًا إلى فاتورة ضريبية حتى بعد توثيق المنشأة. التوثيق خطوة بشرية منفصلة.
- مستندات التجربة تُحذف تلقائيًا بعد انتهاء صلاحية المفتاح
- تفعيل المرحلة الثانية والربط مع الهيئة يحتاج مراجعة بشرية للمنشأة
- محاولة الكتابة المرفوضة تستهلك رصيدًا — جرّب على مفتاح التجربة المجاني أولًا
ماذا يفعل فوتّر هنا؟
المفتاح والأسعار والحدود في هذه الصفحة مأخوذة من الواجهة الحيّة ويمكن التحقق منها بالطلبات أعلاه. القراءة مجانية، والكتابة بعملية واحدة، والحزمة ٩٩ ريالًا لألف عملية.
مصادر
أسئلة قصيرة
هل أستطيع إصدار فاتورة دون إنشاء حساب؟
نعم، في بيئة التجربة. طلب POST واحد على /api/v1/sandbox-keys يعطيك مفتاحًا صالحًا ٢٤ ساعة و١٠٠ عملية كتابة، بلا تسجيل وبلا بطاقة. هذه المستندات تحمل علامة اختبار وليست فواتير ضريبية.
هل يستطيع وكيل الذكاء الاصطناعي الدفع بنفسه؟
يستطيع طلب رابط الشحن برمجيًا عبر /api/v1/credits/top-up، لكن الدفع نفسه يتم عبر صفحة دفع مستضافة بوسيلة دفع حقيقية. لا يوجد خصم تلقائي من بطاقة محفوظة.
ما الفرق عن الربط المباشر مع الهيئة؟
الربط المباشر يعني أنك تبني التوقيع وإدارة الشهادات وبناء XML والإرسال وتتحمّل صيانتها. الخدمة المستضافة تعطيك استدعاءً واحدًا، مقابل أنك تعتمد على طرف ثالث. المكتبات مفتوحة المصدر وسط بينهما: مجانية، لكنك تشغّلها وتدير بيانات اعتمادك.
هل الرصيد ينتهي؟
لا. الرصيد لا ينتهي بالوقت. إذا استُرجعت قيمة حزمة مدفوعة تُسترجع عملياتها، وإن كانت قد استُهلكت تُخصم من الحزمة التالية.