marwan/agdar
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
agdar/ZATCA_DEPLOYMENT_CHECKLIST.md
Marwan Alwali 27a71b658a first commit
2025-11-02 14:35:35 +03:00

10 KiB
Raw Permalink Blame History

ZATCA E-Invoice Deployment & Testing Checklist

📋 Pre-Deployment Checklist

1. Database Setup ✅

  • Migrations created
  • Migrations run successfully
  • All models registered in admin
  • Indexes created for performance

2. Configuration

  • Tenant VAT number configured
  • Tenant Arabic name added
  • Tenant address information complete
  • Environment variables set (.env file)
# 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

  • cryptography installed
  • ecdsa installed
  • qrcode installed
  • pillow installed
  • reportlab installed
  • PyPDF2 installed
  • lxml installed
  • requests installed

4. Celery Setup

  • Redis/RabbitMQ running
  • Celery workers started
  • Celery beat configured
  • Tasks registered
# 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

# 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

# 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

# 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

# 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

from finance.zatca_service import ZATCAService

zatca = ZATCAService(use_sandbox=True)
xml = zatca.generate_xml_invoice(invoice)

assert '<Invoice' in xml
assert invoice.invoice_number in xml
assert invoice.tenant.vat_number in xml
  • XML generates without errors
  • XML contains all required fields
  • XML is valid UBL 2.1
  • XML includes QR code

Test 6: PDF Generation

from finance.pdf_service import PDFService

pdf = PDFService.generate_invoice_pdf(invoice)

assert len(pdf) > 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)

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

# 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

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)

# 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)

# 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:

# 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:

System Issues:

  • Check logs: logs/django.log
  • Check Celery logs
  • Review ZATCA response in admin
  • Consult documentation

✅ Final Verification

Before marking as complete, verify:

  • All code files created
  • All models updated
  • All migrations run
  • Admin interface updated
  • Templates enhanced
  • 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