zatca-qr 1.0.0 → 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 +20 -6
- package/README.en.md +10 -2
- package/README.md +39 -2
- package/package.json +3 -3
package/CHANGELOG.md
CHANGED
|
@@ -1,16 +1,30 @@
|
|
|
1
1
|
# سجل التغييرات
|
|
2
2
|
|
|
3
|
-
## 1.0.
|
|
3
|
+
## 1.0.2: 2026-09-30
|
|
4
|
+
|
|
5
|
+
- جدول كامل لرموز الأخطاء والتنبيهات في الواجهة، مع معنى كل رمز وما تفعله عند ظهوره.
|
|
6
|
+
- اختبار جديد يمنع اختلاف الجدول عن الكود: أي رمز يُضاف بلا توثيق يُسقط الاختبارات.
|
|
7
|
+
- الملف منشور عبر Trusted Publishing من GitHub Actions، ومعه شهادة بناء موقّعة.
|
|
8
|
+
|
|
9
|
+
## 1.0.1: 2026-09-30
|
|
10
|
+
|
|
11
|
+
تحسين في الواجهة فقط، بلا تغيير في الكود.
|
|
12
|
+
|
|
13
|
+
- شارة إصدار npm في أعلى الواجهة.
|
|
14
|
+
- أمر التثبيت صار `npm install zatca-qr` أولاً، والمستودع بديلاً.
|
|
15
|
+
- وصف الحزمة وكلماتها المفتاحية تُبرز الفرق: توليد وقراءة وفحص، مع دعم العربية.
|
|
16
|
+
|
|
17
|
+
## 1.0.0: 2026-09-29
|
|
4
18
|
|
|
5
19
|
الإصدار الأول.
|
|
6
20
|
|
|
7
|
-
- `encodeZatcaTlv(data, { strict })
|
|
8
|
-
- `buildTlvBytes(data)
|
|
9
|
-
- `decodeZatcaTlv(base64)
|
|
21
|
+
- `encodeZatcaTlv(data, { strict })`: ترميز TLV ثم Base64، مع ترتيب العلامات تصاعدياً.
|
|
22
|
+
- `buildTlvBytes(data)`: الوصول إلى البايتات الخام للفحص والاختبار.
|
|
23
|
+
- `decodeZatcaTlv(base64)`: فك الترميز إلى حقول مقروءة، مع تنبيهات للعلامات المكرّرة
|
|
10
24
|
والناقصة والخارجة عن المواصفة، وتسامح مع Base64 الآمن للروابط.
|
|
11
|
-
- `validateZatcaInvoice(data)
|
|
25
|
+
- `validateZatcaInvoice(data)`: فحص المواصفة: الرقم الضريبي، الطابع الزمني، المبالغ،
|
|
12
26
|
حدود البايتات، واكتمال حقول مرحلة الربط.
|
|
13
|
-
- `toZatcaAmount(value)
|
|
27
|
+
- `toZatcaAmount(value)`: تنسيق المبلغ بفاصلة نقطية وبمنزلتين.
|
|
14
28
|
- دعم علامات مرحلة الربط 6 و7 و8 و9.
|
|
15
29
|
- 38 اختباراً بلا أي تبعية، منها فيكتور مرجعي بفاتورة مبسّطة.
|
|
16
30
|
- صفحة تجريبية عربية تعمل في المتصفح بلا خادم.
|
package/README.en.md
CHANGED
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
**ZATCA (Saudi FATOORA) e-invoice QR payloads — zero dependencies, no server, tested against the specification.**
|
|
4
4
|
|
|
5
|
+
[](https://www.npmjs.com/package/zatca-qr)
|
|
5
6
|
[](https://github.com/Exeerkit/zatca-qr/actions/workflows/ci.yml)
|
|
6
7
|
[](LICENSE)
|
|
7
8
|
[](https://github.com/exeerkit/zatca-qr/releases)
|
|
@@ -26,8 +27,9 @@ before you issue it.
|
|
|
26
27
|
## Install
|
|
27
28
|
|
|
28
29
|
```bash
|
|
29
|
-
npm install
|
|
30
|
-
|
|
30
|
+
npm install zatca-qr
|
|
31
|
+
# or straight from the repository
|
|
32
|
+
npm install github:exeerkit/zatca-qr
|
|
31
33
|
```
|
|
32
34
|
|
|
33
35
|
Zero dependencies. ESM only. Runs in Node 18+, browsers, Cloudflare Workers, Deno and Bun.
|
|
@@ -91,6 +93,12 @@ node examples/node.mjs # CLI example, nothing to install
|
|
|
91
93
|
node --test # 38 tests, zero dependencies
|
|
92
94
|
```
|
|
93
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
|
+
|
|
94
102
|
## References
|
|
95
103
|
|
|
96
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
|
@@ -4,6 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
**تولّد رمز QR لفواتير زاتكا السعودية وتقرأه. بدون مكتبات خارجية وبدون خادم.**
|
|
6
6
|
|
|
7
|
+
[](https://www.npmjs.com/package/zatca-qr)
|
|
7
8
|
[](https://github.com/Exeerkit/zatca-qr/actions/workflows/ci.yml)
|
|
8
9
|
|
|
9
10
|
[](LICENSE)
|
|
@@ -32,8 +33,9 @@
|
|
|
32
33
|
## التثبيت
|
|
33
34
|
|
|
34
35
|
```bash
|
|
35
|
-
npm install
|
|
36
|
-
|
|
36
|
+
npm install zatca-qr
|
|
37
|
+
# أو مباشرة من المستودع
|
|
38
|
+
npm install github:exeerkit/zatca-qr
|
|
37
39
|
```
|
|
38
40
|
|
|
39
41
|
بدون أي مكتبة خارجية. تعمل في Node 18 وأحدث، وفي المتصفح، وفي Cloudflare Workers وDeno وBun.
|
|
@@ -151,6 +153,41 @@ const payload = encodeZatcaTlv({
|
|
|
151
153
|
|
|
152
154
|
العملة في هذا الحقل ريال سعودي دايم، حتى لو الفاتورة بعملة ثانية في ملف XML.
|
|
153
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
|
+
|
|
154
191
|
## جرّبها
|
|
155
192
|
|
|
156
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"
|