{ "openapi": "3.1.0", "info": { "title": "DEXPIRY API", "description": "Decentralized warranty management API. Merchants issue warranty certificates; customers claim and manage warranties via mobile apps. Authenticate with `Authorization: Bearer `.", "version": "1.0.0", "contact": { "name": "DEXPIRY" } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT from login, claim, or magic-link flow" } }, "schemas": {} }, "paths": { "/health": { "get": { "summary": "Health check", "tags": [ "Health" ], "responses": { "200": { "description": "Default Response" } } } }, "/ready": { "get": { "summary": "Readiness (DB, chain, Pinata)", "tags": [ "Health" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/version": { "get": { "summary": "Version / git SHA", "tags": [ "Version" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/auth/login": { "post": { "summary": "Login (admin / merchant)", "tags": [ "Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 6 } }, "required": [ "email", "password" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/v1/auth/change-password": { "put": { "summary": "Change password", "tags": [ "Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "currentPassword": { "type": "string", "minLength": 1 }, "newPassword": { "type": "string", "minLength": 6 } }, "required": [ "currentPassword", "newPassword" ], "additionalProperties": false } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/merchant/stats": { "get": { "summary": "Merchant dashboard stats", "tags": [ "Merchant" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/merchant/products": { "post": { "summary": "Create merchant product", "tags": [ "Merchant" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantSku": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "gtin": { "type": "string" }, "price": { "type": "number", "exclusiveMinimum": true, "minimum": 0 }, "warrantyDurationMonths": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 }, "globalProductId": { "type": "string" } }, "required": [ "merchantSku", "title" ], "additionalProperties": false } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response" } } }, "get": { "summary": "List merchant products", "tags": [ "Merchant" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/merchant/products/{id}": { "put": { "summary": "Update merchant product", "tags": [ "Merchant" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantSku": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "gtin": { "type": "string", "nullable": true }, "price": { "type": "number", "exclusiveMinimum": true, "minimum": 0, "nullable": true }, "warrantyDurationMonths": { "type": "integer", "exclusiveMinimum": true, "minimum": 0, "nullable": true }, "globalProductId": { "type": "string", "nullable": true } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response" } } }, "delete": { "summary": "Delete merchant product", "tags": [ "Merchant" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/merchant/warranties/issue": { "post": { "summary": "Issue warranty", "tags": [ "Merchant" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantProductId": { "type": "string", "format": "uuid" }, "globalProductId": { "type": "string", "format": "uuid" }, "customerEmail": { "type": "string", "format": "email" }, "customerPhone": { "type": "string" }, "customerName": { "type": "string" }, "locationId": { "type": "string", "format": "uuid" }, "serialNumber": { "type": "string", "minLength": 1 }, "invoiceNumber": { "type": "string" }, "purchasePrice": { "type": "number", "exclusiveMinimum": true, "minimum": 0 }, "purchaseDate": { "type": "string", "format": "date-time" }, "warrantyDurationMonths": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "serialNumber" ], "additionalProperties": false } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/merchant/warranties/{id}": { "get": { "summary": "Get warranty by ID", "tags": [ "Merchant" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/merchant/warranties/lookup/{identifier}": { "get": { "summary": "Lookup warranty by DEXPIRY ID or email", "tags": [ "Merchant" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "identifier", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/merchant/warranties": { "get": { "summary": "List merchant warranties", "tags": [ "Merchant" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/merchant/warranties/{id}/retry-mint": { "post": { "summary": "Retry mint for warranty", "tags": [ "Merchant" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/merchant/warranties/{id}/resend-notification": { "post": { "summary": "Resend warranty notification email", "tags": [ "Merchant" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/merchant/sender-addresses": { "get": { "summary": "List receipt sender addresses", "tags": [ "Merchant" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "summary": "Register a receipt sender address", "tags": [ "Merchant" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" } }, "required": [ "email" ], "additionalProperties": false } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/merchant/sender-addresses/{id}": { "delete": { "summary": "Delete a receipt sender address", "tags": [ "Merchant" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/merchant/sender-addresses/{id}/resend-verification": { "post": { "summary": "Resend sender address verification email", "tags": [ "Merchant" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/global/receipt-share/{token}": { "get": { "summary": "Public receipt share preview", "tags": [ "Global" ], "parameters": [ { "schema": { "type": "string", "minLength": 16 }, "in": "path", "name": "token", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/global/sender-verify/{token}": { "get": { "summary": "Confirm merchant sender address", "tags": [ "Global" ], "parameters": [ { "schema": { "type": "string", "minLength": 16 }, "in": "path", "name": "token", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/global/products": { "get": { "summary": "List global products (public search)", "tags": [ "Global" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "brand", "required": false }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "model", "required": false }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "category", "required": false } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/global/jobs/warranty-reminders": { "post": { "summary": "Cron: warranty expiry push reminders", "tags": [ "Global" ], "description": "Protected with the x-cron-secret header.", "responses": { "200": { "description": "Default Response" } } } }, "/v1/admin/merchants": { "get": { "summary": "List all merchants", "tags": [ "Admin" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "summary": "Create merchant", "tags": [ "Admin" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "taxId": { "type": "string" }, "address": { "type": "string" }, "phone": { "type": "string" }, "contactEmail": { "type": "string", "format": "email" } }, "required": [ "name" ], "additionalProperties": false } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/admin/merchants/{id}": { "get": { "summary": "Get merchant by ID", "tags": [ "Admin" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response" } } }, "put": { "summary": "Update merchant", "tags": [ "Admin" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "taxId": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "contactEmail": { "type": "string", "format": "email", "nullable": true }, "status": { "type": "string", "enum": [ "ACTIVE", "SUSPENDED" ] } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/admin/merchants/{id}/users": { "get": { "summary": "List merchant users", "tags": [ "Admin" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "summary": "Create merchant user", "tags": [ "Admin" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 6 }, "name": { "type": "string", "minLength": 1 }, "merchantRole": { "type": "string", "enum": [ "OWNER", "ADMIN", "USER" ], "default": "USER" } }, "required": [ "email", "password", "name" ], "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/admin/global-products": { "get": { "summary": "List global products (admin)", "tags": [ "Admin" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "brand", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "model", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "category", "required": false } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "summary": "Create global product", "tags": [ "Admin" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "brand": { "type": "string", "minLength": 1 }, "model": { "type": "string", "minLength": 1 }, "category": { "type": "string", "minLength": 1 }, "gtin": { "type": "string" }, "imageUrl": { "type": "string", "format": "uri" } }, "required": [ "brand", "model", "category" ], "additionalProperties": false } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/admin/global-products/{id}": { "put": { "summary": "Update global product", "tags": [ "Admin" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "brand": { "type": "string", "minLength": 1 }, "model": { "type": "string", "minLength": 1 }, "category": { "type": "string", "minLength": 1 }, "gtin": { "type": "string", "nullable": true }, "imageUrl": { "type": "string", "format": "uri", "nullable": true } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response" } } }, "delete": { "summary": "Delete global product", "tags": [ "Admin" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/admin/stats": { "get": { "summary": "Platform stats", "tags": [ "Admin" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/customer/auth/validate": { "get": { "summary": "Validate magic link token (read-only)", "tags": [ "Customer Auth" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "token", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/customer/auth/request-access": { "post": { "summary": "Request wallet access (sends email with claim link)", "tags": [ "Customer Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" } }, "required": [ "email" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/v1/customer/auth/validate-claim": { "get": { "summary": "Validate claim link (for /u/[claimId] page)", "tags": [ "Customer Auth" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "claimId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/customer/auth/claim": { "post": { "summary": "Claim link auth (returns JWT)", "tags": [ "Customer Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "claimId": { "type": "string", "minLength": 1 }, "focusWarrantyId": { "type": "string", "format": "uuid" } }, "required": [ "claimId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/v1/customer/auth/resend-link": { "post": { "summary": "Resend claim link email", "tags": [ "Customer Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "claimId": { "type": "string", "minLength": 1 } }, "required": [ "claimId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/v1/customer/auth/magic-link": { "post": { "summary": "Magic link auth (consumes token, returns JWT)", "tags": [ "Customer Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1 } }, "required": [ "token" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/v1/customer/me": { "get": { "summary": "Get customer profile", "tags": [ "Customer" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response" } } }, "patch": { "summary": "Update customer profile", "tags": [ "Customer" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriptionTier": { "type": "string", "enum": [ "FREE", "PAID" ] }, "reminderDaysBeforeExpiry": { "type": "integer", "minimum": 1, "maximum": 30 } }, "additionalProperties": false } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/customer/push/register": { "post": { "summary": "Register push notification token", "tags": [ "Customer" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1 }, "platform": { "type": "string", "enum": [ "ios", "android" ] } }, "required": [ "token", "platform" ], "additionalProperties": false } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/customer/push/unregister": { "post": { "summary": "Unregister push notification token", "tags": [ "Customer" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" } }, "additionalProperties": false } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/customer/inbox-address": { "get": { "summary": "Get DEXPIRY inbox addresses", "tags": [ "Customer" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/customer/receipts/ocr": { "post": { "summary": "Receipt OCR (base64 image)", "tags": [ "Customer" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "imageBase64": { "type": "string", "minLength": 1, "maxLength": 5000000 } }, "required": [ "imageBase64" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/v1/customer/receipts": { "post": { "summary": "Save receipt to account", "tags": [ "Customer" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "imageBase64": { "type": "string", "minLength": 1, "maxLength": 5000000 }, "ocrData": { "type": "object", "properties": { "merchant": { "type": "string" }, "date": { "type": "string" }, "total": { "type": "string" }, "rawText": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "price": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } } }, "additionalProperties": false }, "folderId": { "type": "string", "format": "uuid" } }, "required": [ "imageBase64" ], "additionalProperties": false } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response" } } }, "get": { "summary": "List customer receipts", "tags": [ "Customer" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/customer/receipts/{id}": { "get": { "summary": "Get receipt by ID", "tags": [ "Customer" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response" } } }, "delete": { "summary": "Delete receipt", "tags": [ "Customer" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/customer/receipts/{id}/share-email": { "post": { "summary": "Share receipt by email", "tags": [ "Customer" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "toEmail": { "type": "string", "format": "email" } }, "required": [ "toEmail" ], "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/customer/receipts/folders": { "get": { "summary": "List receipt folders", "tags": [ "Customer" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "summary": "Create receipt folder", "tags": [ "Customer" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 40 } }, "required": [ "name" ], "additionalProperties": false } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/customer/receipts/{id}/folder": { "patch": { "summary": "Assign receipt to folder", "tags": [ "Customer" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "folderId": { "type": "string", "format": "uuid", "nullable": true } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/customer/warranties": { "get": { "summary": "List customer warranties", "tags": [ "Customer" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/customer/warranties/{id}": { "get": { "summary": "Get warranty by ID", "tags": [ "Customer" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response" } } } } }, "servers": [ { "url": "http://localhost:3001", "description": "Local" }, { "url": "https://api.dexpiry.com", "description": "Production" } ], "tags": [ { "name": "Health", "description": "Liveness and readiness" }, { "name": "Version", "description": "Build metadata" }, { "name": "Auth", "description": "Merchant and admin password login" }, { "name": "Global", "description": "Public product search and token links" }, { "name": "Merchant", "description": "Merchant products, warranties, sender addresses" }, { "name": "Admin", "description": "Platform administration" }, { "name": "Customer Auth", "description": "Claim and magic-link authentication" }, { "name": "Customer", "description": "Customer profile, warranties, receipts, inbox" } ] }