{
  "openapi": "3.0.3",
  "info": {
    "title": "FIOTECH FTCPAY API",
    "description": "API tài liệu chính thức cho cổng thanh toán Web3 FTCPAY. Hỗ trợ quy trình đổi Crypto (USDT, BTC, ETH, BNB) sang VND, tích hợp VietQR chuẩn Napas 24/7, 17 cổng dịch vụ tiện ích hàng ngày, và lưu trữ dữ liệu thời gian thực trên Vercel Redis.",
    "version": "1.0.0",
    "contact": {
      "name": "Fiotech Support",
      "url": "https://t.me/huancapital",
      "email": "support@fiotech.org"
    },
    "license": {
      "name": "Proprietary - Fiotech Chain",
      "url": "https://crypto-pay-app.fiotech.org"
    }
  },
  "servers": [
    {
      "url": "/",
      "description": "Máy chủ hiện tại (Auto-detect Current Host)"
    },
    {
      "url": "https://crypto-pay-app.fiotech.org",
      "description": "Production Vercel (Custom Domain)"
    },
    {
      "url": "https://fiotechchain-cryptopay-demo.vercel.app",
      "description": "Vercel Production Mirror"
    },
    {
      "url": "http://localhost:3000",
      "description": "Local Development (Port 3000)"
    }
  ],
  "tags": [
    {
      "name": "Health & Infrastructure",
      "description": "Kiểm tra tình trạng máy chủ và kết nối cơ sở dữ liệu Vercel Redis"
    },
    {
      "name": "Orders & Transactions",
      "description": "Tạo đơn hàng, tra cứu sổ lệnh, cập nhật tiến trình thanh toán Napas 24/7"
    }
  ],
  "paths": {
    "/api/redis/health": {
      "get": {
        "tags": ["Health & Infrastructure"],
        "summary": "Kiểm tra kết nối và độ trễ Vercel Redis",
        "description": "Thực hiện lệnh PING đến cụm Vercel KV / Upstash Redis, đo độ trễ mạng tính bằng mili-giây (ms), trả về loại nhà cung cấp và tổng số đơn hàng đang lưu trữ.",
        "responses": {
          "200": {
            "description": "Kết nối Redis hoạt động bình thường",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                },
                "example": {
                  "status": "ok",
                  "latencyMs": 14,
                  "ping": "PONG",
                  "redis": {
                    "isMock": false,
                    "connected": true,
                    "provider": "Vercel KV / Upstash Redis",
                    "endpoint": "https://vital-flea-59841.upstash.io"
                  },
                  "totalOrders": 12,
                  "timestamp": "2026-09-13T03:15:30.000Z"
                }
              }
            }
          }
        }
      }
    },
    "/api/orders": {
      "get": {
        "tags": ["Orders & Transactions"],
        "summary": "Lấy danh sách 30 đơn hàng gần nhất trong Redis",
        "description": "Đọc danh sách mã đơn hàng từ Redis List `ftc:orders:list` và lấy chi tiết từng đơn hàng từ Redis Key `ftc:order:{id}` theo thứ tự mới nhất.",
        "responses": {
          "200": {
            "description": "Danh sách đơn hàng được lấy thành công",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "count": { "type": "integer" },
                    "orders": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Order" }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Lỗi truy vấn Redis",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      },
      "post": {
        "tags": ["Orders & Transactions"],
        "summary": "Tạo đơn hàng mới (Crypto ➔ VND hoặc 17 dịch vụ thanh toán)",
        "description": "Tạo một giao dịch mới, tính toán số tiền quy đổi theo tỷ giá thời gian thực, sinh mã đơn hàng độc nhất (prefix `FTC-`), tạo liên kết mã VietQR chuẩn Napas 24/7 và lưu vào Vercel Redis với trạng thái ban đầu `PENDING_CRYPTO`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateOrderRequest"
              },
              "examples": {
                "cryptoSwap": {
                  "summary": "Đổi USDT sang tài khoản Ngân hàng (VCB)",
                  "value": {
                    "type": "CRYPTO_SWAP",
                    "serviceName": "Đổi USDT sang VND",
                    "cryptoToken": "USDT",
                    "cryptoAmount": 100,
                    "vndAmount": 2545000,
                    "rate": 25450,
                    "bankCode": "VCB",
                    "bankAccount": "0071001234567",
                    "accountName": "NGUYEN VAN A"
                  }
                },
                "servicePayment": {
                  "summary": "Nạp tiền điện thoại Viettel",
                  "value": {
                    "type": "FEATURE_DEMO",
                    "serviceName": "Nạp tiền điện thoại",
                    "cryptoToken": "USDT",
                    "cryptoAmount": 3.93,
                    "vndAmount": 100000,
                    "rate": 25450,
                    "bankCode": "MB",
                    "bankAccount": "FTCPAY-TOPUP",
                    "accountName": "DICH VU TOPUP",
                    "recipientInfo": "Viettel | 0988 123 456"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tạo đơn hàng thành công và đã lưu vào Redis",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "message": { "type": "string" },
                    "order": { "$ref": "#/components/schemas/Order" }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Dữ liệu yêu cầu không hợp lệ",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/api/orders/{id}": {
      "get": {
        "tags": ["Orders & Transactions"],
        "summary": "Tra cứu chi tiết đơn hàng theo ID",
        "description": "Lấy thông tin chi tiết đầy đủ của đơn hàng từ Vercel Redis dựa trên mã định danh (ví dụ `FTC-MTZ8V3GR-83FM`).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Mã định danh đơn hàng (Order ID)",
            "schema": { "type": "string" },
            "example": "FTC-MTZ8V3GR-83FM"
          }
        ],
        "responses": {
          "200": {
            "description": "Chi tiết đơn hàng",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "order": { "$ref": "#/components/schemas/Order" }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Không tìm thấy đơn hàng trong Redis",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      },
      "patch": {
        "tags": ["Orders & Transactions"],
        "summary": "Cập nhật trạng thái đơn hàng (Mô phỏng On-Chain & Napas)",
        "description": "Chuyển tiếp trạng thái đơn hàng trong Redis để mô phỏng vòng đời giao dịch 30 giây: `PENDING_CRYPTO` ➔ `BLOCKCHAIN_CONFIRMING` ➔ `PAYOUT_NAPAS` ➔ `COMPLETED`. Tự động phát sinh mã Hash giao dịch và số tham chiếu Napas.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Mã đơn hàng cần cập nhật",
            "schema": { "type": "string" },
            "example": "FTC-MTZ8V3GR-83FM"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateOrderStatusRequest"
              },
              "examples": {
                "blockchainConfirming": {
                  "summary": "Bước 2: Xác nhận On-Chain",
                  "value": { "status": "BLOCKCHAIN_CONFIRMING" }
                },
                "payoutNapas": {
                  "summary": "Bước 3: Chuyển khoản Napas 24/7",
                  "value": { "status": "PAYOUT_NAPAS" }
                },
                "completed": {
                  "summary": "Bước 4: Hoàn tất giao dịch",
                  "value": { "status": "COMPLETED" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Cập nhật trạng thái đơn hàng thành công",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "message": { "type": "string" },
                    "order": { "$ref": "#/components/schemas/Order" }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Không tìm thấy đơn hàng",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Order": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "example": "FTC-MTZ8V3GR-83FM" },
          "orderId": { "type": "string", "example": "FTC-MTZ8V3GR-83FM" },
          "type": { "type": "string", "example": "FEATURE_DEMO" },
          "serviceType": { "type": "string", "example": "FEATURE_DEMO" },
          "serviceName": { "type": "string", "example": "Nạp tiền điện thoại" },
          "serviceTitle": { "type": "string", "example": "Nạp tiền điện thoại" },
          "crypto": { "type": "string", "example": "USDT" },
          "cryptoToken": { "type": "string", "example": "USDT" },
          "cryptoAmount": { "type": "number", "example": 3.93 },
          "vndAmount": { "type": "number", "example": 100000 },
          "exchangeRate": { "type": "number", "example": 25450 },
          "rate": { "type": "number", "example": 25450 },
          "bankCode": { "type": "string", "example": "MB" },
          "recipientBank": { "type": "string", "example": "MB" },
          "bankAccount": { "type": "string", "example": "FTCPAY-TOPUP" },
          "recipientAccount": { "type": "string", "example": "FTCPAY-TOPUP" },
          "accountName": { "type": "string", "example": "DICH VU TOPUP" },
          "recipientName": { "type": "string", "example": "DICH VU TOPUP" },
          "recipientInfo": { "type": "string", "example": "Viettel | 0988 123 456" },
          "customerPhone": { "type": "string", "example": "Viettel | 0988 123 456" },
          "billCode": { "type": "string", "example": "" },
          "depositAddress": { "type": "string", "example": "TXfiotechPay99x8kL2mQp4a7ZbC3dE1fG" },
          "vietQrUrl": { "type": "string", "example": "https://img.vietqr.io/image/MB-FTCPAY-TOPUP-compact2.png?amount=100000&addInfo=FTC-MTZ8V3GR-83FM" },
          "status": {
            "type": "string",
            "enum": ["PENDING_CRYPTO", "BLOCKCHAIN_CONFIRMING", "PAYOUT_NAPAS", "COMPLETED"],
            "example": "PENDING_CRYPTO"
          },
          "statusLabel": { "type": "string", "example": "Chờ nạp tiền Crypto" },
          "txHash": { "type": "string", "nullable": true, "example": "0x4a9b2d8e7c1f" },
          "napasRef": { "type": "string", "nullable": true, "example": "NAPAS-98271039" },
          "createdAt": { "type": "string", "format": "date-time", "example": "2026-09-13T03:18:21.771Z" },
          "updatedAt": { "type": "string", "format": "date-time", "example": "2026-09-13T03:18:21.772Z" }
        }
      },
      "CreateOrderRequest": {
        "type": "object",
        "required": ["vndAmount"],
        "properties": {
          "type": { "type": "string", "example": "FEATURE_DEMO" },
          "serviceName": { "type": "string", "example": "Nạp tiền điện thoại" },
          "cryptoToken": { "type": "string", "enum": ["USDT", "BTC", "ETH", "BNB"], "default": "USDT" },
          "cryptoAmount": { "type": "number", "example": 3.93 },
          "vndAmount": { "type": "number", "example": 100000 },
          "rate": { "type": "number", "example": 25450 },
          "bankCode": { "type": "string", "example": "MB" },
          "bankAccount": { "type": "string", "example": "FTCPAY-TOPUP" },
          "accountName": { "type": "string", "example": "DICH VU TOPUP" },
          "recipientInfo": { "type": "string", "example": "Viettel | 0988 123 456" }
        }
      },
      "UpdateOrderStatusRequest": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": ["PENDING_CRYPTO", "BLOCKCHAIN_CONFIRMING", "PAYOUT_NAPAS", "COMPLETED"],
            "example": "BLOCKCHAIN_CONFIRMING"
          },
          "nextStatus": {
            "type": "string",
            "enum": ["PENDING_CRYPTO", "BLOCKCHAIN_CONFIRMING", "PAYOUT_NAPAS", "COMPLETED"],
            "example": "COMPLETED"
          }
        }
      },
      "HealthResponse": {
        "type": "object",
        "properties": {
          "status": { "type": "string", "example": "ok" },
          "latencyMs": { "type": "integer", "example": 12 },
          "ping": { "type": "string", "example": "PONG" },
          "redis": {
            "type": "object",
            "properties": {
              "isMock": { "type": "boolean", "example": false },
              "connected": { "type": "boolean", "example": true },
              "provider": { "type": "string", "example": "Vercel KV / Upstash Redis" },
              "endpoint": { "type": "string", "example": "https://...upstash.io" }
            }
          },
          "totalOrders": { "type": "integer", "example": 5 },
          "timestamp": { "type": "string", "format": "date-time" }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": false },
          "message": { "type": "string", "example": "Không tìm thấy đơn hàng" }
        }
      }
    }
  }
}