API الفواتير
مرجع كامل لنقاط نهاية الفواتير. تتضمن الاستجابات match_status للمطابقة الثلاثية (full_match، partial_match، mismatch، pending_grn) و**payment_status** للتسوية (unpaid، partial، paid، overdue).
قائمة الفواتير
http
GET /v1/invoicesمعاملات الاستعلام
| المعامل | النوع | الوصف |
|---|---|---|
status | string | تصفية حسب حالة سير العمل: draft، submitted، pending، approved، paid، cancelled |
vendor_id | integer | تصفية حسب المورد |
purchase_order_id | integer | تصفية حسب معرف أمر الشراء المرتبط (هذا هو معرف سجل PO؛ غالبًا يُسمى po_id في تطبيقات العميل) |
match_status | string | تصفية حسب المطابقة الثلاثية: full_match، partial_match، mismatch، pending_grn |
from_date | date | فواتير بتاريخ invoice_date في هذا التاريخ أو بعده (ISO 8601) |
to_date | date | فواتير بتاريخ invoice_date في هذا التاريخ أو قبله (ISO 8601) |
sort_by | string | حقل الفرز (الافتراضي: created_at) |
sort_order | string | asc أو desc (الافتراضي: desc) |
per_page | integer | حجم الصفحة (الافتراضي: 15) |
مثال الطلب
bash
curl -X GET "https://api.waqti.sa/v1/invoices?status=submitted&vendor_id=5&purchase_order_id=42&from_date=2026-01-01&to_date=2026-03-31&per_page=20" \
-H "Authorization: Bearer 3|a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0" \
-H "Accept: application/json"مثال الاستجابة
json
{
"data": [
{
"id": 1088,
"invoice_number": "INV-001088",
"vendor_invoice_number": "VND-2026-0142",
"status": "submitted",
"payment_status": "unpaid",
"match_status": "full_match",
"currency": "SAR",
"subtotal": 20000.00,
"vat_amount": 3000.00,
"total": 23000.00,
"invoice_date": "2026-03-10T00:00:00Z",
"due_date": "2026-04-09T00:00:00Z",
"vendor": {
"id": 5,
"name": "ABC Supplies Co."
},
"purchase_order": {
"id": 42,
"po_number": "PO-2026-0042"
},
"created_at": "2026-03-11T08:15:00Z"
},
{
"id": 1089,
"invoice_number": "INV-001089",
"vendor_invoice_number": "VND-2026-0143",
"status": "submitted",
"payment_status": "unpaid",
"match_status": "pending_grn",
"currency": "SAR",
"subtotal": 8500.00,
"vat_amount": 1275.00,
"total": 9775.00,
"invoice_date": "2026-03-12T00:00:00Z",
"due_date": "2026-04-11T00:00:00Z",
"vendor": {
"id": 5,
"name": "ABC Supplies Co."
},
"purchase_order": {
"id": 43,
"po_number": "PO-2026-0043"
},
"created_at": "2026-03-12T11:40:00Z"
}
],
"meta": {
"current_page": 1,
"last_page": 2,
"per_page": 20,
"total": 35
}
}إنشاء فاتورة
http
POST /v1/invoicesجسم الطلب
json
{
"vendor_id": 5,
"po_id": 42,
"invoice_number": "VND-2026-0142",
"invoice_date": "2026-03-10",
"due_date": "2026-04-09",
"currency": "SAR",
"line_items": [
{
"description": "Laptop docking stations",
"quantity": 10,
"unit": "unit",
"unit_price": 450.00,
"vat_rate": 15
},
{
"description": "USB-C cables (2m)",
"quantity": 50,
"unit": "piece",
"unit_price": 35.00,
"vat_rate": 15
}
],
"subtotal": 6250.00,
"vat_amount": 937.50,
"total": 7187.50,
"description": "Hardware shipment per PO-2026-0042"
}po_id هو معرف أمر الشراء المرتبط. قد تستخدم الحمولات purchase_order_id بدل po_id بنفس المعنى.
الاستجابة
json
{
"data": {
"id": 1090,
"invoice_number": "INV-001090",
"vendor_invoice_number": "VND-2026-0142",
"status": "draft",
"payment_status": "unpaid",
"match_status": "pending_grn",
"vendor_id": 5,
"purchase_order_id": 42,
"currency": "SAR",
"subtotal": 6250.00,
"vat_amount": 937.50,
"total": 7187.50,
"invoice_date": "2026-03-10T00:00:00Z",
"due_date": "2026-04-09T00:00:00Z",
"line_items": [
{
"id": 501,
"line_number": 1,
"description": "Laptop docking stations",
"quantity": 10,
"unit": "unit",
"unit_price": 450.00,
"vat_rate": 15,
"vat_amount": 675.00,
"line_total": 5175.00
},
{
"id": 502,
"line_number": 2,
"description": "USB-C cables (2m)",
"quantity": 50,
"unit": "piece",
"unit_price": 35.00,
"vat_rate": 15,
"vat_amount": 262.50,
"line_total": 2012.50
}
],
"created_at": "2026-03-14T09:00:00Z"
}
}الحصول على فاتورة
http
GET /v1/invoices/{id}الاستجابة
json
{
"data": {
"id": 1088,
"invoice_number": "INV-001088",
"vendor_invoice_number": "VND-2026-0142",
"status": "approved",
"payment_status": "partial",
"match_status": "full_match",
"vendor": {
"id": 5,
"name": "ABC Supplies Co.",
"email": "sales@abcsupplies.com",
"vat_number": "300000000000003"
},
"purchase_order": {
"id": 42,
"po_number": "PO-2026-0042",
"status": "completed",
"total_inc_vat": 23000.00
},
"goods_receipt": {
"id": 17,
"gr_number": "GR-2026-0017",
"status": "complete"
},
"currency": "SAR",
"subtotal": 20000.00,
"vat_amount": 3000.00,
"total": 23000.00,
"amount_paid": 10000.00,
"amount_due": 13000.00,
"invoice_date": "2026-03-10T00:00:00Z",
"due_date": "2026-04-09T00:00:00Z",
"description": "Q1 IT peripherals",
"line_items": [
{
"id": 495,
"line_number": 1,
"description": "Network switches (24-port)",
"quantity": 4,
"unit": "unit",
"unit_price": 2500.00,
"vat_rate": 15,
"vat_amount": 1500.00,
"line_total": 11500.00
},
{
"id": 496,
"line_number": 2,
"description": "Rack mounting kits",
"quantity": 4,
"unit": "unit",
"unit_price": 1500.00,
"vat_rate": 15,
"vat_amount": 900.00,
"line_total": 6900.00
}
],
"match_summary": {
"po_variance_pct": 0.0,
"gr_variance_pct": 0.0,
"last_matched_at": "2026-03-11T14:05:00Z"
},
"approved_by": {
"id": 22,
"name": "Noura Al-Faisal"
},
"approved_at": "2026-03-11T14:10:00Z",
"created_at": "2026-03-11T08:15:00Z",
"updated_at": "2026-03-11T14:10:00Z"
}
}تحديث فاتورة
http
PUT /v1/invoices/{id}WARNING
لا يمكن تحديث الفواتير التي حالتها approved أو paid؛ استخدم إشعارات دائنة أو سير عمل الدفع بدلًا من ذلك.
جسم الطلب
json
{
"invoice_number": "VND-2026-0142-A",
"invoice_date": "2026-03-11",
"due_date": "2026-04-15",
"description": "Corrected invoice date and terms",
"line_items": [
{
"id": 495,
"quantity": 5,
"unit_price": 2480.00
},
{
"description": "Spare SFP modules",
"quantity": 8,
"unit": "piece",
"unit_price": 190.00,
"vat_rate": 15
}
],
"subtotal": 13920.00,
"vat_amount": 2088.00,
"total": 16008.00
}الاستجابة
json
{
"data": {
"id": 1088,
"invoice_number": "INV-001088",
"vendor_invoice_number": "VND-2026-0142-A",
"status": "submitted",
"payment_status": "unpaid",
"match_status": "partial_match",
"currency": "SAR",
"subtotal": 13920.00,
"vat_amount": 2088.00,
"total": 16008.00,
"invoice_date": "2026-03-11T00:00:00Z",
"due_date": "2026-04-15T00:00:00Z",
"description": "Corrected invoice date and terms",
"updated_at": "2026-03-14T16:22:00Z"
}
}الموافقة على فاتورة
http
POST /v1/invoices/{id}/approveيسجّل الموافقة بعد المطابقة الثلاثية وفحوصات السياسة. شرط نموذجي: أن يكون match_status مساويًا لـ full_match أو تسمح قواعد المستأجر بـ partial_match.
جسم الطلب
json
{
"comments": "Matched to GR-2026-0017 and PO-2026-0042 — approve for payment"
}الاستجابة
json
{
"data": {
"id": 1088,
"invoice_number": "INV-001088",
"status": "approved",
"payment_status": "unpaid",
"match_status": "full_match",
"approved_by": {
"id": 22,
"name": "Noura Al-Faisal"
},
"approved_at": "2026-03-11T14:10:00Z"
}
}رفض فاتورة
http
POST /v1/invoices/{id}/rejectجسم الطلب
json
{
"reason": "Mismatch: invoice total exceeds PO remaining balance after GRN"
}الاستجابة
json
{
"data": {
"id": 1091,
"invoice_number": "INV-001091",
"status": "cancelled",
"payment_status": "unpaid",
"match_status": "mismatch",
"rejection_reason": "Mismatch: invoice total exceeds PO remaining balance after GRN",
"rejected_at": "2026-03-15T10:45:00Z"
}
}