ڕێبەری بەستنەوە بۆ گەشەپێدەران
بۆ دابینکەرانی سیستەمی ژمێریاری و خاڵی فرۆشتن: چۆن پسوولە بۆ پلاتفۆرم بنێریت.
1. تۆمارکردن
باجدەر سیستەمەکەی لە «سیستەمە بەستراوەکانم» تۆمار دەکات و Client ID و کلیلێکی نهێنی وەردەگرێت کە تەنها یەکجار پیشان دەدرێت. سیستەمەکە تەنها بە ناوی ژمارەی باجی خۆیەوە پسوولە دەردەکات.
2. واژۆکردنی داواکارییەکان
| Header | Value |
|---|---|
| X-Client-Id | Client ID |
| X-Timestamp | Unix seconds (UTC), ±5 min |
| X-Nonce | 16–64 random characters, never reused |
| X-Signature | Base64(HMAC-SHA256(secret, stringToSign)) |
stringToSign = METHOD \n PATH \n QUERY \n TIMESTAMP \n NONCE \n CLIENT_ID \n hex(SHA256(body))
3. کردارەکان
| Method | Path | Purpose |
|---|---|---|
| POST | /api/v1/invoices | Submit one invoice (201 created, 200 identical resubmission) |
| POST | /api/v1/invoices/batch | Submit up to 100 invoices, per-item results |
| GET | /api/v1/invoices/{uuid} | Read an invoice you sold or bought |
| POST | /api/v1/invoices/{uuid}/cancel | Cancel within 72 h, then credit note |
| GET | /api/v1/taxpayers/{tin} | Check a buyer TIN before issuing |
| GET | /api/v1/catalog/items?q= | Look up standard item codes (GTIN or ETIS internal code) |
{
"invoiceType": "Standard",
"sellerTin": "100200300",
"buyerTin": "100200302",
"sellerInvoiceNumber": "RAF-1001",
"issueDate": "2026-10-01T09:30:00+03:00",
"currency": "IQD",
"totalAmount": 4750000,
"lines": [
{ "description": "Steel rebar 16mm", "itemCode": "IQ-STEEL-REBAR", "quantity": 5, "unitPrice": 850000, "lineTotal": 4250000 },
{ "description": "Transport", "quantity": 1, "unitPrice": 500000, "lineTotal": 500000 }
]
}
verificationUrl لە وەڵامەکەدا وەک کۆدی QR لەسەر پسوولە چاپ بکە.
4. کۆدی یەکگرتووی کاڵا
لە خانەی itemCodeی هەر ڕیزێکدا بارکۆدی کاڵا (GTIN) بنووسە ئەگەر هەبێت، ئەگەرنا کۆدی ناوخۆیی ETIS لە ڕێبەرەکەوە (/api/v1/catalog/items). نرخە ئاماژەییەکان لەم کۆدانە دروست دەکرێن. کۆدی HSی گومرگی ئارەزوومەندانەیە و تەنها بۆ پۆلێنکردنە.
5. بەستنەوەی ئامێرەکانی کاشێر و خاڵی فرۆشتن
کاشێرەکە بێ ئینتەرنێت کار دەکات: هەر پسوولەیەک بە کلیلی تایبەتی خۆی واژۆ دەکات و QRێک چاپ دەکات کە دەستبەجێ پشتڕاست دەکرێتەوە، پاشان کاتێک پەیوەندی هەبوو لە ماوەی 72 کاتژمێردا پسوولەکان دەنێرێت.
- ئامێرەکە جووتە کلیلێکی ECDSA P-256 دروست دەکات و کلیلی تایبەت هەرگیز ئامێرەکە جێناهێڵێت.
- ئامێرەکە لە دەروازەی باجدەردا تۆمار دەکرێت و کۆدی چالاککردن وەردەگرێت، پاشان /api/v1/pos/activate بانگ دەکات بۆ وەرگرتنی بڕوانامەیەکی واژۆکراو.
- بۆ هەر پسوولەیەک: ژمارەیەکی زنجیرەیی بێ بۆشایی، بەستەرێک بە پسوولەی پێشوو، واژۆ، و QRێک کە بڕوانامەکەی تێدایە.
- پسوولەکان لە ڕێگەی /api/v1/pos/receipts ڕادەگەیەنرێن (بە واژۆی ئامێر یان بە سیستەمی باجدەر)، و ئەو ژمارانەی /api/v1/pos/devices/me داوایان دەکات دووبارە دەنێردرێنەوە.
6. شێوازی پسوولەی کاشێر
| Method | Path | Auth | Purpose |
|---|---|---|---|
| POST | /api/v1/pos/activate | — | Activation code + device public key → platform-signed device certificate |
| POST | /api/v1/pos/receipts | Device or HMAC | Report up to 500 signed receipts, any order, within 72 h |
| GET | /api/v1/pos/devices/me | Device | Status and receipt numbers the platform is missing |
payload = ETR1|device|tin|seq|issuedAtUnix|currency|total|tax|prev prev = first 16 hex of SHA-256(previous payload) (0000000000000000 for seq 1) certificate = ETDC1|device|tin|publicKey|expiresUnix|platformKeyId|P|S token = b64url(payload).b64url(deviceSig).b64url(certificate).b64url(platformSig) QR = https://etis.haidar.website/r?t=token signatures = ECDSA P-256 / SHA-256, IEEE P1363 (r||s, 64 bytes) Device request headers: X-Device-Code, X-Timestamp, X-Nonce, X-Signature = Base64(ECDSA(deviceKey, stringToSign)) (same stringToSign as HMAC, device code as client id)
نموونەی ئامادە بە C# و Python و JavaScript لەگەڵ ڤێکتەری تاقیکردنەوە لە کۆگاکەدا لە sdk/pos، و تایبەتمەندیی تەواو لە docs/POS.md.