توثيق ماثل API

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

البداية السريعة

1. خذ مفتاح تجربة مجاناً. يوصلك على الإيميل وتلقاه في بوابة العميل.
2. أرسل أول فاتورة على الـ sandbox بدون شهادة: لا ترسل seller ولا csid، وماثل يوقّعها ويرسلها لبوابة المطورين بالهيئة باسم منشأة تجريبية حقّتنا. والرد هو رد الهيئة الحقيقي.

curl https://matheel.app/api/v1/invoices \
  -H "Authorization: Bearer $MATHEEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "environment": "sandbox",
        "invoice": { "type": "simplified", "counter": 1,
                     "uuid": "8d487816-70b8-4ade-a618-9d620b73814a", "number": "INV-1",
                     "line_items": [{ "name": "قهوة", "quantity": 2, "price": "50.00" }],
                     "subtotal": "100.00", "vat_amount": "15.00", "total": "115.00" } }'

إذا رجع 200 والحالة reported أو cleared، الربط شغّال. احفظ invoice_hash، لأنه بيصير previous_invoice_hash في الفاتورة اللي بعدها.

التجربة بدون شهادة لها حد ١٠٠ فاتورة بالساعة لكل مفتاح. ولما تجهز، سوّ شهادتك (الخطوات تحت) وأرسلها في csid مع بيانات منشأتك.

بالذكاء الاصطناعي

انسخ البرومبت والصقه في Claude أو Cursor أو ChatGPT، وهو يكتب الربط في مشروعك. والأدوات اللي تقرأ التوثيق بنفسها، عطها /llms.txt.

Integrate the Matheel API (https://matheel.app) into my app so it files Saudi ZATCA Phase 2 e-invoices.
Reference (read it first): https://matheel.app/llms.txt
Ask me which language/framework I use and where invoices are created, then add one small client module.
Keep the invoice chain per device (counter + last invoice_hash), store invoice_xml and qr on 200,
keep the same counter on 422/429/503, and start with "environment": "sandbox" without seller/csid.

المصادقة

كل طلب لازم يكون فيه مفتاحك في الهيدر:

Authorization: Bearer <your Matheel license key>

المفتاح يطلع لك لما تشترك، ومن نفس البوابة تلغي أو تغيّر الباقة. المفتاح الغلط أو الملغي يرجّع 401.

البيئات

الحقل environment مطلوب، ويحدد وين تستقبل الهيئة الفاتورة. والشهادة لازم تكون من نفس البيئة.

الطلب

POST /api/v1/invoices بجسم JSON فيه: environment وseller وcsid وinvoice، واختيارياً mode.

seller · المنشأة البائعة

csid · الشهادة

الثلاثة تُستخدم للتوقيع والإرسال في نفس الطلب بس، وما نحتفظ فيها.

invoice · الفاتورة

mode · طريقة الإرسال

اختياري. إذا ما أرسلته، ماثل يختار حسب النوع: clear للضريبية وreport للمبسّطة.

الرد

{
  "status": "cleared",            // or "reported"
  "zatca_uuid": "…",
  "invoice_hash": "NWZlY2Vi…",     // send it as previous_invoice_hash next time
  "previous_invoice_hash": "…",
  "qr": "AQ1TaGFy…",               // TLV, base64: print it on the invoice
  "invoice_xml": "PD94bWwg…",      // base64 legal XML: archive it, hand it to the buyer
  "warnings": [],
  "errors": []
}

في الـ clearance، invoice_xml هو المستند المختوم من الهيئة. وفي الـ reporting هو الـ XML الموقّع اللي انرسل. وفي الحالتين هذا المستند اللي تحفظه.

سلسلة الفواتير

الهيئة تربط كل فاتورة باللي قبلها: العدّاد (ICV) لازم يزيد واحد، والهاش اللي قبله (PIH) لازم يطابق. ماثل ما يمسك السلسلة لأنه ما يحتفظ بشي، فأنت اللي تمسكها:

• احفظ invoice_hash بعد كل فاتورة انقبلت.
• إذا انرفضت فاتورة، لا تستهلك رقم عدّاد ولا تغيّر الهاش. صلّحها وأرسلها بنفس العدّاد.
• كل جهاز أو فرع (EGS) له سلسلة لحاله وشهادة لحاله.

الأخطاء

شهادة الـ CSID

ماثل يسوي لك الخطوات كلها بطلب واحد على POST /api/v1/onboarding: ترسل بيانات منشأتك، ويرجع لك csid جاهز تحطه في طلب الفاتورة. على الـ sandbox ما تحتاج OTP، وعلى المحاكاة والإنتاج ترسل الـ OTP من بوابة «فاتورة».

curl https://matheel.app/api/v1/onboarding \
  -H "Authorization: Bearer $MATHEEL_KEY" -H "Content-Type: application/json" \
  -d '{ "environment": "sandbox",
        "seller": { "vat_number": "399999999900003", "legal_name_ar": "منشأتك", "legal_name_en": "Your Co",
                    "address": { "street": "King Fahd Rd", "building_number": "1234", "district": "Al Olaya",
                                 "city": "Riyadh", "postal_code": "12211" } } }'
# → { "csid": { "private_key": "…", "binary_security_token": "…", "secret": "…" }, "compliance_checks": 6 }

الشهادة والمفتاح يرجعون لك وما نحتفظ فيهم. احفظهم عندك بأمان، وكل جهاز أو فرع له شهادة لحاله. الحد ١٠ تسجيلات بالساعة لكل مفتاح.

وهذي الخطوات اللي يسويها ماثل (لو تبي تسويها بنفسك):

1. سوّ CSR بمفتاح secp256k1 فيه بيانات المنشأة.
2. صاحب المنشأة يطلّع OTP من حسابه في بوابة «فاتورة».
3. بالـ CSR والـ OTP تاخذ شهادة الامتثال، وبعدها تعدّي فحوصات الامتثال الستة.
4. بعدها تاخذ شهادة الإنتاج، وهي اللي ترسلها في csid.

على بيئة المطورين الـ OTP ثابت ومنشور في التوثيق الرسمي، فتقدر تسوي الخطوات كلها اليوم. وإذا تبي مساعدة في أول ربط، راسلنا على hello@matheel.app.

الاستهلاك والحدود

• كل فاتورة تنقبل على production تنحسب فاتورة وحدة من باقتك.
• الفاتورة اللي ترسلها مرتين بنفس الـ uuid تنحسب مرة وحدة.
• الفواتير المرفوضة وفواتير sandbox وsimulation ما تنحسب.
• لما تخلص الباقة في الشهر، طلبات الإنتاج ترجّع 402 لين تكبّر الباقة أو يبدأ شهر جديد. وبيئة المطورين والمحاكاة تظل شغّالة.