El Salvador Electronic Invoicing (DTE) Integration

ClinicFlow provides native tax compliance for medical and dental clinics in El Salvador through full integration with the Ministry of Finance (Ministerio de Hacienda - MH) Electronic Tax Document (Documento Tributario Electrónico - DTE) system.

---

1. System Overview

The DTE engine generates, digitally signs, transmits, and archives legally binding electronic invoices directly from clinic billing workflows.

flowchart TD
    A["Clinic Receptionist / Admin"] -->|POST /api/dte/checkout| B["1. Generate JSON Schema (Document 01 / 03 / 14)"]
    B --> C["2. Increment Sequence Counter (increment_dte_sequence)"]
    C --> D["3. Encrypt & Sign Payload (PKCS#7 / X.509 Certificate)"]
    D --> E["4. Synchronous Transmission to Hacienda MH API"]

    E -->|Status: RECIBIDO| F["MH Server Approved"]
    E -->|Connection / Server Timeout| G["MH Network Disruption"]

    F --> H["Embed Generation Code & Issue QR Stamp"]
    G --> I["Enqueue to dte_contingency_events (Offline Contingency Mode)"]

    style A fill:#1e293b,stroke:#0284c7,color:#ffffff
    style B fill:#0f172a,stroke:#0284c7,color:#ffffff
    style C fill:#0f172a,stroke:#0284c7,color:#ffffff
    style D fill:#0f172a,stroke:#0284c7,color:#ffffff
    style E fill:#0369a1,stroke:#38bdf8,color:#ffffff
    style F fill:#166534,stroke:#22c55e,color:#ffffff
    style G fill:#991b1b,stroke:#ef4444,color:#ffffff
    style H fill:#166534,stroke:#22c55e,color:#ffffff
    style I fill:#991b1b,stroke:#ef4444,color:#ffffff

---

2. Supported DTE Document Types

Document Code	Name	Legal Description	Primary Use Case
01	Factura Electrónica	Consumer Electronic Invoice	B2C consultation and dental treatment billing to individual patients.
03	Comprobante de Crédito Fiscal	Electronic Tax Credit Certificate	B2B billing to corporate patients, insurance providers, or enterprise accounts requiring VAT offset (IVA).
14	Factura de Sujeto Excluido	Excluded Subject Invoice	Billing for services purchased from vendors not registered for VAT.

---

3. Database Architecture & Schema

The DTE module relies on 9 dedicated tables in backend/src/db/schema.sql:

1. dte_settings: Per-clinic tax configuration (NIT, NRC, economic activity code 86200, establishment code, point of sale ID).
2. dte_credentials: AES-256 encrypted MH API authentication credentials, private key, and public certificate.
3. dte_sequences: Atomic sequential control numbers per DTE type (increment_dte_sequence() RPC prevents race conditions).
4. billing_items: Taxable product and clinical procedure catalog with standardized tax classifications.
5. patient_tax_profiles: Patient tax identification records (DUI, NIT, NRC, tax address, economic activity).
6. dte_invoices: Primary invoice registry storing generation code (Código de Generación), receipt stamp (Sello de Recepción), total amount, tax amounts, and MH authorization status (issued, rejected, voided, contingency).
7. dte_invoice_items: Granular invoice line items.
8. dte_payloads: Historical storage of raw JSON requests, signed JSON payloads, and raw MH HTTP response tokens for audit compliance.
9. dte_contingency_events: Queue of invoices created during internet or MH server outages for automatic retry upon connection recovery.

---

4. Transmission & Contingency Handling

Normal Online Mode

1. Payload assembled matching MH JSON Schema version 3.
2. Signed using PKCS#7 / X.509 certificate.
3. Transmitted to MH endpoint (https://api.mh.gob.sv/...).
4. Upon receiving status RECIBIDO, the receipt stamp (Sello de Recepción) and generation code are embedded into the PDF/Print layout.

Offline Contingency Mode (Modo Contingencia)

In the event of an internet disruption or MH server unavailability:

1. ClinicFlow automatically switches to Contingency Mode.
2. The invoice is generated locally with a Contingency Control Number.
3. The invoice is stored in dte_invoices with status contingency and queued in dte_contingency_events.
4. The background worker attempts batch synchronization once connectivity is re-established (must be completed within 24 hours per MH regulations).

---

5. Security & Key Management

• PrivateKey & Certificate Protection: MH private keys are encrypted using AES-256 envelope encryption (backend/src/utils/encryption.ts) with ENCRYPTION_KEY. Plaintext keys never touch disk or logs.
• Audit Compliance: All issuing attempts, failures, and invalidation operations are logged in dte_payloads and audit_logs.