إنشاء فاتورة

POST https://app.alaaqat.com/api/invoices

تُنشئ هذه النقطة فاتورة جديدة. يحتاج مفتاح واجهة التطبيق البرمجية إلى الإمكانية invoice-create، ويحتاج عضو الفريق الذي أنشأ المفتاح إلى صلاحية إنشاء الفواتير.

ترويسة الطلب

{
    "Accept": "application/json",
    "Content-Type": "application/json"
}

محتوى الطلب

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

{
    title: string,
    items: [
        {
            name: string,
            description?: string | null,
            unit_price: number,
            quantity: number,
            unit_discount?: number,
            tax_rate?: number
        }
    ],
    currency?: string,
    status?: string,
    due_date?: string,
    discount_rate?: number,
    fixed_discount?: number,
    tax_rate?: number,
    fixed_tax?: number,
    fees_rate?: number,
    fixed_fees?: number,
    description?: string,
    comments?: string,
    owner?: number,
    communication_team?: number,
    association_ids?: {
        [object_type: string]: string[]
    },
    [internal_name: string]: any
}
الحقل مطلوب التحققات الوصف
title مطلوب نص عنوان الفاتورة.
items مطلوب مصفوفة من بند واحد أو أكثر بنود الفاتورة. راجع البنود والمبلغ.
items.*.name مطلوب نص حتى 100 حرف ما يُباع في هذا البند.
items.*.description اختياري نص حتى 1,024 حرفاً، أو null تفاصيل إضافية عن البند.
items.*.unit_price مطلوب رقم سعر الوحدة الواحدة.
items.*.quantity مطلوب عدد صحيح عدد الوحدات.
items.*.unit_discount اختياري رقم مبلغ يُخصم من كل وحدة.
items.*.tax_rate اختياري رقم يمثل نسبة مئوية ضريبة هذا البند، مثل 16 لنسبة 16%.
currency اختياري رمز عملة، مثل JOD أو SAR أو USD خيارات الخاصية Currency، ويمكنك عرضها عبر قائمة خصائص الفواتير.
status اختياري draft أو open أو paid أو partially_paid أو voided حالة الفاتورة.
due_date اختياري تاريخ، مثل 2026-11-30 تاريخ استحقاق الفاتورة.
discount_rate اختياري رقم يمثل نسبة مئوية خصم على الفاتورة كلها.
fixed_discount اختياري رقم مبلغ ثابت يُخصم من الفاتورة كلها.
tax_rate اختياري رقم يمثل نسبة مئوية ضريبة على الفاتورة كلها.
fixed_tax اختياري رقم مبلغ ضريبة ثابت يُضاف إلى الفاتورة.
fees_rate اختياري رقم يمثل نسبة مئوية رسوم على الفاتورة كلها.
fixed_fees اختياري رقم رسم ثابت يُضاف إلى الفاتورة.
description, comments اختياري نص نص حر يظهر على الفاتورة.
owner اختياري معرّف عضو في الفريق عضو الفريق الذي يملكها.
communication_team اختياري معرّف فريق الفريق الذي ينتمي إليه السجل.
association_ids اختياري كائن من أنواع السجلات، لكل نوع مصفوفة من المعرّفات يربط السجل الجديد بسجلات موجودة. راجع الربط عند الإنشاء.
أي خاصية أخرى اختياري يطابق نوع الخاصية استخدم internal_name للخاصية مفتاحاً.

يضع نظام علاقات _id وinvoice_number وamount بنفسه، ويُرفض الطلب الذي يرسل أياً منها، وكذلك الطلب الذي يرسل خاصية تحمل "system_only": true.

{
    "title": "Office chairs, October order",
    "currency": "JOD",
    "status": "open",
    "due_date": "2026-11-30",
    "discount_rate": 5,
    "tax_rate": 16,
    "items": [
        {
            "name": "Ergonomic office chair",
            "description": "Black mesh back",
            "unit_price": 120,
            "quantity": 4,
            "unit_discount": 10
        },
        {
            "name": "Delivery and assembly",
            "unit_price": 35,
            "quantity": 1
        }
    ],
    "association_ids": {
        "contact": [
            "6650f1a2b3c4d5e6f7a8b901"
        ],
        "product": [
            "6656b1c2d3e4f5a6b7c8d901"
        ]
    }
}

البنود والمبلغ

يحسب نظام علاقات بنفسه قيمة net_price لكل بند، وقيمة amount للفاتورة:

  1. قيمة البند هي سعر الوحدة بعد خصم الوحدة، مضروباً في الكمية، ثم تُضاف ضريبة البند.
  2. تُجمع قيم البنود، ثم يُخصم منها discount_rate وfixed_discount الخاصان بالفاتورة.
  3. تُضاف tax_rate وfixed_tax الخاصتان بالفاتورة، ثم fees_rate وfixed_fees.

في المثال أعلاه، قيمة الكراسي (120 − 10) × 4 = 440، وقيمة التوصيل 35. يصبح المجموع 475، وبعد خصم 5% يصبح 451.25، ثم تجعل ضريبة 16% قيمة amount تساوي 523.45.

تُطبَّق ضريبة البند tax_rate وضريبة الفاتورة tax_rate كلتاهما، فاستخدم إحداهما فقط حتى لا تُحسب الضريبة مرتين.

ويعطي نظام علاقات كل فاتورة الرقم التالي في تسلسل فواتيرك، مثل INV-1001، ضمن invoice_number.

الربط عند الإنشاء

يربط الحقل association_ids السجل الجديد بسجلات موجودة لديك في الطلب نفسه. كل مفتاح فيه نوع سجل: contact أو company أو deal أو ticket أو product أو invoice، عدا invoice، وقيمة كل مفتاح مصفوفة من قيم _id لسجلات من ذلك النوع. ويُتجاوز المعرّف الذي لا يعود لسجل في حسابك.

للربط لاحقاً، راجع الارتباطات.

الإستجابة

201 Created، ويأتي السجل الجديد ضمن data وبنوده ضمن data.items.

{
    "data": {
        "properties": {
            "_id": "6657c1d2e3f4a5b6c7d8e901",
            "title": "Office chairs, October order",
            "status": "open",
            "currency": "JOD",
            "discount_rate": 5,
            "tax_rate": 16,
            "invoice_number": "INV-1001",
            "amount": 523.45,
            "created_by": 12,
            "updated_at": "2026-10-20T09:30:00.000000Z",
            "created_at": "2026-10-20T09:30:00.000000Z"
        },
        "account_id": 1024,
        "items": [
            {
                "net_price": 440,
                "name": "Ergonomic office chair",
                "unit_price": 120,
                "quantity": 4,
                "description": "Black mesh back",
                "unit_discount": 10,
                "tax_rate": 0
            },
            {
                "net_price": 35,
                "name": "Delivery and assembly",
                "unit_price": 35,
                "quantity": 1,
                "description": null,
                "unit_discount": 0,
                "tax_rate": 0
            }
        ]
    },
    "message": "Entity was created successfully."
}

الأخطاء

الرمز المعنى
422 الحقل title أو items غير موجود، أو أحد البنود ناقص، أو قيمة لا تطابق نوع خاصيتها، أو أُرسل حقل يضعه نظام علاقات بنفسه.