{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "DocumentSnapshot",
  "description": "The immutable record the PDF is rendered from. Issued ONCE per document: everything (seller data, template text, prices, totals) is copied into the snapshot at issue time so an old invoice never changes when settings, prices or product names change later. The PDF, the customer screens, the WhatsApp/e-mail and the verify page all read this same object.",
  "type": "object",
  "required": ["id", "type", "number", "status", "payment_state", "issued_at", "currency", "order", "seller", "buyer", "lines", "totals", "verify", "template"],
  "properties": {
    "id": { "type": "string", "format": "uuid" },
    "type": { "enum": ["invoice", "proforma", "credit_note"] },
    "number": { "type": "string", "pattern": "^(INV|PF|CN)-\\d{2}-\\d{6}$", "description": "{prefix}-{yy}-{6-digit sequence}. Prefix is configurable. Sequence is atomic and gap-free per type." },
    "status": { "enum": ["issued", "voided", "superseded"], "description": "voided = cancelled before delivery/payment (no credit note). superseded = replaced by a re-issued copy (company-name invoice)." },
    "payment_state": { "enum": ["paid", "due_on_delivery", "awaiting_payment", "refunded"], "description": "LIVE value (changes after issue, e.g. due_on_delivery -> paid). The PDF prints the state at issue; the verify page shows the live state." },
    "issued_at": { "type": "string", "format": "date-time", "description": "ISO-8601 with Africa/Cairo offset" },
    "currency": { "const": "EGP" },
    "order": { "type": "object", "required": ["number"], "properties": { "number": { "type": "string" }, "placed_at": { "type": "string", "format": "date-time" }, "channel": { "enum": ["web", "app", "sales"] } } },
    "against": { "type": ["object", "null"], "description": "credit_note only: the invoice it reduces", "properties": { "number": { "type": "string" } } },
    "seller": { "type": "object", "required": ["legal_name_ar", "legal_name_en", "tax_registration_no"], "properties": {
      "legal_name_ar": { "type": "string" }, "legal_name_en": { "type": "string" }, "address_ar": { "type": "string" }, "address_en": { "type": "string" },
      "phone": { "type": "string" }, "email": { "type": "string" }, "tax_registration_no": { "type": "string" }, "commercial_register_no": { "type": ["string", "null"] }, "logo_url": { "type": "string" } } },
    "buyer": { "type": "object", "required": ["name"], "properties": {
      "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": ["string", "null"] },
      "address": { "type": "object", "properties": { "line": { "type": "string" }, "city": { "type": "string" }, "governorate": { "type": "string" } } },
      "company": { "type": ["object", "null"], "description": "only when the customer asked for a company-name invoice", "properties": { "name": { "type": "string" }, "tax_registration_no": { "type": "string" } } } } },
    "lines": { "type": "array", "minItems": 1, "items": { "type": "object", "required": ["name_ar", "name_en", "qty", "unit_price", "line_total"], "properties": {
      "sku": { "type": ["string", "null"] }, "name_ar": { "type": "string" }, "name_en": { "type": "string" }, "size_ar": { "type": "string" }, "size_en": { "type": "string" },
      "image_url": { "type": ["string", "null"] }, "qty": { "type": "integer", "minimum": 1 }, "unit_price": { "type": "number" }, "list_price": { "type": ["number", "null"], "description": "price before the product's own discount; printed struck-through" }, "line_total": { "type": "number" } } } },
    "totals": { "type": "object", "required": ["subtotal", "total", "vat_amount", "net_before_vat", "vat_percent"], "properties": {
      "subtotal": { "type": "number" }, "coupon": { "type": ["object", "null"], "properties": { "code": { "type": "string" }, "amount": { "type": "number" } } },
      "glow_points": { "type": ["object", "null"], "properties": { "points": { "type": "integer" }, "amount": { "type": "number" } } },
      "shipping": { "type": "number" }, "total": { "type": "number" }, "vat_percent": { "type": "number" }, "vat_amount": { "type": "number" }, "net_before_vat": { "type": "number" },
      "prices_include_vat": { "type": "boolean" } } },
    "payment": { "type": "object", "properties": {
      "method": { "enum": ["card", "apple_pay", "wallet", "cod", "instapay"] }, "card_last4": { "type": ["string", "null"] }, "wallet_phone_masked": { "type": ["string", "null"] },
      "gateway_ref": { "type": ["string", "null"], "description": "MPGS transaction/order id" }, "paid_at": { "type": ["string", "null"], "format": "date-time" },
      "instapay": { "type": ["object", "null"], "properties": { "handle": { "type": "string" }, "reference": { "type": "string" }, "hold_until": { "type": "string", "format": "date-time" } } },
      "refund": { "type": ["object", "null"], "description": "credit_note only", "properties": { "reason": { "type": "string" }, "to": { "type": "string" }, "eta_text": { "type": "string" } } } } },
    "verify": { "type": "object", "description": "absent on proforma (it has no QR)", "properties": { "url": { "type": "string", "format": "uri" }, "sig": { "type": "string", "pattern": "^[0-9a-f]{10}$" } } },
    "template": { "type": "object", "required": ["language", "version"], "properties": {
      "language": { "enum": ["ar", "en"] }, "version": { "type": "integer", "description": "template settings version copied at issue time" },
      "footer_note": { "type": "string" }, "thank_you": { "type": "string" }, "primary_color": { "type": "string" }, "digits": { "enum": ["latin", "arabic_indic"] },
      "show": { "type": "object", "properties": { "sku": { "type": "boolean" }, "list_price": { "type": "boolean" }, "images": { "type": "boolean" }, "payment_details": { "type": "boolean" }, "qr": { "type": "boolean" } } } } }
  },
  "examples": [{
    "id": "7c0e6a2e-6f3a-4a52-9d57-5a1e0d2b9a11", "type": "invoice", "number": "INV-26-024117", "status": "issued", "payment_state": "paid",
    "issued_at": "2026-10-29T14:32:00+02:00", "currency": "EGP", "order": { "number": "TNG-24117", "placed_at": "2026-10-29T14:32:00+02:00", "channel": "web" }, "against": null,
    "seller": { "legal_name_ar": "TNG للصناعات التجميلية", "legal_name_en": "TNG for Cosmetic Industries", "address_ar": "270 حدائق الأهرام، الجيزة، مصر", "address_en": "270 Hadayek El-Ahram, Giza, Egypt", "phone": "+20 100 604 6943", "email": "info@lotusorganics.store", "tax_registration_no": "000-000-000", "commercial_register_no": null, "logo_url": "/assets/logo/tng-logo.jpg" },
    "buyer": { "name": "سلمى أحمد", "phone": "01012345678", "email": null, "address": { "line": "12 شارع التحرير، الدقي", "city": "الدقي", "governorate": "الجيزة" }, "company": null },
    "lines": [
      { "sku": "ORG-COL-050", "name_ar": "كريم الكولاجين ضد التجاعيد", "name_en": "Collagen Anti-Wrinkle Cream", "size_ar": "50 جم", "size_en": "50 g", "image_url": null, "qty": 1, "unit_price": 351, "list_price": 390, "line_total": 351 },
      { "sku": "ORG-RWF-250", "name_ar": "غسول الوش بماء الورد", "name_en": "Rose Water Face Wash", "size_ar": "250 مل", "size_en": "250 ml", "image_url": null, "qty": 2, "unit_price": 225, "list_price": 250, "line_total": 450 },
      { "sku": "ORG-KSH-200", "name_ar": "شامبو الكيراتين العلاجي", "name_en": "Keratin Treatment Shampoo", "size_ar": "200 مل", "size_en": "200 ml", "image_url": null, "qty": 1, "unit_price": 234, "list_price": 260, "line_total": 234 }
    ],
    "totals": { "subtotal": 1035, "coupon": { "code": "GLOW10", "amount": 100 }, "glow_points": null, "shipping": 0, "total": 935, "vat_percent": 14, "vat_amount": 114.82, "net_before_vat": 820.18, "prices_include_vat": true },
    "payment": { "method": "card", "card_last4": "4242", "wallet_phone_masked": null, "gateway_ref": "8F3K21", "paid_at": "2026-10-29T14:32:00+02:00", "instapay": null, "refund": null },
    "verify": { "url": "https://lotusorganics.store/v/INV-26-024117?s=7272b786b4", "sig": "7272b786b4" },
    "template": { "language": "ar", "version": 3, "footer_note": "الاسترجاع خلال 7 أيام من الاستلام للمنتجات المقفولة. للاستفسار كلمينا على واتساب.", "thank_you": "شكرًا إنك اخترتي TNG", "primary_color": "#F4A04B", "digits": "latin", "show": { "sku": true, "list_price": true, "images": true, "payment_details": true, "qr": true } }
  }]
}