zatca-qr 1.0.1 → 1.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +6 -0
- package/README.en.md +6 -0
- package/README.md +35 -0
- package/package.json +3 -3
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,11 @@
|
|
|
1
1
|
# سجل التغييرات
|
|
2
2
|
|
|
3
|
+
## 1.0.2: 2026-09-30
|
|
4
|
+
|
|
5
|
+
- جدول كامل لرموز الأخطاء والتنبيهات في الواجهة، مع معنى كل رمز وما تفعله عند ظهوره.
|
|
6
|
+
- اختبار جديد يمنع اختلاف الجدول عن الكود: أي رمز يُضاف بلا توثيق يُسقط الاختبارات.
|
|
7
|
+
- الملف منشور عبر Trusted Publishing من GitHub Actions، ومعه شهادة بناء موقّعة.
|
|
8
|
+
|
|
3
9
|
## 1.0.1: 2026-09-30
|
|
4
10
|
|
|
5
11
|
تحسين في الواجهة فقط، بلا تغيير في الكود.
|
package/README.en.md
CHANGED
|
@@ -93,6 +93,12 @@ node examples/node.mjs # CLI example, nothing to install
|
|
|
93
93
|
node --test # 38 tests, zero dependencies
|
|
94
94
|
```
|
|
95
95
|
|
|
96
|
+
## Errors and warnings
|
|
97
|
+
|
|
98
|
+
Every error and warning carries a stable `code` field, for example `FIELD_TOO_LONG`,
|
|
99
|
+
`VAT_NUMBER_FORMAT` or `PHASE2_INCOMPLETE`, so you can branch on it instead of matching message
|
|
100
|
+
text. The full table lives in the Arabic README: [README.md](README.md).
|
|
101
|
+
|
|
96
102
|
## References
|
|
97
103
|
|
|
98
104
|
- [ZATCA detailed technical guideline (PDF)](https://zatca.gov.sa/en/E-Invoicing/Introduction/Guidelines/Documents/E-invoicing-Detailed-Technical-Guideline.pdf)
|
package/README.md
CHANGED
|
@@ -153,6 +153,41 @@ const payload = encodeZatcaTlv({
|
|
|
153
153
|
|
|
154
154
|
العملة في هذا الحقل ريال سعودي دايم، حتى لو الفاتورة بعملة ثانية في ملف XML.
|
|
155
155
|
|
|
156
|
+
## رموز الأخطاء والتنبيهات
|
|
157
|
+
|
|
158
|
+
كل خطأ وتنبيه له رمز ثابت في `code`، فتقدر تتعامل معه برمجياً بدل ما تقارن نص الرسالة.
|
|
159
|
+
الأخطاء توقف `validateZatcaInvoice` وترجع `valid: false`، والتنبيهات ترجع مع `valid: true`.
|
|
160
|
+
|
|
161
|
+
| الرمز | النوع | متى يظهر | وش تسوي |
|
|
162
|
+
| --- | --- | --- | --- |
|
|
163
|
+
| `MISSING_FIELD` | خطأ | حقل إلزامي فاضي أو غير موجود | مرّر الحقل الخمسة كاملة |
|
|
164
|
+
| `INVALID_FIELD` | خطأ | نوع غير مدعوم، أو رقم في حقل نصي | مرّر نصاً، والمبالغ فقط تقبل رقماً |
|
|
165
|
+
| `FIELD_TOO_LONG` | خطأ | الحقل أكبر من 255 بايتاً | قصّر النص، وتذكّر الحرف العربي بايتان |
|
|
166
|
+
| `VAT_NUMBER_FORMAT` | خطأ | الرقم الضريبي مو 15 رقماً يبدأ وينتهي بـ3 | صحّح الرقم |
|
|
167
|
+
| `TIMESTAMP_FORMAT` | خطأ | وقت بلا منطقة زمنية، أو تاريخ غير صحيح | استخدم `2026-04-18T13:30:00+03:00` أو `new Date()` |
|
|
168
|
+
| `AMOUNT_FORMAT` | خطأ | مبلغ بفاصلة عربية أو آلاف أو نوع غلط | `1150.00` بأرقام إنجليزية ونقطة |
|
|
169
|
+
| `PHASE2_INCOMPLETE` | خطأ | حقل من 6 و7 و8 ناقص، أو ختم بلا توقيع | مرّر الثلاثة مع بعض |
|
|
170
|
+
| `TRUNCATED_TLV` | خطأ | الرمز مقطوع عند فك الترميز | أعد قراءة الرمز كاملاً |
|
|
171
|
+
| `INVALID_BASE64` | خطأ | حمولة فيها حروف خارج Base64 | تحقق من نص الرمز |
|
|
172
|
+
| `INVALID_TLV` | خطأ | علامة صفرية أو بنية غير صحيحة | الرمز ليس رمز زاتكا |
|
|
173
|
+
| `AMOUNT_PRECISION` | تنبيه | المبلغ مو بمنزلتين عشريتين | استخدم `toZatcaAmount` |
|
|
174
|
+
| `VAT_EXCEEDS_TOTAL` | تنبيه | الضريبة أكبر من الإجمالي | راجع حساب الفاتورة |
|
|
175
|
+
| `PAYLOAD_TOO_LARGE` | تنبيه | الحمولة طويلة وقد تفشل مع ماسحات الميدان | اختبر الرمز على جهاز حقيقي |
|
|
176
|
+
| `DUPLICATE_TAG` | تنبيه | نفس العلامة مكررة في الرمز | ارفض الرمز أو راجع مصدره |
|
|
177
|
+
| `MISSING_REQUIRED_TAG` | تنبيه | علامة إلزامية ناقصة عند القراءة | الرمز ناقص وليس فاتورة صحيحة |
|
|
178
|
+
| `UNKNOWN_TAGS` | تنبيه | علامات خارج المواصفة | تظهر في `unknown` وتُتجاهل |
|
|
179
|
+
| `ZATCA_QR_ERROR` | خطأ | الرمز الافتراضي حين لا يوجد رمز أدق | اقرأ نص الرسالة |
|
|
180
|
+
|
|
181
|
+
```ts
|
|
182
|
+
try {
|
|
183
|
+
const payload = encodeZatcaTlv(invoice, { strict: true })
|
|
184
|
+
} catch (error) {
|
|
185
|
+
if (error.code === 'FIELD_TOO_LONG') {
|
|
186
|
+
// الاسم عربي طويل، قصّره أو راجع بيانات البائع
|
|
187
|
+
}
|
|
188
|
+
}
|
|
189
|
+
```
|
|
190
|
+
|
|
156
191
|
## جرّبها
|
|
157
192
|
|
|
158
193
|
```bash
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "zatca-qr",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.2",
|
|
4
4
|
"description": "ZATCA (Saudi FATOORA) e-invoice QR: encode, decode and validate in TLV + Base64. Byte-accurate Arabic text, zero dependencies. مولّد وقارئ رمز فاتورة زاتكا.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./src/index.js",
|
|
@@ -48,10 +48,10 @@
|
|
|
48
48
|
"homepage": "https://www.vibeio.dev",
|
|
49
49
|
"repository": {
|
|
50
50
|
"type": "git",
|
|
51
|
-
"url": "git+https://github.com/
|
|
51
|
+
"url": "git+https://github.com/Exeerkit/zatca-qr.git"
|
|
52
52
|
},
|
|
53
53
|
"bugs": {
|
|
54
|
-
"url": "https://github.com/
|
|
54
|
+
"url": "https://github.com/Exeerkit/zatca-qr/issues"
|
|
55
55
|
},
|
|
56
56
|
"engines": {
|
|
57
57
|
"node": ">=18"
|