دليل الربط للمطورين
لمزوّدي أنظمة المحاسبة ونقاط البيع: كيف ترسل الفواتير إلى المنصة.
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.