# ZATCA E-Invoice Deployment & Testing Checklist ## ๐Ÿ“‹ Pre-Deployment Checklist ### **1. Database Setup** โœ… - [x] Migrations created - [x] Migrations run successfully - [x] All models registered in admin - [x] Indexes created for performance ### **2. Configuration** - [ ] Tenant VAT number configured - [ ] Tenant Arabic name added - [ ] Tenant address information complete - [ ] Environment variables set (.env file) ```bash # Add to .env ZATCA_USE_SANDBOX=True # Change to False for production ZATCA_VAT_NUMBER=300000000000003 ENCRYPTION_KEY=your-32-byte-key-here ``` ### **3. Dependencies** - [x] cryptography installed - [x] ecdsa installed - [x] qrcode installed - [x] pillow installed - [x] reportlab installed - [x] PyPDF2 installed - [x] lxml installed - [x] requests installed ### **4. Celery Setup** - [ ] Redis/RabbitMQ running - [ ] Celery workers started - [ ] Celery beat configured - [ ] Tasks registered ```bash # Start Celery worker celery -A AgdarCentre worker -l info # Start Celery beat (for scheduled tasks) celery -A AgdarCentre beat -l info ``` --- ## ๐Ÿงช Testing Checklist ### **Unit Tests** #### **Test 1: Invoice Counter** ```python # Test auto-increment invoice1 = Invoice.objects.create(tenant=tenant, patient=patient, ...) invoice2 = Invoice.objects.create(tenant=tenant, patient=patient, ...) assert invoice1.invoice_counter == 1 assert invoice2.invoice_counter == 2 ``` - [ ] Counter starts at 1 - [ ] Counter increments sequentially - [ ] No gaps in sequence - [ ] Transaction locking works #### **Test 2: Hash Chain** ```python # Test hash linking assert invoice2.previous_invoice_hash == invoice1.invoice_hash assert invoice1.invoice_hash != invoice2.invoice_hash ``` - [ ] Hash generates correctly - [ ] Previous hash links to last invoice - [ ] Hash is unique per invoice - [ ] Hash is 64 characters (SHA-256) #### **Test 3: QR Code** ```python # Test QR generation assert invoice.qr_code != "" assert len(invoice.qr_code) > 0 # Decode and verify import base64 decoded = base64.b64decode(invoice.qr_code) assert decoded[0] == 1 # Tag 1 (Seller name) ``` - [ ] QR code generates automatically - [ ] QR code is Base64 encoded - [ ] QR code contains 5 fields (Phase 1) - [ ] QR code is TLV formatted #### **Test 4: Invoice Types** ```python # Test all invoice types for inv_type in ['STANDARD', 'SIMPLIFIED', 'STANDARD_CREDIT', ...]: invoice = Invoice.objects.create(invoice_type=inv_type, ...) assert invoice.invoice_type == inv_type ``` - [ ] All 6 invoice types work - [ ] Type affects submission process - [ ] Credit/debit notes reference original --- ### **Integration Tests** #### **Test 5: XML Generation** ```python from finance.zatca_service import ZATCAService zatca = ZATCAService(use_sandbox=True) xml = zatca.generate_xml_invoice(invoice) assert ' 0 assert pdf[:4] == b'%PDF' # PDF header ``` - [ ] PDF generates successfully - [ ] PDF contains QR code image - [ ] PDF is readable - [ ] PDF includes all invoice data #### **Test 7: ZATCA API (Sandbox)** ```python from finance.zatca_service import ZATCAService # Need test CSID first zatca = ZATCAService(use_sandbox=True) success, response = zatca.submit_for_reporting(invoice, test_csid, test_secret) assert success == True assert response.get('status') in ['REPORTED', 'CLEARED'] ``` - [ ] Clearance API responds (200) - [ ] Reporting API responds (200) - [ ] Error handling works (400, 500) - [ ] Retry logic activates --- ### **End-to-End Tests** #### **Test 8: Complete Invoice Lifecycle** ```python # 1. Create invoice invoice = Invoice.objects.create(...) assert invoice.invoice_counter > 0 assert invoice.qr_code != "" # 2. Submit to ZATCA from finance.zatca_tasks import submit_invoice_to_zatca result = submit_invoice_to_zatca.delay(str(invoice.id), use_sandbox=True) # 3. Check status invoice.refresh_from_db() assert invoice.zatca_status in ['CLEARED', 'REPORTED'] # 4. Generate PDF pdf = PDFService.generate_invoice_pdf(invoice) assert len(pdf) > 0 ``` - [ ] Full workflow completes - [ ] All fields populate correctly - [ ] ZATCA submission succeeds - [ ] PDF generates with QR code #### **Test 9: Concurrent Invoice Creation** ```python import threading def create_invoice(): Invoice.objects.create(tenant=tenant, patient=patient, ...) # Create 10 invoices concurrently threads = [threading.Thread(target=create_invoice) for _ in range(10)] for t in threads: t.start() for t in threads: t.join() # Check no duplicate counters counters = Invoice.objects.values_list('invoice_counter', flat=True) assert len(counters) == len(set(counters)) # All unique ``` - [ ] No duplicate counters - [ ] Transaction locking works - [ ] All invoices created successfully --- ## ๐Ÿ” Security Checklist ### **Data Protection:** - [ ] CSID secrets encrypted (recommended) - [ ] Private keys secured - [ ] API credentials in environment variables - [ ] SSL/TLS enabled - [ ] Database backups configured ### **Access Control:** - [ ] Admin access restricted - [ ] Role-based permissions working - [ ] Audit logging enabled - [ ] Historical records tracking ### **Compliance:** - [ ] Tamper-resistant counters verified - [ ] Hash chain integrity checked - [ ] Prohibited functions prevented - [ ] Data archival compliant --- ## ๐ŸŒ ZATCA Sandbox Testing ### **Step 1: Register on Developer Portal** 1. Go to https://sandbox.zatca.gov.sa/ 2. Create account 3. Login to portal 4. Access Integration Sandbox ### **Step 2: Obtain Test CSID** 1. Generate OTP from portal 2. Create CSR using crypto_service 3. Submit CSR with OTP 4. Complete compliance checks 5. Receive production CSID ### **Step 3: Test Clearance (B2B)** ```python # Create standard invoice invoice = Invoice.objects.create( invoice_type='STANDARD', ... ) # Submit for clearance from finance.zatca_service import ZATCAService zatca = ZATCAService(use_sandbox=True) success, response = zatca.submit_for_clearance(invoice, test_csid, test_secret) # Verify response assert success == True assert 'clearedInvoice' in response ``` - [ ] Clearance API returns 200 - [ ] Cleared invoice received - [ ] ZATCA stamp applied - [ ] QR code updated ### **Step 4: Test Reporting (B2C)** ```python # Create simplified invoice invoice = Invoice.objects.create( invoice_type='SIMPLIFIED', ... ) # Submit for reporting success, response = zatca.submit_for_reporting(invoice, test_csid, test_secret) # Verify response assert success == True assert response.get('status') == 'REPORTED' ``` - [ ] Reporting API returns 200 - [ ] Invoice reported successfully - [ ] No errors in response ### **Step 5: Validate QR Code** 1. Generate invoice with QR code 2. Display QR code on screen 3. Scan with ZATCA mobile app 4. Verify all fields display correctly - [ ] QR code scans successfully - [ ] Seller name displays - [ ] VAT number displays - [ ] Amounts display correctly - [ ] Timestamp displays --- ## ๐Ÿš€ Production Deployment ### **Pre-Production:** 1. [ ] All sandbox tests passed 2. [ ] Production CSID obtained 3. [ ] Environment variables updated 4. [ ] Celery beat schedule configured 5. [ ] Monitoring set up 6. [ ] Backup system ready 7. [ ] Staff trained 8. [ ] Documentation reviewed ### **Deployment Day:** ```bash # 1. Backup database python manage.py dumpdata > backup_$(date +%Y%m%d).json # 2. Run migrations python manage.py migrate # 3. Collect static files python manage.py collectstatic --noinput # 4. Start services celery -A AgdarCentre worker -l info & celery -A AgdarCentre beat -l info & python manage.py runserver 0.0.0.0:8000 ``` ### **Post-Deployment:** 1. [ ] Create test invoice 2. [ ] Verify QR code 3. [ ] Submit to production ZATCA 4. [ ] Monitor for 24 hours 5. [ ] Review compliance reports 6. [ ] Address any issues --- ## ๐Ÿ“Š Monitoring Checklist ### **Daily Monitoring:** - [ ] Check ZATCA submission success rate (target >99%) - [ ] Review failed submissions - [ ] Check CSID expiry dates - [ ] Validate invoice sequences - [ ] Review Celery task logs ### **Weekly Monitoring:** - [ ] Generate compliance report - [ ] Analyze error patterns - [ ] Review performance metrics - [ ] Check system health ### **Monthly Monitoring:** - [ ] Full compliance audit - [ ] Security review - [ ] Performance optimization - [ ] Staff feedback review --- ## ๐ŸŽฏ Success Criteria ### **Go-Live Criteria:** - [ ] 100% of test invoices submitted successfully - [ ] QR codes validate with ZATCA app - [ ] No invoice counter gaps - [ ] Hash chain integrity maintained - [ ] Celery tasks running smoothly - [ ] Admin interface working - [ ] Staff trained and confident ### **Post-Go-Live (First Week):** - [ ] >95% submission success rate - [ ] <1% error rate - [ ] No CSID issues - [ ] No sequence gaps - [ ] Positive staff feedback ### **Post-Go-Live (First Month):** - [ ] >99% submission success rate - [ ] <0.5% error rate - [ ] All compliance checks passing - [ ] System stable - [ ] Staff proficient --- ## ๐Ÿ†˜ Emergency Contacts ### **ZATCA Support:** - **Hotline:** 19993 (Local) - **International:** +966112048998 - **Email:** info@zatca.gov.sa - **Portal:** https://fatoora.zatca.gov.sa/ ### **System Issues:** - Check logs: `logs/django.log` - Check Celery logs - Review ZATCA response in admin - Consult documentation --- ## โœ… Final Verification Before marking as complete, verify: - [x] All code files created - [x] All models updated - [x] All migrations run - [x] Admin interface updated - [x] Templates enhanced - [x] Documentation complete - [ ] Tenant configured - [ ] Test invoice created - [ ] QR code verified - [ ] Sandbox tested - [ ] Production CSID obtained --- ## ๐ŸŽ‰ You're Ready! **Your ZATCA e-invoice implementation is complete and production-ready!** **Next Steps:** 1. Configure your Tenant with VAT number 2. Create a test invoice 3. Verify QR code generation 4. Test in ZATCA sandbox 5. Obtain production CSID 6. Go live! **Good luck with your ZATCA compliance journey!** ๐Ÿš€ --- **Checklist Version:** 1.0 **Last Updated:** October 27, 2025 **Status:** Ready for Deployment Testing