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 للفاتورة:
discount_rate وfixed_discount الخاصان بالفاتورة.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 غير موجود، أو أحد البنود ناقص، أو قيمة لا تطابق نوع خاصيتها، أو أُرسل حقل يضعه نظام علاقات بنفسه. |