{
    "openapi": "3.1.0",
    "info": {
        "title": "Fawtara API",
        "version": "1.0.0",
        "description": "واجهة برمجية موحّدة لربط أنظمة الشركات مع نظام الفوترة الوطني الأردني (JoFotara).\nترسل JSON بسيطًا، وتتولّى المنصّة بناء UBL 2.1، والتوقيع المنطقي، والإرسال، وتخزين رمز QR.",
        "contact": {
            "name": "دعم فواترا",
            "url": "https://fawtara.codexal.co/app/docs/overview"
        }
    },
    "servers": [
        {
            "url": "https://fawtara.codexal.co/api",
            "description": "الإنتاج"
        }
    ],
    "security": [
        {
            "bearerAuth": []
        }
    ],
    "components": {
        "securitySchemes": {
            "bearerAuth": {
                "type": "http",
                "scheme": "bearer",
                "description": "مفتاح الـ API: fwt_live_… للإنتاج أو fwt_test_… لبيئة الاختبار."
            }
        },
        "schemas": {
            "InvoiceRequest": {
                "type": "object",
                "required": [
                    "invoice_number",
                    "customer",
                    "lines"
                ],
                "properties": {
                    "invoice_number": {
                        "type": "string",
                        "maxLength": 64,
                        "example": "INV-2026-001"
                    },
                    "issue_date": {
                        "type": "string",
                        "format": "date",
                        "example": "2026-10-05"
                    },
                    "payment_method": {
                        "type": "string",
                        "enum": [
                            "cash",
                            "receivable"
                        ],
                        "default": "cash"
                    },
                    "currency": {
                        "type": "string",
                        "default": "JOD"
                    },
                    "note": {
                        "type": "string",
                        "maxLength": 500
                    },
                    "global_discount": {
                        "type": "number",
                        "format": "float",
                        "default": 0
                    },
                    "metadata": {
                        "type": "object",
                        "additionalProperties": true
                    },
                    "customer": {
                        "type": "object",
                        "required": [
                            "name"
                        ],
                        "properties": {
                            "name": {
                                "type": "string"
                            },
                            "identity_type": {
                                "type": "string",
                                "enum": [
                                    "tax",
                                    "national",
                                    "passport"
                                ],
                                "default": "tax"
                            },
                            "identity_number": {
                                "type": "string"
                            },
                            "tin": {
                                "type": "string"
                            },
                            "phone": {
                                "type": "string"
                            },
                            "city": {
                                "type": "string"
                            },
                            "address": {
                                "type": "string"
                            },
                            "postal_code": {
                                "type": "string"
                            },
                            "country_code": {
                                "type": "string",
                                "default": "JO"
                            },
                            "email": {
                                "type": "string",
                                "format": "email"
                            }
                        }
                    },
                    "lines": {
                        "type": "array",
                        "minItems": 1,
                        "maxItems": 300,
                        "items": {
                            "type": "object",
                            "required": [
                                "name",
                                "unit_price"
                            ],
                            "properties": {
                                "name": {
                                    "type": "string"
                                },
                                "description": {
                                    "type": "string"
                                },
                                "sku": {
                                    "type": "string"
                                },
                                "quantity": {
                                    "type": "number",
                                    "default": 1
                                },
                                "unit_code": {
                                    "type": "string",
                                    "default": "PCE"
                                },
                                "unit_price": {
                                    "type": "number"
                                },
                                "discount": {
                                    "type": "number",
                                    "default": 0
                                },
                                "tax_percent": {
                                    "type": "number",
                                    "default": 0
                                },
                                "tax_category": {
                                    "type": "string",
                                    "enum": [
                                        "S",
                                        "Z",
                                        "O",
                                        "E"
                                    ]
                                }
                            }
                        }
                    }
                }
            },
            "Error": {
                "type": "object",
                "properties": {
                    "error": {
                        "type": "object",
                        "properties": {
                            "type": {
                                "type": "string",
                                "example": "validation_error"
                            },
                            "message": {
                                "type": "string"
                            },
                            "fields": {
                                "type": "object",
                                "additionalProperties": {
                                    "type": "array",
                                    "items": {
                                        "type": "string"
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "parameters": {
            "IdempotencyKey": {
                "name": "Idempotency-Key",
                "in": "header",
                "required": false,
                "schema": {
                    "type": "string",
                    "maxLength": 80
                },
                "description": "مفتاح فريد يمنع تكرار إنشاء الفاتورة عند إعادة إرسال الطلب."
            }
        }
    },
    "paths": {
        "/v1/ping": {
            "get": {
                "summary": "فحص المفتاح والاتصال",
                "tags": [
                    "الحساب"
                ],
                "responses": {
                    "200": {
                        "description": "المفتاح صالح"
                    }
                }
            }
        },
        "/v1/account": {
            "get": {
                "summary": "بيانات الحساب والخطة",
                "tags": [
                    "الحساب"
                ],
                "responses": {
                    "200": {
                        "description": "تم"
                    }
                }
            }
        },
        "/v1/usage": {
            "get": {
                "summary": "الاستهلاك الشهري والحصة المتبقية",
                "tags": [
                    "الحساب"
                ],
                "responses": {
                    "200": {
                        "description": "تم"
                    }
                }
            }
        },
        "/v1/plans": {
            "get": {
                "summary": "قائمة الباقات (عامّة، بلا مصادقة)",
                "tags": [
                    "الحساب"
                ],
                "security": [],
                "responses": {
                    "200": {
                        "description": "تم"
                    }
                }
            }
        },
        "/v1/invoices": {
            "post": {
                "summary": "إنشاء فاتورة وإرسالها إلى الفوترة الوطنية",
                "tags": [
                    "الفواتير"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/InvoiceRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "قُبلت الفاتورة من البوابة"
                    },
                    "202": {
                        "description": "أُنشئت ولم تُقبل بعد — راجع الحقل error"
                    },
                    "402": {
                        "description": "تجاوز الحصة أو اشتراك غير نشط",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "رقم فاتورة مكرّر"
                    },
                    "422": {
                        "description": "خطأ تحقّق",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "تجاوز حد الطلبات"
                    }
                }
            },
            "get": {
                "summary": "سرد الفواتير",
                "tags": [
                    "الفواتير"
                ],
                "parameters": [
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 1
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 25,
                            "maximum": 100
                        }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "pending",
                                "accepted",
                                "rejected",
                                "error"
                            ]
                        }
                    },
                    {
                        "name": "mode",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "live",
                                "test"
                            ]
                        }
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "تم"
                    }
                }
            }
        },
        "/v1/invoices/preview": {
            "post": {
                "summary": "بناء UBL ومعاينته دون إرسال",
                "tags": [
                    "الفواتير"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/InvoiceRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "تم بناء الـ XML"
                    }
                }
            }
        },
        "/v1/invoices/{id}": {
            "get": {
                "summary": "استرجاع فاتورة",
                "tags": [
                    "الفواتير"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "معرّف الفاتورة inv_… أو رقمها"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "تم"
                    },
                    "404": {
                        "description": "غير موجودة"
                    }
                }
            }
        },
        "/v1/invoices/{id}/retry": {
            "post": {
                "summary": "إعادة إرسال فاتورة مرفوضة أو فاشلة",
                "tags": [
                    "الفواتير"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "قُبلت"
                    },
                    "202": {
                        "description": "ما زالت غير مقبولة"
                    }
                }
            }
        },
        "/v1/invoices/{id}/ubl": {
            "get": {
                "summary": "تنزيل ملف UBL 2.1",
                "tags": [
                    "الفواتير"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "XML",
                        "content": {
                            "application/xml": {}
                        }
                    }
                }
            }
        },
        "/v1/invoices/{id}/qr.png": {
            "get": {
                "summary": "صورة رمز الاستجابة السريعة",
                "tags": [
                    "الفواتير"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "scale",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 6,
                            "minimum": 2,
                            "maximum": 14
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "PNG",
                        "content": {
                            "image/png": {}
                        }
                    }
                }
            }
        },
        "/v1/credit-notes": {
            "post": {
                "summary": "إشعار دائن (مرتجع) مرتبط بفاتورة أصلية",
                "tags": [
                    "الفواتير"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "allOf": [
                                    {
                                        "$ref": "#/components/schemas/InvoiceRequest"
                                    },
                                    {
                                        "type": "object",
                                        "required": [
                                            "original_invoice_id",
                                            "return_reason"
                                        ],
                                        "properties": {
                                            "original_invoice_id": {
                                                "type": "string",
                                                "example": "inv_8f2c1a9b4d0e6f73"
                                            },
                                            "return_reason": {
                                                "type": "string",
                                                "example": "إرجاع بضاعة تالفة"
                                            }
                                        }
                                    }
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "قُبل الإشعار"
                    },
                    "422": {
                        "description": "خطأ تحقّق"
                    }
                }
            }
        },
        "/v1/webhooks": {
            "get": {
                "summary": "سرد نقاط الـ Webhook",
                "tags": [
                    "Webhooks"
                ],
                "responses": {
                    "200": {
                        "description": "تم"
                    }
                }
            },
            "post": {
                "summary": "إضافة نقطة Webhook",
                "tags": [
                    "Webhooks"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "url"
                                ],
                                "properties": {
                                    "url": {
                                        "type": "string",
                                        "format": "uri",
                                        "example": "https://erp.example.com/hooks/fawtara"
                                    },
                                    "events": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "example": [
                                            "invoice.accepted",
                                            "invoice.rejected"
                                        ]
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "أُنشئت"
                    },
                    "403": {
                        "description": "الخطة لا تدعم الـ Webhooks"
                    }
                }
            }
        },
        "/v1/webhooks/{id}": {
            "delete": {
                "summary": "حذف نقطة Webhook",
                "tags": [
                    "Webhooks"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "حُذفت"
                    }
                }
            }
        }
    }
}