كيف أبدأ مع API فواتير Invovate؟

أنشئ حسابًا مجانيًا على invovate.com، تحقق من بريدك الإلكتروني، وأنشئ مفتاح API من لوحة التحكم. يمكنك بعد ذلك إرسال طلبات إلى POST /api/generate-invoice باستخدام Bearer token.

كم عدد الفواتير التي يمكنني إنشاؤها مجانًا؟

تتيح الخطة المجانية 40 طلبًا في الساعة و400 طلبًا في الأسبوع. للحصول على حجم أكبر، تتوفر خطط Starter وPro.

هل تدعم الـ API ضريبة القيمة المضافة في الإمارات والسعودية؟

نعم. اضبط tax_rate على 5 (معدل ضريبة القيمة المضافة الإماراتي والسعودي) لكل سطر، أو استخدم global_tax لتطبيق نفس المعدل على جميع السطور.

هل يمكنني إنشاء فواتير بالدرهم الإماراتي أو الريال السعودي؟

نعم. اضبط currency على AED للدرهم الإماراتي أو SAR للريال السعودي، و language على ar. تدعم الـ API أكثر من 20 عملة.

توثيق API مولّد الفواتير — واجهة برمجية مجانية للفواتير

نظرة عامة

تتيح واجهة برمجة فواتير Invovate للمطورين إنشاء فواتير احترافية من خلال طلب HTTP POST واحد. يمكنك الاختيار بين استجابة JSON منظمة تحتوي على جميع الحسابات أو تنزيل مباشر لملف PDF. تدعم الـ API 11 لغة وأكثر من 20 عملة و5 قوالب تصميم — مثالية للمستقلين والشركات في الإمارات والسعودية والدول العربية.

ابدأ مجانًا

40 طلبًا/ساعة، بدون بطاقة ائتمانية

JSON أو PDF

اختر تنسيق المخرجات

حساب ضريبة القيمة المضافة

لكل سطر أو بشكل شامل (5%)

متعدد اللغات

ar, en, fr, de وأكثر

الرابط الأساسي:
https://invovate.com/api

البدء السريع

أنشئ فاتورتك الأولى في ثلاث خطوات:

الخطوة 1 — إنشاء حساب
سجّل مجانًا على invovate.com وتحقق من بريدك الإلكتروني.

الخطوة 2 — الحصول على مفتاح الـ API
انتقل إلى لوحة التحكم واضغط على "إنشاء مفتاح API". يبدأ مفتاحك بـ inv_.

الخطوة 3 — أول طلب

curl -X POST https://invovate.com/api/generate-invoice \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer inv_yourApiKeyHere" \
  -d '{
    "from": {"name": "شركتي المحدودة"},
    "to": {"name": "شركة العميل"},
    "items": [{"description": "تطوير مواقع", "quantity": 1, "unit_price": 5000, "tax_rate": 5}],
    "invoice": {"currency": "AED", "language": "ar"}
  }'

المصادقة

تدعم الـ API ثلاث طرق للمصادقة:

1. مفتاح الـ API (موصى به للاستخدام من جهة الخادم)

Authorization: Bearer inv_yourApiKeyHere

2. كوكي الجلسة (لتطبيقات الويب)

عند تسجيل الدخول عبر المتصفح، يُرسَل كوكي inv_session تلقائيًا.

3. مجهول (بدون مصادقة)

يمكن إجراء الطلبات بدون مصادقة لكنها مقتصرة على مخرجات JSON ومحدودة حسب عنوان IP. مناسب للاختبار.

الأمان: لا تضمّن مفتاح الـ API في الكود من جهة العميل ولا تخزّنه في مستودع Git. استخدم متغيرات البيئة على خادمك.

الحدود والخطط

الخطة	السعر	في الساعة	في الأسبوع
مجاني	0 AED	40	400
Starter	33 AED/شهر	200	4,000
Pro	107 AED/شهر	1,000	40,000
Enterprise	للتفاوض	غير محدود	غير محدود

تُعاد الحدود في رؤوس الاستجابة:

X-RateLimit-Limit-Hourly: 40
X-RateLimit-Remaining-Hourly: 39
X-RateLimit-Reset-Hourly: 1712123456
X-RateLimit-Limit-Weekly: 400
X-RateLimit-Remaining-Weekly: 399
X-RateLimit-Reset-Weekly: 1712345678

إنشاء فاتورة

POST

/api/generate-invoice

ينشئ فاتورة ويُعيد إما JSON يحتوي على جميع الحسابات أو ملف PDF ثنائي.

تنسيق الطلب

المُرسِل (`from`)

الحقل	النوع	مطلوب	الوصف
from.name	string	نعم	اسم شركتك
from.address	string	لا	عنوان شركتك
from.email	string	لا	بريدك الإلكتروني
from.tax_id	string	لا	الرقم الضريبي (مثال: 100345678900003)

المُستلِم (`to`)

الحقل	النوع	مطلوب	الوصف
to.name	string	نعم	اسم العميل أو الشركة
to.address	string	لا	عنوان العميل
to.email	string	لا	بريد العميل الإلكتروني

بيانات الفاتورة (`invoice`)

الحقل	النوع	الافتراضي	الوصف
invoice.number	string	تلقائي	رقم الفاتورة
invoice.date	string	اليوم	تاريخ الإصدار (YYYY-MM-DD)
invoice.due_date	string	—	تاريخ الاستحقاق (YYYY-MM-DD)
invoice.currency	string	USD	رمز العملة (مثال: AED)
invoice.language	string	en	رمز اللغة (مثال: ar)
invoice.terms	string	—	شروط الدفع
invoice.po_number	string	—	رقم أمر الشراء

بنود الفاتورة (`items`)

الحقل	النوع	مطلوب	الوصف
description	string	نعم	وصف المنتج أو الخدمة
quantity	number	نعم	الكمية
unit_price	number	نعم	سعر الوحدة (قبل الضريبة)
discount	number	لا	الخصم (نسبة مئوية أو مبلغ)
discount_type	string	percent	"percent" أو "amount"
tax_rate	number	لا	نسبة الضريبة لكل سطر (مثال: 5)

حقول أخرى

الحقل	النوع	الوصف
global_tax	number	نسبة ضريبة شاملة (تُطبَّق إذا لم تُحدَّد نسبة لكل سطر)
global_discount	number	خصم على الإجمالي
amount_paid	number	المبلغ المدفوع مسبقًا (للدفع الجزئي)
notes	string	ملاحظات أسفل الفاتورة
template	string	اسم القالب: classic, modern, bold, minimal, navy
output	string	"json" (افتراضي) أو "pdf"

تنسيق الاستجابة

استجابة JSON (`output: "json"`)

{
  "success": true,
  "invoice": {
    "number": "INV-2026-042",
    "date": "2026-04-03",
    "due_date": "2026-05-03",
    "currency": "AED",
    "language": "ar",
    "template": "classic",
    "from": { "name": "شركتي المحدودة", "tax_id": "100345678900003" },
    "to": { "name": "شركة العميل" },
    "items": [
      {
        "description": "تطوير مواقع الويب",
        "quantity": 1,
        "unit_price": 10000,
        "discount": 0,
        "tax_rate": 5,
        "tax_amount": 500.00,
        "line_total": 10500.00
      }
    ],
    "subtotal": 10000.00,
    "total_tax": 500.00,
    "grand_total": 10500.00,
    "amount_paid": 0,
    "balance_due": 10500.00,
    "notes": "شكرًا لثقتكم بنا."
  },
  "meta": {
    "processing_ms": 11,
    "credits_remaining": { "hourly": 39, "weekly": 399 }
  }
}

استجابة PDF (`output: "pdf"`)

تُعيد ملف PDF ثنائيًا مع الرؤوس التالية:

Content-Type: application/pdf
Content-Disposition: attachment; filename="invoice.pdf"

رموز الأخطاء

{
  "success": false,
  "error": { "message": "مطلوب عنصر واحد على الأقل" }
}

حالة HTTP	المعنى
400	خطأ في التحقق — راجع تنسيق طلبك
401	المصادقة مطلوبة أو مفتاح الـ API غير صالح
403	البريد الإلكتروني غير مُتحقق منه
429	تجاوز حد المعدل
500	خطأ داخلي في الخادم

نقاط نهاية المصادقة

الطريقة	المسار	الوصف
POST	/api/auth/register	إنشاء حساب بالبريد الإلكتروني وكلمة المرور
POST	/api/auth/login	تسجيل الدخول، يُعيد كوكي الجلسة
POST	/api/auth/logout	تسجيل الخروج
GET	/api/auth/me	الحصول على بيانات المستخدم الحالي ومفتاح الـ API
POST	/api/auth/generate-api-key	إنشاء مفتاح API جديد (يتطلب تأكيد البريد الإلكتروني)

أمثلة الكود

cURL — فاتورة PDF بضريبة القيمة المضافة الإماراتية

curl -X POST https://invovate.com/api/generate-invoice \ -H "Content-Type: application/json" \ -H "Authorization: Bearer inv_yourApiKeyHere" \ -d '{ "from": { "name": "شركة الحلول الرقمية ذ.م.م", "address": "برج خليفة، دبي، الإمارات العربية المتحدة", "tax_id": "100345678900003", "email": "[email protected]" }, "to": { "name": "شركة العميل المحدودة", "address": "مدينة الشارقة للإعلام، الشارقة", "email": "[email protected]" }, "invoice": { "number": "INV-2026-042", "date": "2026-04-03", "due_date": "2026-05-03", "currency": "AED", "language": "ar", "terms": "30 يومًا صافيًا" }, "items": [ {"description": "تصميم وتطوير الموقع", "quantity": 1, "unit_price": 15000, "tax_rate": 5}, {"description": "استشارات تحسين محركات البحث", "quantity": 10, "unit_price": 800, "tax_rate": 5} ], "notes": "شكرًا لثقتكم بنا.", "template": "modern", "output": "pdf" }' --output invoice.pdf

JavaScript (Node.js)

// إنشاء فاتورة باستخدام Invovate API const response = await fetch('https://invovate.com/api/generate-invoice', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer inv_yourApiKeyHere' }, body: JSON.stringify({ from: { name: 'شركتي المحدودة', tax_id: '100345678900003' }, to: { name: 'شركة العميل', email: '[email protected]' }, invoice: { number: 'INV-001', currency: 'AED', language: 'ar', due_date: '2026-05-03' }, items: [{ description: 'استشارات', quantity: 5, unit_price: 2000, tax_rate: 5 }], output: 'json' }) }); const data = await response.json(); if (data.success) { console.log('الإجمالي شامل الضريبة:', data.invoice.grand_total, 'AED'); console.log('الطلبات المتبقية (الساعة):', data.meta.credits_remaining.hourly); }

Python

import requests

API_KEY = "inv_yourApiKeyHere"
URL = "https://invovate.com/api/generate-invoice"

# إنشاء فاتورة لعميل إماراتي
invoice = {
    "from": { "name": "مستقل في دبي", "tax_id": "100345678900003" },
    "to": { "name": "شركة العميل ذ.م.م", "address": "مركز دبي المالي العالمي" },
    "invoice": {
        "number": "INV-2026-001",
        "currency": "AED",
        "language": "ar",
        "terms": "30 يومًا صافيًا"
    },
    "items": [
        {"description": "تصميم الهوية البصرية", "quantity": 1, "unit_price": 8000, "tax_rate": 5},
        {"description": "بطاقات العمل", "quantity": 3, "unit_price": 500, "tax_rate": 5}
    ],
    "output": "pdf"
}

response = requests.post(URL, json=invoice, headers={"Authorization": f"Bearer {API_KEY}"})
if response.status_code == 200:
    with open("invoice.pdf", "wb") as f:
        f.write(response.content)
    print("تم حفظ الفاتورة: invoice.pdf")
else:
    print(f"خطأ: {response.json()['error']['message']}")

اللغات المدعومة

الرمز	اللغة	اتجاه الكتابة
`ar`	العربية	RTL
`en`	الإنجليزية	LTR
`fr`	الفرنسية	LTR
`de`	الألمانية	LTR
`nl`	الهولندية	LTR
`es`	الإسبانية	LTR
`it`	الإيطالية	LTR
`pt`	البرتغالية	LTR
`ru`	الروسية	LTR
`hi`	الهندية	LTR
`ja`	اليابانية	LTR

قوالب الـ PDF

الاسم	الأسلوب
`classic`	لون أزرق، صفوف رمادية متناوبة (الافتراضي)
`modern`	تيل/سماوي، تصميم عصري نظيف
`bold`	رأس داكن، تباين عالٍ
`minimal`	رمادي فاتح، بدون حدود
`navy`	رأس كحلي مع خط ذهبي

العملات المدعومة

AED, SAR, USD, EUR, GBP, JPY, CAD, AUD, CHF, CNY, INR, SGD, NZD, KRW, BRL, MXN, ZAR, SEK, NOK, DKK