{"openapi":"3.0.3","info":{"title":"Haps QR Code & Ticket Verification API","version":"2.0.0","description":"High-security QR code generation, scanning, and cryptographic ticket verification API for Haps underground nightlife, events, and promoters. Features Level H (30%) error recovery, custom Haps logo embedding, HMAC-SHA256 tamper-proof signatures, and real-time door scanner integration.","contact":{"name":"Haps Engineering Team","url":"https://haps.network","email":"dev@haps.network"}},"servers":[{"url":"/api/qr","description":"Current Environment API Server"}],"paths":{"/generate":{"post":{"summary":"Generate Branded QR Code","description":"Generates a high-resolution QR code with the Haps logo embedded at center (Level H 30% error correction). Supports PNG, SVG, and Data URL outputs.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"oneOf":[{"type":"string"},{"type":"object"}],"description":"Plain text, deep link URL, or structured HapsTicketPayload."},"format":{"type":"string","enum":["png","svg","data-url"],"default":"png"},"size":{"type":"integer","minimum":128,"maximum":2048,"default":512},"darkColor":{"type":"string","default":"#00d8da","description":"Module color (Hex)."},"lightColor":{"type":"string","default":"#0a0b10","description":"Background color (Hex)."},"includeLogo":{"type":"boolean","default":true},"signTicket":{"type":"boolean","default":true,"description":"Automatically cryptographically sign if data is a ticket."}}}}}},"responses":{"200":{"description":"Generated QR code payload or direct image."}}},"get":{"summary":"Generate QR code via GET (Direct image/binary stream)","parameters":[{"name":"text","in":"query","required":true,"schema":{"type":"string"}},{"name":"size","in":"query","schema":{"type":"integer","default":512}},{"name":"format","in":"query","schema":{"type":"string","enum":["png","svg"],"default":"png"}},{"name":"logo","in":"query","schema":{"type":"boolean","default":true}},{"name":"raw","in":"query","schema":{"type":"boolean","default":true}}],"responses":{"200":{"description":"Direct PNG or SVG image stream."}}}},"/scan":{"post":{"summary":"Decode QR Code Image","description":"Reads an image (uploaded via multipart/form-data or provided as base64 in JSON), locates QR modules, decodes content, and checks Haps signature validity.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"Base64 encoded image string or data URL."},"url":{"type":"string","description":"Direct URL to image file."}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}}}}}},"responses":{"200":{"description":"Decoded QR data, coordinate points, and ticket verification."}}}},"/verify-ticket":{"post":{"summary":"Verify Cryptographic Ticket & Guard Replay Attacks","description":"Verifies HMAC-SHA256 signature, validates dynamic expiration time, and optionally records the check-in to prevent double-entry / replay attacks.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"type":"string","description":"Raw scanned QR string or haps:// URI."},"checkIn":{"type":"boolean","default":false,"description":"Whether to record this scan as an entry check-in."},"staffId":{"type":"string","default":"door_staff_app"}}}}}},"responses":{"200":{"description":"Verification status and check-in confirmation."}}}},"/batch":{"post":{"summary":"Batch Ticket QR Generation","description":"Generates up to 200 signed QR codes at once. Can return an array of Base64 results or stream a ready-to-download ZIP containing all PNG passes."}},"/demo-ticket":{"get":{"summary":"Retrieve Sample Ready-to-Test Passes","description":"Returns 4 demo passes (VIP Backstage with secret location, General Admission, Dynamic Expiring Pass, and Duplicate Test Pass)."}},"/stats":{"get":{"summary":"Door Scanner Statistics & Audit Log"},"post":{"summary":"Reset Demo Check-In Ledger"}}}}