مجموعة Postman لواجهة الفوترة

مجموعة Postman هي أسرع طريقة لاختبار التكامل مع منصة فاتورة قبل كتابة سطر واحد من كود الإنتاج. تتيح لك إرسال طلبات المصادقة والمصادقة (Clearance) والإبلاغ (Reporting) يدويًا، وقراءة استجابات هيئة الزكاة والضريبة والجمارك (ZATCA) لحظيًا، وتثبيت بيئة المتغيرات مرة واحدة لإعادة استخدامها في كل طلب. هذا الدليل العملي يشرح بناء مجموعة Postman كاملة لواجهة الفوترة من الصفر: من إنشاء البيئة وتعريف عنوان الأساس ومعرف الختم المشفر (CSID)، مرورًا ببناء ترويسة المصادقة، وصولًا إلى تصدير المجموعة ومشاركتها مع فريقك.

يفترض هذا الدليل أنك أنهيت الخطوات السابقة في مركز المطوّرين: حصلت على معرف الختم المشفر للامتثال (Compliance CSID)، وفهمت آلية المصادقة، وتعرّفت على نقاط نهاية الواجهة. إن لم تكن قد فعلت، راجع دليل المصادقة (Authentication) ودليل نقاط نهاية API (Endpoints) أولًا. كل ما يلي يُختبر على بيئة المحاكاة (Sandbox) التابعة للهيئة، لا على بيئة الإنتاج.

ما هي مجموعة Postman ولماذا تحتاجها مع واجهة الفوترة

Postman أداة لاختبار واجهات برمجة التطبيقات (APIs) دون كتابة كود. تُرسل بها طلبات HTTP إلى أي خادم، وتقرأ الاستجابة بصيغة منسّقة، وتحتفظ بالطلبات منظّمة في «مجموعات» (Collections). المجموعة ببساطة مجلد يحوي طلباتك المتكررة مرتّبة، مع متغيرات بيئة مشتركة بينها.

تكامل منصة فاتورة في المرحلة الثانية يتطلب سلسلة طلبات متتابعة: طلب امتثال لمعرف الختم، ثم طلبات مصادقة لفواتير B2B، وطلبات إبلاغ لفواتير B2C. كل طلب يحمل ترويسات دقيقة ونصًا بصيغة UBL 2.1. تجربة هذه الطلبات يدويًا في الكود بطيئة ومعرّضة للخطأ. مع Postman تبني الطلب مرة، وتعدّل متغيرًا واحدًا، وتعيد الإرسال فورًا.

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

هناك سبب عملي ثالث يجعل Postman لا غنى عنها في مشاريع الفوترة الإلكترونية. واجهة الهيئة صارمة في التحقق، وأي انحراف بسيط في صيغة المستند أو ترتيب الحقول يعيد رفضًا مفصّلًا. حين تختبر يدويًا، ترى رسالة الخطأ كاملةً وتصحّح المستند خطوةً بخطوة قبل أن تكتب منطق التوليد في تطبيقك. هذا يوفّر ساعات من تتبّع الأخطاء داخل الكود، لأنك تفصل مشكلة بناء الفاتورة عن مشكلة إرسالها.

تذكّر أن كل اختبار في هذا الدليل يجري على بيئة المحاكاة المخصصة للمطوّرين. لا ترسل فواتير حقيقية إلى بيئة الإنتاج أثناء التعلّم، لأن الفاتورة المُصادق عليها في الإنتاج تصبح مستندًا ضريبيًا ملزمًا. بيئة المحاكاة آمنة تمامًا للتجربة، وتعيد استجابات مطابقة لسلوك الإنتاج دون أي أثر ضريبي.

الخطوة الأولى: إنشاء بيئة Postman ومتغيراتها

تثبيت Postman وإنشاء البيئة

نزّل تطبيق Postman لسطح المكتب أو استخدم نسخة الويب. بعد فتحه، أنشئ بيئة جديدة (Environment) من القائمة الجانبية. البيئة وعاء يحفظ القيم المتغيرة كي لا تكتبها في كل طلب. سمّ البيئة باسم واضح مثل Fatoora Sandbox لتمييزها عن بيئة الإنتاج لاحقًا.

تعريف المتغيرات الأساسية

أضف المتغيرات التالية داخل البيئة. اترك عمود «القيمة الأولية» (Initial Value) فارغًا للقيم السرّية، واملأ «القيمة الحالية» (Current Value) فقط، لأن القيمة الأولية تُصدَّر مع المجموعة وقد تتسرّب القيم السرّية.

baseUrl        = https://gw-fatoora.zatca.gov.sa/e-invoicing/developer-portal
acceptVersion  = V2
csid           = (معرف الختم المشفر للامتثال بصيغة Base64)
csidSecret     = (السر المقترن بالمعرف)
authHeader     = (يُحسب لاحقًا بصيغة Basic Base64)
otp            = (كلمة المرور لمرة واحدة من بوابة فاتورة)

عنوان الأساس (baseUrl) يشير إلى بيئة المحاكاة التابعة للهيئة. عند الانتقال للإنتاج، تغيّر هذه القيمة فقط دون لمس بقية الطلبات. القيمة V2 في متغير acceptVersion تُستخدم في ترويسة Accept-Version التي تطلبها الهيئة في كل نداء على واجهة المرحلة الثانية.

معرف الختم المشفر للامتثال (Compliance CSID) والسر المقترن به تحصل عليهما من خطوة الامتثال: ترسل طلب توقيع شهادة (CSR) عبر بوابة فاتورة مع كلمة مرور لمرة واحدة (OTP)، فتعيد لك الهيئة المعرف وسرّه. قيود يدير هذا المعرف تلقائيًا داخل المنصة، لكنك في مرحلة الاختبار اليدوي تضعه في Postman بنفسك لتفحص الاستجابات مباشرة.

لماذا نفصل القيمة الأولية عن القيمة الحالية

Postman يميّز بين عمودين لكل متغير: القيمة الأولية والقيمة الحالية. القيمة الأولية تُخزَّن داخل ملف البيئة وتُرافقه عند التصدير أو المزامنة السحابية، بينما القيمة الحالية تبقى على جهازك فقط. القاعدة الذهبية أن تضع كل قيمة سرّية في القيمة الحالية وحدها، وتترك الأولية فارغة. بهذا تشارك بنية البيئة مع فريقك دون أن تتسرّب أسرارك.

التطبيق العملي: عند إنشاء متغير csidSecret، اكتب السر في خانة Current Value فقط. حين تصدّر البيئة لاحقًا لزميل، يستلم الهيكل كاملًا بأسماء المتغيرات لكن دون السر، فيملأ سرّه الخاص محليًا. هذه عادة أمنية أساسية في كل مشروع يتعامل مع بيانات اعتماد، وتزداد أهميةً مع معرّفات الهيئة لأنها تُمكّن من توقيع فواتير ضريبية باسم المنشأة.

إدارة بيئتين منفصلتين: المحاكاة والإنتاج

أنشئ بيئتين مستقلتين منذ البداية: واحدة للمحاكاة وأخرى للإنتاج. تحملان أسماء المتغيرات نفسها لكن بقيم مختلفة، أبرزها baseUrl ومعرف الختم. هذا الفصل يمنع أخطر خطأ في مشاريع الفوترة، وهو إرسال فاتورة اختبارية إلى الإنتاج أو العكس. للتبديل بين البيئتين يكفي اختيارها من القائمة العلوية في Postman دون لمس أي طلب.

عنوان أساس المحاكاة يختلف عن عنوان الإنتاج. معرف الختم في المحاكاة هو معرف الامتثال، وفي الإنتاج هو معرف الإنتاج الذي تحصل عليه بعد اجتياز فحوص الامتثال. حافظ على هذا التمييز صريحًا في تسمية البيئتين كي لا تخلط بينهما أثناء العمل السريع.

الخطوة الثانية: بناء ترويسة المصادقة (Authorization Header)

تستخدم واجهة الفوترة مصادقة من نوع Basic فوق طبقة OAuth 2.0. الترويسة تتكوّن من معرف الختم المشفر وسرّه، مفصولين بنقطتين، ثم مُرمّزين بصيغة Base64. الصيغة كالتالي:

Authorization: Basic base64(csid:csidSecret)

بدل حساب الترميز يدويًا في كل مرة، أضف سكربت ما قبل الطلب (Pre-request Script) على مستوى المجموعة. يقرأ السكربت متغيري csid وcsidSecret، يدمجهما، يرمّزهما، ويخزّن الناتج في متغير authHeader الذي تستدعيه كل الطلبات.

// Pre-request Script على مستوى المجموعة
const csid = pm.environment.get("csid");
const secret = pm.environment.get("csidSecret");
const token = Buffer.from(csid + ":" + secret).toString("base64");
pm.environment.set("authHeader", "Basic " + token);

بهذا تبني الترويسة مرة واحدة آليًا. أي طلب داخل المجموعة يضيف في تبويب الترويسات (Headers) السطر التالي، فيُستبدل المتغير بقيمته المحسوبة لحظة الإرسال:

Authorization: {{authHeader}}
Accept-Version: {{acceptVersion}}
Content-Type: application/json
Accept-Language: ar

ترويسة Accept-Version إلزامية وتحدّد إصدار الواجهة الذي تخاطبه. ترويسة Content-Type تُعلم الخادم أن نص الطلب بصيغة JSON يحوي حِمل UBL المُرمّز. إغفال أي ترويسة منها يعيد عادةً استجابة 400 أو 401، لذا ثبّتها على مستوى المجموعة لتُورَّث في كل طلب.

السبب وراء وضع السكربت والترويسات على مستوى المجموعة لا على كل طلب منفردًا هو الوراثة. Postman يطبّق إعدادات المجموعة على كل طلب بداخلها ما لم تتجاوزها صراحةً. هذا يعني أنك تضبط المصادقة مرة واحدة، فيستفيد منها كل طلب جديد تضيفه لاحقًا دون إعادة الإعداد. عند تغيير معرف الختم أو سرّه، تعدّل قيمة المتغير في البيئة فقط، ويُعاد حساب الترويسة آليًا في الطلب التالي.

طبيعة الترميز بـ Base64 هنا مجرد تشفير نقل لا تشفير سرّية. الغرض منه نقل المعرف والسر بصيغة نصية آمنة في ترويسة HTTP، لا إخفاؤهما. لذلك تبقى الحماية الحقيقية في عدم تسريب القيم الأصلية، لا في الترميز نفسه. أي طرف يملك السلسلة المُرمّزة يستطيع فكّها بسهولة، وهذا سبب إضافي للحرص على بقاء بيانات الاعتماد محليةً وغير مشتركة.

الخطوة الثالثة: إرسال طلب الامتثال (Compliance Request)

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

أنشئ طلبًا جديدًا في المجموعة بطريقة POST على المسار التالي:

POST {{baseUrl}}/compliance/invoices

Headers:
  Authorization: {{authHeader}}
  Accept-Version: {{acceptVersion}}
  Content-Type: application/json
  Accept-Language: ar

Body (raw, JSON):
{
  "invoiceHash": "<SHA-256 hash للفاتورة المُقَنّنة>",
  "uuid": "<معرّف الفاتورة UUID>",
  "invoice": "<حِمل XML بصيغة UBL 2.1 مُرمّز Base64>"
}

الحقول الثلاثة إلزامية. الحقل invoiceHash هو تجزئة SHA-256 للفاتورة بعد تقنينها (Canonicalization)، وuuid معرّف فريد لكل فاتورة، وinvoice هو مستند UBL 2.1 كاملًا مُرمّزًا بـ Base64. استجابة الامتثال الناجحة تعيد الحالة CLEARED أو REPORTED حسب نوع الفاتورة، إضافةً إلى أي ملاحظات تحذيرية (warnings) تستحق المراجعة.

الخطوة الرابعة: طلبات المصادقة والإبلاغ (Clearance & Reporting)

المصادقة لفواتير B2B

الفاتورة الضريبية القياسية بين المنشآت (B2B) تخضع للمصادقة الفورية: تُرسلها إلى الهيئة أولًا، فتعيد لك نسخة موقّعة بختمها، وبعدها فقط يحقّ لك تسليمها للمشتري. في Postman أنشئ طلب POST على مسار المصادقة:

POST {{baseUrl}}/invoices/clearance/single

Headers:
  Authorization: {{authHeader}}
  Accept-Version: {{acceptVersion}}
  Clearance-Status: 1
  Content-Type: application/json

Body (raw, JSON):
{
  "invoiceHash": "<hash>",
  "uuid": "<uuid>",
  "invoice": "<UBL Base64>"
}

ترويسة Clearance-Status بقيمة 1 تطلب من الهيئة إجراء المصادقة الكاملة وإعادة الفاتورة المختومة. الاستجابة الناجحة تحمل الحالة CLEARED مع نسخة XML الموقّعة في الحقل clearedInvoice.

الإبلاغ لفواتير B2C

الفاتورة الضريبية المبسّطة للمستهلك (B2C) لا تحتاج مصادقة مسبقة. تصدرها وتسلّمها للمشتري فورًا، ثم تبلغ بها الهيئة خلال أربع وعشرين ساعة. المسار مختلف:

POST {{baseUrl}}/invoices/reporting/single

Headers:
  Authorization: {{authHeader}}
  Accept-Version: {{acceptVersion}}
  Clearance-Status: 0
  Content-Type: application/json

Body (raw, JSON):
{
  "invoiceHash": "<hash>",
  "uuid": "<uuid>",
  "invoice": "<UBL Base64>"
}

الفرق الجوهري أن مسار الإبلاغ يعيد الحالة REPORTED دون فاتورة مختومة، لأن الفاتورة المبسّطة سُلّمت للمشتري سلفًا. هذا التمييز بين المصادقة والإبلاغ هو جوهر تكامل المرحلة الثانية، وتجربته في Postman تكشف فورًا إن كنت تستدعي المسار الصحيح لكل نوع فاتورة.

الخطوة الخامسة: قراءة الاستجابة وتفسير الأخطاء

Postman يعرض الاستجابة بثلاثة أجزاء: رمز الحالة (Status Code)، والترويسات، والنص. رمز 200 يعني نجاح الطلب، و202 يعني قبولًا مع تحذيرات، و400 يشير إلى نص طلب غير صالح، و401 إلى خلل في المصادقة. ركّز على حقل validationResults في النص، فهو يفصّل التحذيرات والأخطاء التي رصدتها الهيئة.

{
  "validationResults": {
    "status": "WARNING",
    "warningMessages": [
      { "code": "BR-KSA-...", "message": "وصف التحذير" }
    ],
    "errorMessages": []
  },
  "clearanceStatus": "CLEARED",
  "clearedInvoice": "<XML موقّع Base64>"
}

التحذيرات لا تمنع المصادقة لكنها تستحق المعالجة قبل الإنتاج. الأخطاء (errorMessages) تمنع القبول، وعليك تصحيح الفاتورة وإعادة الإرسال. لاحظ أن الهيئة هي الجهة التي تتحقق من الفاتورة وتجيز قبولها، لا الأداة التي تصدرها. قيود يرسل ما تصدره أنت، والهيئة تبقى المرجع الذي يقبل أو يرفض.

عند ظهور رمز 401 راجع متغير authHeader: تأكد من تطابق المعرف وسرّه، ومن أن سكربت ما قبل الطلب يعمل، ومن صحة عنوان الأساس. أكثر الأخطاء شيوعًا في الاختبار اليدوي خلطٌ بين معرف الامتثال ومعرف الإنتاج، أو استخدام عنوان بيئة الإنتاج مع معرف محاكاة.

جدول الأخطاء الشائعة وحلولها

تتكرّر بضعة أنماط من الأخطاء أثناء الاختبار اليدوي. معرفتها مسبقًا تختصر زمن التشخيص:

رمز 400 مع رسالة عن صيغة غير صالحة يعني غالبًا أن حِمل UBL غير مُرمّز بـ Base64 بشكل صحيح، أو أن قيمة invoiceHash لا تطابق المستند المرسل. أعد حساب التجزئة بعد التقنين مباشرةً، وتحقّق من أنك ترمّز المستند نفسه الذي حسبت تجزئته منه.

رمز 401 يشير دائمًا إلى المصادقة: معرف خاطئ، أو سر خاطئ، أو ترويسة Authorization لم تُحقن لأن سكربت ما قبل الطلب لم يُنفّذ. افتح وحدة تحكّم Postman (Console) وتحقّق من قيمة authHeader المحسوبة فعليًا قبل الإرسال.

رمز 403 يعني أن المعرف صحيح لكنه لا يملك صلاحية على المسار المطلوب، كأن تستخدم معرف امتثال لاستدعاء مسار إنتاج. رمز 500 نادر ويأتي من جانب الخادم، فأعد المحاولة بعد فترة قصيرة. أما غياب ترويسة Accept-Version فيعيد رفضًا فوريًا، لذا ثبّتها على مستوى المجموعة كما أوصينا.

الطلبات المجمّعة (Batch) لاختبار الحجم

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

POST {{baseUrl}}/invoices/clearance
POST {{baseUrl}}/invoices/reporting

Body (raw, JSON):
{
  "invoices": [
    { "invoiceHash": "...", "uuid": "...", "invoice": "..." },
    { "invoiceHash": "...", "uuid": "...", "invoice": "..." }
  ]
}

اختبار الطلبات المجمّعة في Postman يكشف كيف تتعامل الهيئة مع رفض عنصر واحد ضمن دفعة: هل تقبل الباقي أم ترفض الدفعة كاملة. فهم هذا السلوك مبكرًا يوفّر عليك مفاجآت في الإنتاج حين ترسل دفعات كبيرة.

أتمتة التحقق عبر تبويب الاختبارات (Tests)

Postman يتيح كتابة تأكيدات (Assertions) في تبويب الاختبارات لكل طلب، فتتحقق آليًا من الاستجابة بدل فحصها بالعين. أضف سكربتًا يتأكد أن رمز الحالة 200 وأن حقل الحالة يحمل القيمة المتوقّعة:

// Tests tab
pm.test("الاستجابة 200", () => {
  pm.response.to.have.status(200);
});
pm.test("الفاتورة مُصادق عليها", () => {
  const body = pm.response.json();
  pm.expect(body.clearanceStatus).to.eql("CLEARED");
});

هذه التأكيدات تتحوّل إلى شبكة أمان حين تشغّل المجموعة كاملة بـ Newman. أي طلب يفشل تأكيده يظهر فورًا في تقرير التشغيل، فتعرف أن سلوك الواجهة تغيّر قبل أن يكتشفه عملاؤك. ابنِ تأكيدًا واحدًا على الأقل لكل طلب جوهري في مجموعتك.

تحضير حِمل UBL قبل الإرسال

نص الطلب يحوي مستند UBL 2.1 مُرمّزًا بـ Base64، لكن قبل الترميز يجب تقنين المستند (Canonicalization) لتوحيد صيغته، ثم حساب تجزئته SHA-256 التي تضعها في حقل invoiceHash. أي اختلاف بين المستند المُرمّز وتجزئته يعيد رفضًا فوريًا. لذلك جهّز عيّنة مستند صحيحة واحدة، ووثّقها داخل المجموعة كمثال مرجعي يقيس عليه فريقك بقية الفواتير.

الخطوة السادسة: تنظيم المجموعة في مجلدات

مع تكاثر الطلبات، نظّم مجموعتك في مجلدات منطقية تسهّل التنقّل والمشاركة. بنية مقترحة:

Fatoora API Collection
├── 1. Onboarding
│   └── Compliance Request (POST /compliance/invoices)
├── 2. Clearance (B2B)
│   ├── Single Clearance
│   └── Batch Clearance
├── 3. Reporting (B2C)
│   ├── Single Reporting
│   └── Batch Reporting
└── 4. Utilities
    └── Renew CSID

كل مجلد يرث الترويسات والسكربتات من مستوى المجموعة، فلا تكرّر إعداد المصادقة. هذا الترتيب يحاكي مسار التكامل الفعلي: الامتثال أولًا، ثم المصادقة والإبلاغ في الإنتاج، مع طلبات مساعدة لتجديد المعرف عند انتهاء صلاحيته.

الخطوة السابعة: تصدير المجموعة ومشاركتها مع الفريق

بعد ضبط المجموعة، صدّرها لمشاركتها. من قائمة المجموعة اختر «تصدير» (Export)، ثم صيغة Collection v2.1. تحصل على ملف JSON يحوي كل الطلبات والمجلدات والسكربتات، لكن دون قيم البيئة السرّية إن تركت «القيمة الأولية» فارغة كما أوصينا.

// مقتطف من ملف المجموعة المُصدَّر (Collection v2.1)
{
  "info": {
    "name": "Fatoora API Collection",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [ /* المجلدات والطلبات */ ],
  "auth": { "type": "basic" }
}

شارك ملف المجموعة عبر مستودع الكود أو رابط مشاركة Postman، وصدّر البيئة في ملف منفصل يملأ كل مطوّر قيمه السرّية فيه محليًا. بهذا يستورد أي عضو جديد المجموعة، ويضبط معرف ختمه الخاص، ويبدأ الاختبار فورًا دون أن تتسرّب بيانات اعتماد أحد.

للاختبار الآلي المتكرّر، استعن بأداة سطر الأوامر Newman التي تشغّل المجموعة كاملة من الطرفية، فتدمجها في خط التكامل المستمر وتتحقق من سلامة التكامل عند كل تحديث:

newman run fatoora-collection.json -e fatoora-sandbox.json

تجديد معرف الختم المشفر

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

اختبار مسار التجديد في Postman مهم لأنه يحاكي حالة حرجة في الإنتاج: انتهاء صلاحية الشهادة فجأة. حين تجرّبه على بيئة المحاكاة، تتأكد أن منطق التجديد يعمل قبل أن تحتاجه فعليًا. في قيود يجري هذا التجديد آليًا في الخلفية، فلا تتعرّض المنشأة لتوقف غير متوقّع في إصدار الفواتير.

راقب كذلك ترويسات الاستجابة التي تحمل أحيانًا تنبيهًا بقرب انتهاء الصلاحية. رصد هذا التنبيه مبكرًا يتيح لك جدولة التجديد دون انقطاع. هذه التفاصيل الصغيرة هي ما يفرّق بين تكامل يصمد في الإنتاج وآخر يتعطّل في أسوأ وقت.

ممارسات أمنية أثناء الاختبار

التعامل مع معرفات الهيئة يفرض انضباطًا أمنيًا. السر المقترن بالمعرف يعادل مفتاحًا يوقّع فواتير ضريبية باسم المنشأة، وتسرّبه خطر حقيقي. التزم بثلاث قواعد أساسية أثناء الاختبار.

أولًا، لا تضع أي سر في القيمة الأولية للمتغير، واتركه في القيمة الحالية فقط كما شرحنا. ثانيًا، لا تدرج بيانات الاعتماد في ملفات الكود ولا في سجلّ المستودع، بل اقرأها من ملف بيئة محلي غير متتبَّع. ثالثًا، استخدم معرفات بيئة المحاكاة للاختبار دائمًا، واحفظ معرف الإنتاج بعيدًا عن أدوات التجربة اليومية.

عند مشاركة المجموعة عبر مساحة عمل Postman السحابية، تذكّر أن المساحة المشتركة قد تزامن القيم الأولية. لذا تحقّق قبل المشاركة من خلو الحقول السرّية، أو شارك ملف المجموعة فقط دون ملف البيئة. هذه العادة تحمي منشأتك من أكثر تسريبات بيانات الاعتماد شيوعًا.

أسئلة شائعة عن مجموعة Postman لواجهة الفوترة

هل أحتاج مجموعة Postman إذا كنت أستخدم قيود؟ لا للامتثال نفسه. قيود يتولّى التكامل مع منصة فاتورة كاملًا. لكن إن كنت مطوّرًا تريد فهم سلوك الواجهة أو عزل مشكلة، فالمجموعة أداة تشخيص ممتازة.

ما الفرق بين معرف الامتثال ومعرف الإنتاج؟ معرف الامتثال يُستخدم على بيئة المحاكاة لاجتياز فحوص الهيئة، ومعرف الإنتاج يوقّع الفواتير الحية بعد اجتياز تلك الفحوص. لكل بيئة معرفها الخاص.

لماذا أحصل على رمز 401 رغم صحة المعرف؟ غالبًا لأن سكربت ما قبل الطلب لم يبنِ ترويسة Authorization، أو لأن السر غير مطابق. افتح وحدة التحكّم في Postman وتحقّق من قيمة authHeader فعليًا.

هل تُحفظ الفواتير الاختبارية في سجلّي الضريبي؟ لا. فواتير بيئة المحاكاة لا أثر ضريبي لها إطلاقًا. الأثر الضريبي يبدأ فقط مع فواتير الإنتاج المُصادق عليها بمعرف الإنتاج.

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

كيف يختصر قيود هذه الخطوات

كل ما سبق ضروري لمن يبني تكاملًا مباشرًا مع منصة فاتورة. قيود منصة محاسبية جاهزة للمرحلة الثانية تتولّى هذه الطبقة بالكامل: تدير معرف الختم المشفر تلقائيًا، وتبني ترويسات المصادقة، وترسل فواتير B2B للمصادقة وفواتير B2C للإبلاغ، وتخزّن سلسلة تجزئة الفواتير للتحقق من الامتثال. أنت تصدر الفاتورة من واجهة قيود، والمنصة تتولّى الحوار مع الهيئة خلف الكواليس.

تبقى مجموعة Postman أداة قيّمة لفريق المطوّرين لفهم التكامل وعزل المشكلات والتحقق من سلوك الواجهة. أما المنشأة التي تريد امتثالًا فوريًا دون بناء تكامل، فتجده جاهزًا في قيود من اليوم الأول.

باختصار، مجموعة Postman تمنحك رؤية مباشرة لكل خطوة في حوار الفوترة الإلكترونية مع الهيئة: من تثبيت المتغيرات وبناء الترويسة، إلى إرسال طلبات الامتثال والمصادقة والإبلاغ، وقراءة الاستجابات وتصدير المجموعة لفريقك. أتقن هذه الأداة لتفهم التكامل عمقًا، ثم دع قيود يتولّى تشغيله في الإنتاج نيابةً عنك بثبات وأمان.