ZATCA E-Invoicing API | واجهة برمجة تطبيقات الفوترة الإلكترونية

Production-ready FastAPI integration with ZATCA (Saudi e-invoicing) — fully upgraded for API v2.1.1.

What's New | الجديد

Critical Bug Fixed

• XML Builder: Fixed quantity_el.text bug — was using line_index instead of line.quantity, causing all invoices to show wrong quantities!

5 New API Endpoints (ZATCA Client)

Method	Endpoint	Description
POST	/production/renewal	Renew expiring CSID
POST	/compliance/qr/buyer	Validate buyer QR code
POST	/compliance/qr/seller	Validate seller QR code
POST	/csids/revoke	Revoke CSID certificate
POST	/csids/renewal	Renew compliance CSID

8 New Application Endpoints

Method	Endpoint	Description
POST	/onboarding/renewal	CSID renewal flow
POST	/invoices/credit-note	Create credit notes
POST	/invoices/debit-note	Create debit notes
POST	/invoices/{id}/cancel	Cancel invoice
POST	/compliance-checks/buyer-qr	QR validation (buyer)
POST	/compliance-checks/seller-qr	QR validation (seller)
POST	/batch/submit	Batch invoice submission
GET	/health	Health check

Enhanced Features

• Retry logic with exponential backoff (3 retries, configurable)
• Structured logging with JSON format
• SQLite database replacing in-memory storage
• Credit/Debit notes with UBL XML support
• Standard (B2B) invoices separate from simplified (B2C)
• Certificate-based signing using actual X.509 from ZATCA
• Request tracing with unique request IDs
• Batch operations for bulk invoice submission

Project Structure

project/
├── config.py              # Environment configuration
├── logger.py              # Structured JSON logging
├── database.py            # SQLite + SQLAlchemy models
├── requirements.txt       # Dependencies
├── core/
│   ├── models.py          # Invoice, CreditNote, DebitNote, enums
│   ├── crypto_utils.py    # EC keys, CSR, signing with certificates
│   ├── qr_generator.py    # TLV QR code generation
│   ├── xml_builder.py     # UBL XML for all invoice types
│   └── zatca_client.py    # ZATCA HTTP client with retries
└── api/
    ├── schemas.py         # Pydantic request/response models
    └── main.py            # FastAPI application

Quick Start

# Install dependencies
pip install -r requirements.txt

# Run the API
uvicorn api.main:app --reload --port 8000

# Open interactive docs
open http://127.0.0.1:8000/docs

Environment Variables

Variable	Default	Description
DATABASE_URL	sqlite:///./zatca.db	Database connection
ZATCA_ENVIRONMENT	sandbox	sandbox, simulation, production
ZATCA_TIMEOUT	30	API timeout in seconds
ZATCA_MAX_RETRIES	3	Retry attempts
LOG_LEVEL	INFO	Logging level

API Workflow

1. Onboarding

POST /keys                    → Generate EC key pair
POST /csr                     → Create CSR from key
POST /onboarding/compliance   → Get compliance CSID
POST /invoices/{id}/compliance-check  → Validate test invoices
POST /onboarding/production   → Get production CSID

2. Invoice Lifecycle

POST /invoices                → Create invoice (simplified/standard)
GET  /invoices/{id}/xml       → Get unsigned XML
POST /invoices/{id}/sign      → Sign with certificate
POST /invoices/{id}/report    → Submit simplified (B2C)
POST /invoices/{id}/clear     → Submit standard (B2B)
POST /invoices/{id}/cancel    → Cancel if needed

3. Credit/Debit Notes

POST /invoices/credit-note    → Reference original invoice
POST /invoices/debit-note     → Reference original invoice
POST /invoices/{id}/sign      → Sign the note
POST /invoices/{id}/report    → Submit the note

4. CSID Renewal

POST /onboarding/renewal      → Renew before expiry

License

MIT