{"openapi":"3.1.0","info":{"title":"ConnectMeGuru eSIM & Wallet API","description":"API for international travel eSIM data plans lookup, wallet balance checking, and instant secure purchases.","version":"1.0.0"},"servers":[{"url":"https://www.connectmeguru.com"}],"paths":{"/api/products/search":{"get":{"summary":"Get eSIM Catalog","description":"If the returned field \"hasMore\" is true, ChatGPT must tell the user that these are some plans and suggest providing narrower criteria. If \"plans\" is empty, it means no single eSIM covers all requested countries; ChatGPT must inform the user and offer to look up separate plans for each country.","operationId":"getEsimCatalog","security":[],"parameters":[{"name":"country","in":"query","required":true,"schema":{"type":"string"},"description":"The destination name, country code, or query keywords to search eSIM plans (e.g. JP, Japan, \"Japan 100MB\", \"Europe 10GB\", \"USA 30 Days\"). GPT must merge previous context (e.g. if the user previously searched \"Japan\" and now says \"100MB\", search for \"Japan 100MB\") to refine results."}],"responses":{"200":{"description":"Successful retrieval of catalog","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"aggregator":{"type":"string"},"totalCount":{"type":"integer","description":"Total number of plans matching the search query."},"hasMore":{"type":"boolean","description":"True if matching plans exceed 60 and were truncated. If true, ChatGPT must notify the user and ask for narrower search criteria."},"plans":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"packageCode":{"type":"string"},"productUrl":{"type":"string"},"dataAmount":{"type":"number"},"dataUnit":{"type":"string"},"duration":{"type":"integer"},"retailPrice":{"type":"number"},"locationNames":{"type":"array","items":{"type":"string"}}}}}}}}}}}}},"/api/wallet/balance":{"get":{"summary":"Get Wallet Balance","description":"Retrieves the user's wallet balance in USD.","operationId":"getWalletBalance","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Wallet balance retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"balance":{"type":"number"}}}}}},"401":{"description":"Unauthorized"}}}},"/api/orders":{"post":{"summary":"Purchase eSIM","description":"Places a new eSIM order using the user's wallet balance. Returns the order ID on success.","operationId":"purchaseEsim","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"packageCode":{"type":"string","description":"The package code of the eSIM (e.g. PIK0SW14Q)."},"discountCode":{"type":"string","description":"Optional discount coupon code."}},"required":["packageCode"]}}}},"responses":{"200":{"description":"Purchase completed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"orderId":{"type":"string"},"status":{"type":"string"},"iccid":{"type":"string","description":"The ICCID of the provisioned eSIM."},"qrCode":{"type":"string","description":"The URL or base64 representation of the QR code image."},"smdpAddress":{"type":"string","description":"The SM-DP+ server address (e.g. rsp.truphone.com)."},"matchingId":{"type":"string","description":"The activation code/matching ID for manual input."},"lpaUrl":{"type":"string","description":"A clickable direct mobile LPA link to download the eSIM on iOS/Android (e.g., LPA:1$smdp$code)."}}}}}},"400":{"description":"Bad request (e.g. insufficient funds, inactive package)"},"401":{"description":"Unauthorized"}}},"get":{"summary":"Get User Orders","description":"Retrieves a paginated list of the authenticated user's eSIM orders and history.","operationId":"getUserOrders","security":[{"BearerAuth":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1},"description":"The page number to retrieve."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20},"description":"Number of orders per page."}],"responses":{"200":{"description":"Successful retrieval of orders list","content":{"application/json":{"schema":{"type":"object","properties":{"orders":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"iccid":{"type":"string"},"qrCode":{"type":"string"},"smdpAddress":{"type":"string"},"matchingId":{"type":"string"},"createdAt":{"type":"string"},"product":{"type":"object","properties":{"name":{"type":"string"},"packageCode":{"type":"string"}}}}}}}}}}},"401":{"description":"Unauthorized"}}}},"/api/orders/{id}":{"get":{"summary":"Get Order Details","description":"Retrieves details, status, and carrier provisioning credentials (QR code, ICCID, LPA URL) for a specific eSIM order.","operationId":"getOrderDetails","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The database CUID ID of the order."}],"responses":{"200":{"description":"Order details retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"iccid":{"type":"string"},"qrCode":{"type":"string"},"smdpAddress":{"type":"string"},"matchingId":{"type":"string"},"lpaUrl":{"type":"string"},"createdAt":{"type":"string"},"product":{"type":"object","properties":{"name":{"type":"string"},"packageCode":{"type":"string"}}}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Order not found"}}}},"/api/orders/{id}/cancel":{"post":{"summary":"Cancel Order","description":"Requests cancellation and wallet refund for an eligible eSIM order before active use.","operationId":"cancelOrder","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The order ID to cancel."}],"responses":{"200":{"description":"Order successfully cancelled and refunded","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}},"400":{"description":"Cancellation blocked (e.g. eSIM is already activated/downloaded)"},"401":{"description":"Unauthorized"}}}},"/api/discount/validate":{"post":{"summary":"Validate Discount Coupon","description":"Validates a coupon code and calculates the discount and net price before placing an order.","operationId":"validateDiscount","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"The coupon code to validate."},"orderAmount":{"type":"number","description":"The current order price in USD before discount."},"packageCode":{"type":"string","description":"The package code the coupon is being applied to."}},"required":["code","orderAmount"]}}}},"responses":{"200":{"description":"Coupon details validated","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean"},"discount":{"type":"number","description":"The discount amount in USD."},"type":{"type":"string","description":"Discount type: FIXED or PERCENTAGE."},"value":{"type":"number","description":"The percentage or fixed rate."},"category":{"type":"string"}}}}}},"400":{"description":"Coupon invalid or restrictions not met"},"401":{"description":"Unauthorized"}}}},"/api/esims/{id}/topup":{"get":{"summary":"Get Eligible Top-ups","description":"Lists all compatible top-up packages and prices for an active eSIM.","operationId":"getTopUpPackages","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The active eSIM order ID."}],"responses":{"200":{"description":"List of compatible top-up packages","content":{"application/json":{"schema":{"type":"object","properties":{"esim":{"type":"object","properties":{"id":{"type":"string"},"iccid":{"type":"string"},"productName":{"type":"string"}}},"packages":{"type":"array","items":{"type":"object","properties":{"packageCode":{"type":"string"},"name":{"type":"string"},"retailPrice":{"type":"number"},"duration":{"type":"integer"},"volume":{"type":"integer"},"speed":{"type":"string"}}}}}}}}},"401":{"description":"Unauthorized"}}},"post":{"summary":"Purchase Top-up","description":"Purchases a compatible top-up package for an active eSIM using the wallet balance.","operationId":"purchaseTopUp","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The active eSIM order ID."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"packageCode":{"type":"string","description":"The compatible top-up package code to purchase."}},"required":["packageCode"]}}}},"responses":{"200":{"description":"Top-up purchased and queued for provisioning successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"orderId":{"type":"string"},"status":{"type":"string"}}}}}},"400":{"description":"Insufficient funds or invalid plan"},"401":{"description":"Unauthorized"}}}},"/api/esims/{id}/usage":{"post":{"summary":"Refresh eSIM Usage","description":"Triggers a real-time data usage refresh directly from the network carrier (enforces 30-minute cooldown).","operationId":"refreshEsimUsage","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The active eSIM order ID."}],"responses":{"200":{"description":"Usage sync details","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"usage":{"type":"object","properties":{"usedVolume":{"type":"number"},"totalVolume":{"type":"number"},"remainingVolume":{"type":"number"},"status":{"type":"string"},"updatedAt":{"type":"string"}}}}}}}},"401":{"description":"Unauthorized"},"429":{"description":"Cooldown active"}}}},"/api/wallet/transactions":{"get":{"summary":"Get Wallet Transactions","description":"Retrieves the ledger of wallet deposits, debits, and refunds.","operationId":"getWalletTransactions","security":[{"BearerAuth":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"Transaction history retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"transactions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"number"},"type":{"type":"string","description":"DEBIT, CREDIT, or REFUND."},"description":{"type":"string"},"createdAt":{"type":"string"}}}}}}}}},"401":{"description":"Unauthorized"}}}},"/api/discount/available":{"get":{"summary":"Get Available Promotional Coupons","description":"Retrieves active official ConnectMeGuru promotional discount and coupon codes with descriptions. Use when customers ask for discounts, deals, promos, or coupon codes. Never invent fake codes or reveal third-party codes.","operationId":"getAvailableCoupons","security":[],"responses":{"200":{"description":"Promotional coupons retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"coupons":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Coupon code"},"type":{"type":"string","description":"PERCENTAGE or FIXED"},"value":{"type":"number","description":"Discount value"},"discount":{"type":"string","description":"Formatted discount string"},"description":{"type":"string","description":"Description of the coupon code"},"appInstallOnly":{"type":"boolean","description":"True if code is only applicable on the mobile app"},"minOrder":{"type":"number","description":"Minimum order requirement"}}}}}}}}}}}}},"components":{"schemas":{},"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Enter your Personal Access Token (PAT) or OAuth token."}}}}