ForHosting KIT · المستندات وملفات PDF

أنشئ فاتورة مع حساب الإجماليات والضريبة

حوّل بيانات الفوترة الأساسية إلى مستند فاتورة متسق من دون تكرار قواعد الحساب في كل تطبيق. أدخل البائع والمشتري والبنود والكميات وأسعار الوحدات ومعدل الضريبة كنسبة مئوية. يحسب المولد إجمالي كل بند والمجموع الفرعي والضريبة والإجمالي النهائي، ثم يعيد البيانات المدخلة والمحسوبة في كائن منظم يمكنكم حفظه أو مراجعته أو عرضه أو تمريره إلى سير عمل آخر.

● Betaمجاني · داخل متصفحك

شغّل الأداة مجانًا اطّلع على الـAPI

استخدمها من الويبAPIالبريدTelegramالتطبيق قريبًا

جهّزوا بيانات الفاتورة كاملة

ابدؤوا بتحديد طرفي المعاملة. يمكن أن يتضمن حقلا البائع والمشتري الاسمين مع العنوان أو بيانات التسجيل أو معلومات الاتصال التي ينبغي للعملية اللاحقة الاحتفاظ بها. أضيفوا بعد ذلك بندا واحدا على الأقل. يحتاج كل سطر إلى وصف واضح وكمية رقمية وسعر وحدة رقمي. يُكتب معدل الضريبة كنسبة مئوية، لذلك أدخلوا 8.25 لتطبيق 8.25 في المئة بدلا من 0.0825. يمكن استعمال كميات كسرية للأعمال المقاسة بالساعات أو الوزن أو المسافة أو أي وحدة قابلة للتجزئة، كما يجوز أن تحتوي الأسعار على كسور عشرية. تُرفض الكميات والأسعار السالبة لأنها تدل غالبا على فاتورة غير سليمة أو تسوية ائتمانية ينبغي تمثيلها بإشعار دائن مستقل. لا تستخدموا الصفر إلا عند إدراج بند مجاني فعلا. تساعد الأوصاف الدقيقة على مطابقة المستند النهائي مع أوامر الشراء وسجلات التسليم والعقود. لا يحتوي الطلب على تاريخ أو معرّف مولد، ولهذا تعطي الطلبات المتطابقة النتيجة نفسها دائما.

افهموا طريقة حساب كل مبلغ

يضرب المولد كمية كل بند في سعر الوحدة، ثم يقرّب إجمالي البند الناتج إلى منزلتين عشريتين. وبعد ذلك يجمع إجماليات البنود المقربة للحصول على المجموع الفرعي. تُحسب الضريبة بضرب ذلك المجموع في معدل الضريبة المئوي المرسل، وتُقرب هي أيضا إلى منزلتين. وأخيرا، تُضاف الضريبة المقربة إلى المجموع الفرعي لإنتاج الإجمالي النهائي. هذا الترتيب صريح وحتمي، وهو أمر مهم لأن الأنظمة المحاسبية قد تعطي نتائج مختلفة إذا أجرت التقريب في مرحلة أخرى. تحتفظ النتيجة بوصف كل بند وكميته، وتعرض أسعار الوحدات كقيم مالية، وتضيف line_total إلى كل سطر. وعلى مستوى المستند، تتضمن subtotal وtax_rate وtax وgrand_total إلى جانب البائع والمشتري. لا يجري النظام تحويلا للعملات ولا يستنتج العملة، ولذلك يجب أن تكون كل الأسعار بعملة واحدة يختارها المستدعي. تمثل الاستجابة المنظمة سجل بيانات وحسابات جاهزا لقالب أو قاعدة بيانات أو خطوة موافقة أو تكامل API، وليست ملف PDF أو صورة.

ادمجوا الحساب بأمان في سير الفوترة

استخدموا هذه الإمكانية عند النقطة التي تتحول فيها بيانات الطلب القابلة للتعديل إلى سجل فاتورة. تحققوا أولا من سياق العمل: الطرفان والعملة والولاية الضريبية والحاجة إلى خصومات أو اقتطاعات أو معدلات ضريبية متعددة أو تسويات ائتمانية. ثم أرسلوا البنود الموحدة واحفظوا الكائن المعاد بوصفه نتيجة الحساب. لا تستخدم الخوارزمية شبكة أو قيما عشوائية أو ساعة أو حالة مخفية، لذا يمكن إعادة الطلب نفسه بأمان ومقارنة نتائجه أثناء التدقيق. تظهر الأخطاء عند غياب الحقول المطلوبة أو وجود مبالغ غير رقمية أو قائمة فارغة أو أكبر من الحد أو معدل ضريبة سالب، وبخاصة عند وجود كمية أو سعر سالب. عالجوا هذه الأخطاء قبل تعيين رقم للفاتورة أو إرسال أي شيء إلى العميل. يمكن تمرير النتيجة إلى قالب HTML أو استيراد محاسبي أو مولد مرفقات أو قائمة موافقات، لكن هذه الإجراءات تبقى منفصلة. يحافظ هذا الفصل على قابلية اختبار الحساب ويمنع العرض من تغيير الإجماليات بصمت. تبلغ كلفة طلب API مقدار $0.002، ويستخدم المتصفح منطق الحساب النقي نفسه لتتطابق النتائج التفاعلية والمؤتمتة.

حالات الاستخدام

إصدار فواتير الطلبات المعتمدة

حوّلوا بنود الطلبات الموحدة إلى فاتورة منظمة ذات مبالغ وضرائب متسقة.

تشغيل نموذج لإنشاء الفواتير

احسبوا الإجماليات أثناء إدخال الطرفين والبنود والضريبة، ثم مرروا النتيجة إلى أداة العرض.

توحيد تكاملات الفوترة

وفروا لعدة تطبيقات عقد حساب حتميا واحدا قبل إدخال السجلات في المحاسبة أو الموافقات.

الأسئلة الشائعة

ما كلفة الطلب الواحد؟

تبلغ كلفة كل طلب API مقدار $0.002.

كيف ينبغي إدخال معدل الضريبة؟

أدخلوا رقما مئويا؛ فعلى سبيل المثال، استخدموا 8.25 لتطبيق معدل قدره 8.25 في المئة.

كيف تُقرب القيم المالية؟

يُقرب إجمالي كل بند إلى منزلتين، ثم تُجمع البنود لتكوين المجموع الفرعي، وبعدها تُحسب الضريبة وتُقرب.

هل يمكن استخدام كميات أو أسعار سالبة للأرصدة؟

لا. تؤدي أي كمية أو سعر وحدة سالب إلى خطأ في الإدخال. استخدموا إجراء مستقلا لإشعار الدائن.

هل تشمل النتيجة ملف PDF أو رقم فاتورة؟

لا. تعيد بيانات فاتورة منظمة مع الإجماليات المحسوبة. العرض والترقيم وتحديد العملة والتسليم خطوات منفصلة.

للمطوّرين — الوصول عبر API

كل ما في هذه الصفحة متاح برمجيًا. هذا القسم موجّه للفرق التقنية التي تريد ربط الأداة بأنظمتها الخاصة؛ بقية المستخدمين يمكنهم استخدام الأداة أعلاه مباشرة دون الحاجة لقراءة ما يلي.

الـEndpoint

POSThttps://api.kit.forhosting.com/doc/invoice-generate

صادِق على طلبك بترويسة Bearer، وأرسل طلب POST واحدًا لتدخل مهمتك قائمة التنفيذ فورًا؛ ثم تستلم النتيجة عبر webhook أو رابط موقّع.

استدعِ الخدمة من بيئتك

curl -X POST https://api.kit.forhosting.com/doc/invoice-generate \
  -H "Authorization: Bearer $KIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"seller":"Northwind Studio","buyer":"Contoso Retail","line_items":[{"description":"Design consultation","quantity":2,"unit_price":125},{"description":"Style guide","quantity":1,"unit_price":80.5}],"tax_rate":8.25}'

const res = await fetch("https://api.kit.forhosting.com/doc/invoice-generate", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.KIT_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "seller": "Northwind Studio",
    "buyer": "Contoso Retail",
    "line_items": [
      {
        "description": "Design consultation",
        "quantity": 2,
        "unit_price": 125
      },
      {
        "description": "Style guide",
        "quantity": 1,
        "unit_price": 80.5
      }
    ],
    "tax_rate": 8.25
  })
});
const { task_id } = await res.json();

import os, requests

res = requests.post(
    "https://api.kit.forhosting.com/doc/invoice-generate",
    headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
    json={
    "seller": "Northwind Studio",
    "buyer": "Contoso Retail",
    "line_items": [
        {
            "description": "Design consultation",
            "quantity": 2,
            "unit_price": 125
        },
        {
            "description": "Style guide",
            "quantity": 1,
            "unit_price": 80.5
        }
    ],
    "tax_rate": 8.25
},
)
task_id = res.json()["task_id"]

<?php
$res = file_get_contents("https://api.kit.forhosting.com/doc/invoice-generate", false, stream_context_create([
  "http" => [
    "method"  => "POST",
    "header"  => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
    "content" => '{"seller":"Northwind Studio","buyer":"Contoso Retail","line_items":[{"description":"Design consultation","quantity":2,"unit_price":125},{"description":"Style guide","quantity":1,"unit_price":80.5}],"tax_rate":8.25}',
  ],
]));
$task = json_decode($res, true);

body := bytes.NewBufferString(`{"seller":"Northwind Studio","buyer":"Contoso Retail","line_items":[{"description":"Design consultation","quantity":2,"unit_price":125},{"description":"Style guide","quantity":1,"unit_price":80.5}],"tax_rate":8.25}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/doc/invoice-generate", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)

مثال على الطلب

{
  "seller": "Northwind Studio",
  "buyer": "Contoso Retail",
  "line_items": [
    {
      "description": "Design consultation",
      "quantity": 2,
      "unit_price": 125
    },
    {
      "description": "Style guide",
      "quantity": 1,
      "unit_price": 80.5
    }
  ],
  "tax_rate": 8.25
}

مثال على الاستجابة

{
  "task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
  "type": "doc.invoice_generate",
  "status": "queued",
  "_links": {
    "result": "/tasks/tsk_…/result"
  }
}

الواجهة غير متزامنة: تستلم task_id فور الإرسال، ويمكنك الاستعلام عن الحالة بمعدل طلب واحد في الثانية.

الأسعار

لكل طلب$0.002

السعر معلن كما تراه: لا tokens ولا نظام نقاط؛ وإن فشلت المهمة فلن تُحاسَب عليها.

الحدود

`max_mb`	25
`max_pages`	200

الأخطاء

HTTP	الرمز	المعنى
`401`	`unauthorized`	مفتاح الوصول مفقود أو غير صالح؛ تحقق من ترويسة Bearer في طلبك.
`402`	`insufficient_balance`	رصيدك لا يكفي لتنفيذ هذه المهمة؛ أعد شحن الرصيد ثم أعد المحاولة.
`404`	`unknown_type`	نوع المهمة المطلوب غير موجود في الكتالوج — راجع الاسم المرسل في الطلب.
`429`	`rate_limited`	تجاوزت الحد المسموح من الطلبات؛ انتظر قليلًا ثم أعد المحاولة.

اطّلع على توثيق KIT الكامل ←