{
  "info": {
    "_postman_id": "e44ba2f4-6d3a-4f97-b3f9-8a0fab096ea1",
    "name": "ZATCA Integration API - هيئة الزكاة والضريبة",
    "description": "تكامل API مع هيئة الزكاة والضريبة والجمارك (ZATCA) للفواتير الإلكترونية.\n\n## خطوات التكامل:\n1. **الخطوة 0**: توليد CSR والمفاتيح\n2. **الخطوة 1**: طلب Compliance CSID (تحتاج OTP من بوابة الهيئة)\n3. **الخطوة 2**: إرسال فواتير تجريبية للتحقق\n4. **الخطوة 3**: طلب Production CSID\n5. **إرسال الفواتير**: إرسال الفواتير الفعلية إلى ZATCA\n\n## ملاحظات:\n- يجب الحصول على OTP من بوابة ZATCA: https://fatoora.zatca.gov.sa\n- البيئة الافتراضية: Sandbox\n- يدعم الفواتير المبسطة والقياسية",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
    "_exporter_id": "37722216"
  },
  "item": [
    {
      "name": "Authentication",
      "item": [
        {
          "name": "Login - Get Token",
          "event": [
            {
              "listen": "test",
              "script": {
                "exec": [
                  "var jsonData = pm.response.json();",
                  "if (jsonData.data && jsonData.data.token) {",
                  "    pm.collectionVariables.set('TOKEN', jsonData.data.token);",
                  "    console.log('Token saved successfully');",
                  "}"
                ],
                "type": "text/javascript",
                "packages": {},
                "requests": {}
              }
            }
          ],
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Accept",
                "value": "application/json",
                "type": "text"
              },
              {
                "key": "Content-Type",
                "value": "application/json",
                "type": "text"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n    \"phone_or_email\": \"admin@admin.com\",\n    \"password\": \"admin\"\n}"
            },
            "url": {
              "raw": "{{BASE_URL}}/auth/login",
              "host": [
                "{{BASE_URL}}"
              ],
              "path": [
                "auth",
                "login"
              ]
            }
          },
          "response": []
        }
      ]
    },
    {
      "name": "ZATCA Setup - خطوات الإعداد",
      "item": [
        {
          "name": "Get Integration Status - حالة التكامل",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Accept",
                "value": "application/json",
                "type": "text"
              },
              {
                "key": "Authorization",
                "value": "Bearer {{TOKEN}}",
                "type": "text"
              }
            ],
            "url": {
              "raw": "{{BASE_URL}}/zatca/status",
              "host": [
                "{{BASE_URL}}"
              ],
              "path": [
                "zatca",
                "status"
              ]
            },
            "description": "الحصول على حالة التكامل الحالية مع ZATCA.\n\nيعرض:\n- هل تم توليد CSR\n- هل تم الحصول على Compliance credentials\n- هل النظام جاهز للإنتاج"
          },
          "response": []
        },
        {
          "name": "Step 0: Generate CSR - توليد CSR",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Accept",
                "value": "application/json",
                "type": "text"
              },
              {
                "key": "Content-Type",
                "value": "application/json",
                "type": "text"
              },
              {
                "key": "Authorization",
                "value": "Bearer {{TOKEN}}",
                "type": "text"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n    \"organization_identifier\": \"310598226800003\",\n    \"organization_name\": \"اسم الشركة\",\n    \"common_name\": \"TST-886431145-399999999900003\",\n    \"organizational_unit_name\": \"فرع الرياض\",\n    \"registered_address\": \"شارع الملك فهد\",\n    \"business_category\": \"Supply activities\",\n    \"solution_name\": \"Building ERP\",\n    \"version\": \"1.0.0\",\n    \"serial_number\": \"1-TST|2-TST|3-ed22f1d8\",\n    \"postal_code\": \"12345\",\n    \"city\": \"الرياض\",\n    \"building_number\": \"1234\",\n    \"district\": \"حي النزهة\"\n}"
            },
            "url": {
              "raw": "{{BASE_URL}}/zatca/generate-csr",
              "host": [
                "{{BASE_URL}}"
              ],
              "path": [
                "zatca",
                "generate-csr"
              ]
            },
            "description": "الخطوة الأولى: توليد CSR (Certificate Signing Request) والمفاتيح.\n\n**الحقول المطلوبة:**\n- `organization_identifier`: رقم السجل التجاري (15 رقم)\n- `organization_name`: اسم الشركة\n- `common_name`: معرف فريد بتنسيق TST-XXXXXXX-XXXXXXX\n- `organizational_unit_name`: اسم الفرع\n- `registered_address`: العنوان المسجل\n- `business_category`: نوع النشاط\n- `postal_code`: الرمز البريدي\n- `city`: المدينة\n- `building_number`: رقم المبنى\n- `district`: الحي\n\n**الخطوة التالية:** احصل على OTP من بوابة ZATCA"
          },
          "response": []
        },
        {
          "name": "Step 1: Request Compliance CSID - طلب شهادة التوافق",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Accept",
                "value": "application/json",
                "type": "text"
              },
              {
                "key": "Content-Type",
                "value": "application/json",
                "type": "text"
              },
              {
                "key": "Authorization",
                "value": "Bearer {{TOKEN}}",
                "type": "text"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n    \"otp\": \"{{OTP}}\"\n}"
            },
            "url": {
              "raw": "{{BASE_URL}}/zatca/request-compliance-csid",
              "host": [
                "{{BASE_URL}}"
              ],
              "path": [
                "zatca",
                "request-compliance-csid"
              ]
            },
            "description": "الخطوة الثانية: طلب Compliance CSID من الهيئة.\n\n**المتطلبات:**\n- يجب إكمال الخطوة 0 (توليد CSR) أولاً\n- الحصول على OTP من بوابة ZATCA (https://fatoora.zatca.gov.sa)\n\n**الحقول:**\n- `otp`: رمز OTP من البوابة (6 أرقام)\n\n**النتيجة:** الحصول على Certificate و Secret للمصادقة"
          },
          "response": []
        },
        {
          "name": "Step 2: Compliance Check - فحص التوافق",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Accept",
                "value": "application/json",
                "type": "text"
              },
              {
                "key": "Content-Type",
                "value": "application/json",
                "type": "text"
              },
              {
                "key": "Authorization",
                "value": "Bearer {{TOKEN}}",
                "type": "text"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{}"
            },
            "url": {
              "raw": "{{BASE_URL}}/zatca/compliance-check",
              "host": [
                "{{BASE_URL}}"
              ],
              "path": [
                "zatca",
                "compliance-check"
              ]
            },
            "description": "الخطوة الثالثة: إرسال فواتير تجريبية للتحقق من صحة التكامل.\n\n**المتطلبات:**\n- يجب إكمال الخطوة 1 (Compliance CSID) أولاً\n\n**ما يحدث:**\n1. توليد فاتورة تجريبية\n2. توقيع الفاتورة\n3. إرسالها لـ ZATCA للتحقق\n\n**النتيجة:** تأكيد صحة التكامل"
          },
          "response": []
        },
        {
          "name": "Step 3: Request Production CSID - طلب شهادة الإنتاج",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Accept",
                "value": "application/json",
                "type": "text"
              },
              {
                "key": "Content-Type",
                "value": "application/json",
                "type": "text"
              },
              {
                "key": "Authorization",
                "value": "Bearer {{TOKEN}}",
                "type": "text"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{}"
            },
            "url": {
              "raw": "{{BASE_URL}}/zatca/request-production-csid",
              "host": [
                "{{BASE_URL}}"
              ],
              "path": [
                "zatca",
                "request-production-csid"
              ]
            },
            "description": "الخطوة الرابعة والأخيرة: طلب شهادة الإنتاج النهائية.\n\n**المتطلبات:**\n- يجب إكمال الخطوة 2 (Compliance Check) بنجاح أولاً\n\n**النتيجة:**\n- الحصول على Production Certificate\n- النظام جاهز لإرسال الفواتير الفعلية"
          },
          "response": []
        },
        {
          "name": "Reset Integration - إعادة تعيين",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Accept",
                "value": "application/json",
                "type": "text"
              },
              {
                "key": "Authorization",
                "value": "Bearer {{TOKEN}}",
                "type": "text"
              }
            ],
            "url": {
              "raw": "{{BASE_URL}}/zatca/reset",
              "host": [
                "{{BASE_URL}}"
              ],
              "path": [
                "zatca",
                "reset"
              ]
            },
            "description": "إعادة تعيين التكامل وحذف جميع الملفات.\n\n**تحذير:** سيتم حذف:\n- ملف CSR\n- المفتاح الخاص\n- بيانات Compliance credentials\n- بيانات Production credentials\n\nاستخدم هذا فقط إذا أردت البدء من جديد."
          },
          "response": []
        }
      ]
    },
    {
      "name": "Invoice Submission - إرسال الفواتير",
      "item": [
        {
          "name": "Send Invoice to ZATCA - إرسال فاتورة",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Accept",
                "value": "application/json",
                "type": "text"
              },
              {
                "key": "Authorization",
                "value": "Bearer {{TOKEN}}",
                "type": "text"
              }
            ],
            "url": {
              "raw": "{{BASE_URL}}/sales-invoices/{{INVOICE_ID}}/send-to-zatca",
              "host": [
                "{{BASE_URL}}"
              ],
              "path": [
                "sales-invoices",
                "{{INVOICE_ID}}",
                "send-to-zatca"
              ]
            },
            "description": "إرسال فاتورة مبيعات إلى ZATCA.\n\n**المتطلبات:**\n- إكمال جميع خطوات الإعداد\n- فاتورة مبيعات صحيحة مع بيانات كاملة\n\n**أنواع الفواتير:**\n- `simplified`: فاتورة مبسطة (Reporting)\n- `standard`: فاتورة قياسية (Clearance)\n\n**النتيجة:**\n- Hash الفاتورة\n- QR Code\n- حالة الإرسال"
          },
          "response": []
        },
        {
          "name": "Retry Failed Invoice - إعادة إرسال فاتورة فاشلة",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Accept",
                "value": "application/json",
                "type": "text"
              },
              {
                "key": "Authorization",
                "value": "Bearer {{TOKEN}}",
                "type": "text"
              }
            ],
            "url": {
              "raw": "{{BASE_URL}}/sales-invoices/{{INVOICE_ID}}/retry-zatca",
              "host": [
                "{{BASE_URL}}"
              ],
              "path": [
                "sales-invoices",
                "{{INVOICE_ID}}",
                "retry-zatca"
              ]
            },
            "description": "إعادة إرسال فاتورة فشل إرسالها سابقاً.\n\n**الشروط:**\n- الفاتورة يجب أن تكون بحالة `failed` أو `rejected`\n- الحد الأقصى للمحاولات: 5"
          },
          "response": []
        },
        {
          "name": "Get Invoice ZATCA Status - حالة الفاتورة",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Accept",
                "value": "application/json",
                "type": "text"
              },
              {
                "key": "Authorization",
                "value": "Bearer {{TOKEN}}",
                "type": "text"
              }
            ],
            "url": {
              "raw": "{{BASE_URL}}/sales-invoices/{{INVOICE_ID}}/zatca-status",
              "host": [
                "{{BASE_URL}}"
              ],
              "path": [
                "sales-invoices",
                "{{INVOICE_ID}}",
                "zatca-status"
              ]
            },
            "description": "الحصول على حالة إرسال الفاتورة إلى ZATCA.\n\n**المعلومات المعادة:**\n- حالة الإرسال (not_submitted, pending, submitted, cleared, reported, failed, rejected)\n- تاريخ الإرسال\n- عدد المحاولات\n- Hash الفاتورة\n- وجود QR Code"
          },
          "response": []
        },
        {
          "name": "Get Invoice QR Code - رمز QR",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Accept",
                "value": "application/json",
                "type": "text"
              },
              {
                "key": "Authorization",
                "value": "Bearer {{TOKEN}}",
                "type": "text"
              }
            ],
            "url": {
              "raw": "{{BASE_URL}}/sales-invoices/{{INVOICE_ID}}/qr-code",
              "host": [
                "{{BASE_URL}}"
              ],
              "path": [
                "sales-invoices",
                "{{INVOICE_ID}}",
                "qr-code"
              ]
            },
            "description": "الحصول على QR Code للفاتورة.\n\n**ملاحظة:** يجب أن تكون الفاتورة قد أُرسلت بنجاح إلى ZATCA"
          },
          "response": []
        },
        {
          "name": "Batch Send Invoices - إرسال دفعة فواتير",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Accept",
                "value": "application/json",
                "type": "text"
              },
              {
                "key": "Content-Type",
                "value": "application/json",
                "type": "text"
              },
              {
                "key": "Authorization",
                "value": "Bearer {{TOKEN}}",
                "type": "text"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n    \"invoice_ids\": [1, 2, 3]\n}"
            },
            "url": {
              "raw": "{{BASE_URL}}/sales-invoices/batch-send-to-zatca",
              "host": [
                "{{BASE_URL}}"
              ],
              "path": [
                "sales-invoices",
                "batch-send-to-zatca"
              ]
            },
            "description": "إرسال مجموعة فواتير دفعة واحدة إلى ZATCA.\n\n**الحقول:**\n- `invoice_ids`: مصفوفة من IDs الفواتير المراد إرسالها\n\n**النتيجة:**\n- عدد الفواتير الناجحة\n- عدد الفواتير الفاشلة\n- تفاصيل كل فاتورة"
          },
          "response": []
        }
      ]
    },
    {
      "name": "ZATCA Preparation - تحضير البيانات",
      "item": [
        {
          "name": "Get Preparation Data - بيانات التحضير",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Accept",
                "value": "application/json",
                "type": "text"
              },
              {
                "key": "Authorization",
                "value": "Bearer {{TOKEN}}",
                "type": "text"
              }
            ],
            "url": {
              "raw": "{{BASE_URL}}/zatca-preparation",
              "host": [
                "{{BASE_URL}}"
              ],
              "path": [
                "zatca-preparation"
              ]
            },
            "description": "الحصول على بيانات التحضير لإرسال الفواتير إلى ZATCA.\n\nيعرض الفواتير الجاهزة للإرسال ومتطلباتها."
          },
          "response": []
        },
        {
          "name": "Get Invoice ZATCA Information - معلومات الفاتورة",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Accept",
                "value": "application/json",
                "type": "text"
              },
              {
                "key": "Authorization",
                "value": "Bearer {{TOKEN}}",
                "type": "text"
              }
            ],
            "url": {
              "raw": "{{BASE_URL}}/zatca-preparation/{{INVOICE_ID}}",
              "host": [
                "{{BASE_URL}}"
              ],
              "path": [
                "zatca-preparation",
                "{{INVOICE_ID}}"
              ]
            },
            "description": "الحصول على معلومات ZATCA الخاصة بفاتورة معينة.\n\nيعرض:\n- بيانات الفاتورة المطلوبة\n- الحقول الناقصة\n- جاهزية الفاتورة للإرسال"
          },
          "response": []
        }
      ]
    }
  ],
  "variable": [
    {
      "key": "BASE_URL",
      "value": "http://127.0.0.1:8000/api/v1",
      "type": "string"
    },
    {
      "key": "TOKEN",
      "value": "",
      "type": "string",
      "description": "Bearer token for authentication"
    },
    {
      "key": "INVOICE_ID",
      "value": "1",
      "type": "string",
      "description": "Sales Invoice ID for testing"
    },
    {
      "key": "OTP",
      "value": "123456",
      "type": "string",
      "description": "OTP from ZATCA Portal (6 digits)"
    }
  ]
}