{"how_to_call":"GET /v1/data/<id>?<params> with header \"Authorization: Bearer <access_token>\" (token from the shared login id.hvholdings.vn). Every registered app may call every API; each user only sees data their own HV Admin account is allowed to see.","errors":{"401":"code=refresh → refresh the token (POST /v1/token { app, refresh_token }) then retry once · code=relogin → send the user to the login page","403":"API disabled / app paused / account has no permission at the source","429":"too many calls — wait retry_after seconds","502":"source is down — retry later"},"note":"Columns not listed for an API may appear when the source adds new fields — ignore unknown columns.","apis":[{"id":"profile","name":"Tài khoản","description":"Thông tin tài khoản HV Admin của chính người đang đăng nhập: mã, tên đăng nhập, họ tên, email, số điện thoại, ảnh, tình trạng. Luôn trả 1 dòng — không xem được tài khoản người khác.","source":"HV Admin","version":1,"path":"/v1/data/profile","params":[],"max_page_size":1,"columns":[{"name":"id","type":"string","description":"Mã tài khoản trong HV Admin (UUID)"},{"name":"userName","type":"string","description":"Tên đăng nhập"},{"name":"firstName","type":"string","description":"Tên"},{"name":"lastName","type":"string","description":"Họ (và tên đệm)"},{"name":"email","type":"string","description":"Email"},{"name":"isActive","type":"boolean","description":"Tài khoản còn hoạt động"},{"name":"emailConfirmed","type":"boolean","description":"Email đã xác nhận"},{"name":"phoneNumber","type":"string","description":"Số điện thoại"},{"name":"imageUrl","type":"string","description":"Địa chỉ ảnh đại diện"},{"name":"twoFactorEnabled","type":"boolean","description":"Đã bật xác thực 2 lớp"}],"example":{"api":"profile","version":1,"page":1,"has_more":false,"count":1,"rows":[{"id":"string","userName":"string","firstName":"string","lastName":"string","email":"string","isActive":"boolean","emailConfirmed":"boolean","phoneNumber":"string","imageUrl":"string","twoFactorEnabled":"boolean"}]}},{"id":"markets","name":"Thị trường","description":"Các thị trường (nước bán) mà tài khoản đang đăng nhập được kinh doanh. HV Admin tự lọc theo tài khoản — mỗi người thấy danh sách của mình. Dùng làm ô chọn thị trường và làm mã thị trường khi gọi các API khác.","source":"HV Admin","version":1,"path":"/v1/data/markets","params":[{"name":"page","required":false,"description":"Trang muốn lấy, bắt đầu từ 1 (mặc định 1)"},{"name":"page_size","required":false,"description":"Số dòng mỗi trang (mặc định 50)"}],"max_page_size":200,"columns":[{"name":"value","type":"string","description":"Mã thị trường trong HV Admin (UUID) — dùng mã này khi lọc theo thị trường"},{"name":"label","type":"string","description":"Tên thị trường, VD \"Việt Nam\", \"Mỹ\""},{"name":"hint","type":"string","description":"Mã viết tắt, VD \"VN\", \"USA\", \"AU\""},{"name":"parentValue","type":"string","description":"Mã thị trường cha (trống nếu không có)"}],"example":{"api":"markets","version":1,"page":1,"has_more":false,"count":1,"rows":[{"value":"string","label":"string","hint":"string","parentValue":"string"}]}},{"id":"marketing-performance","name":"Doanh số marketing","description":"Doanh số, chi phí marketing, giá vốn, lợi nhuận và tình trạng đơn theo từng nhân sự marketing × thị trường trong 1 khoảng ngày. HV Admin tự lọc theo tài khoản — mỗi người thấy phần mình được xem. Số tiền theo đơn vị ở tham số currency.","source":"HV Admin","version":1,"path":"/v1/data/marketing-performance","params":[{"name":"from","required":true,"description":"Từ ngày, dạng YYYY-MM-DD"},{"name":"to","required":true,"description":"Đến ngày, dạng YYYY-MM-DD (tối đa 92 ngày mỗi lượt)"},{"name":"date_type","required":false,"description":"Lọc theo loại ngày: Created = ngày tạo đơn (mặc định, hiện chỉ có loại này)"},{"name":"currency","required":false,"description":"Đơn vị tiền: Vnd (mặc định, hiện chỉ có loại này)"},{"name":"page","required":false,"description":"Trang muốn lấy, bắt đầu từ 1 (mặc định 1)"},{"name":"page_size","required":false,"description":"Số dòng mỗi trang (mặc định 50)"}],"max_page_size":200,"columns":[{"name":"marketerEmployeeId","type":"string","description":"Mã nhân sự marketing"},{"name":"marketerName","type":"string","description":"Tên nhân sự marketing"},{"name":"marketId","type":"string","description":"Mã thị trường (khớp cột value của API markets)"},{"name":"marketName","type":"string","description":"Tên thị trường"},{"name":"orgUnitCode","type":"string","description":"Mã đơn vị / phòng ban trong sơ đồ tổ chức"},{"name":"structurePath","type":"string","description":"Đường dẫn trong sơ đồ tổ chức (đơn vị cha → con)"},{"name":"orderCount","type":"number","description":"Số đơn (chưa xác nhận: tổng đơn tạo trong kỳ)"},{"name":"confirmedOrders","type":"number","description":"Số đơn đã chốt"},{"name":"actualRevenue","type":"number","description":"Doanh thu thực nhận (chưa xác nhận định nghĩa; thị trường Mỹ từng trả 0)"},{"name":"gmvAfterDiscount","type":"number","description":"GMV sau giảm giá"},{"name":"revenue","type":"number","description":"Doanh thu"},{"name":"totalMarketingCost","type":"number","description":"Tổng chi phí marketing"},{"name":"partnerFee","type":"number","description":"Phí đối tác (vận chuyển / sàn)"},{"name":"partnerFeeRatioOnGmvAfterDiscount","type":"number","description":"Phí đối tác / GMV sau giảm giá (tỉ lệ)"},{"name":"partnerFeeRatioOnRevenue","type":"number","description":"Phí đối tác / doanh thu (tỉ lệ)"},{"name":"productCogs","type":"number","description":"Giá vốn sản phẩm bán"},{"name":"productCogsRatioOnGmvAfterDiscount","type":"number","description":"Giá vốn sản phẩm / GMV sau giảm giá (tỉ lệ)"},{"name":"productCogsRatioOnRevenue","type":"number","description":"Giá vốn sản phẩm / doanh thu (tỉ lệ)"},{"name":"productCogsRatioOnCogs","type":"number","description":"Giá vốn sản phẩm / tổng giá vốn (tỉ lệ)"},{"name":"giftCogs","type":"number","description":"Giá vốn quà tặng"},{"name":"giftCogsRatioOnGmvAfterDiscount","type":"number","description":"Giá vốn quà tặng / GMV sau giảm giá (tỉ lệ)"},{"name":"giftCogsRatioOnRevenue","type":"number","description":"Giá vốn quà tặng / doanh thu (tỉ lệ)"},{"name":"giftCogsRatioOnCogs","type":"number","description":"Giá vốn quà tặng / tổng giá vốn (tỉ lệ)"},{"name":"cogs","type":"number","description":"Tổng giá vốn (sản phẩm + quà tặng)"},{"name":"cogsRatioOnGmvAfterDiscount","type":"number","description":"Tổng giá vốn / GMV sau giảm giá (tỉ lệ)"},{"name":"cogsRatioOnRevenue","type":"number","description":"Tổng giá vốn / doanh thu (tỉ lệ)"},{"name":"expectedProfit","type":"number","description":"Lợi nhuận dự kiến"},{"name":"expectedProfitRatioOnGmvAfterDiscount","type":"number","description":"Lợi nhuận dự kiến / GMV sau giảm giá (tỉ lệ)"},{"name":"expectedProfitRatioOnRevenue","type":"number","description":"Lợi nhuận dự kiến / doanh thu (tỉ lệ)"},{"name":"netProfit","type":"number","description":"Lợi nhuận ròng"},{"name":"netProfitRatioOnGmvAfterDiscount","type":"number","description":"Lợi nhuận ròng / GMV sau giảm giá (tỉ lệ)"},{"name":"netProfitRatioOnRevenue","type":"number","description":"Lợi nhuận ròng / doanh thu (tỉ lệ)"},{"name":"performance","type":"number","description":"Hiệu suất (chưa xác nhận công thức)"},{"name":"marketingCostRatioOnGmvAfterDiscount","type":"number","description":"Chi phí marketing / GMV sau giảm giá (tỉ lệ)"},{"name":"marketingCostRatioOnRevenue","type":"number","description":"Chi phí marketing / doanh thu (tỉ lệ)"},{"name":"roasOnGmvAfterDiscount","type":"number","description":"ROAS tính trên GMV sau giảm giá"},{"name":"roasOnRevenue","type":"number","description":"ROAS tính trên doanh thu"},{"name":"roasOffPlatform","type":"number","description":"ROAS ngoài nền tảng (chưa xác nhận định nghĩa)"},{"name":"confirmedAov","type":"number","description":"Giá trị trung bình 1 đơn đã chốt"},{"name":"confirmedAovOnRevenue","type":"number","description":"Giá trị trung bình 1 đơn đã chốt, tính trên doanh thu"},{"name":"totalOrders","type":"number","description":"Tổng số đơn (mọi trạng thái)"},{"name":"processing","type":"number","description":"Số đơn đang xử lý"},{"name":"confirmed","type":"number","description":"Số đơn đã xác nhận"},{"name":"cancelled","type":"number","description":"Số đơn đã huỷ"},{"name":"waitingShipment","type":"number","description":"Số đơn chờ gửi hàng"},{"name":"shipping","type":"number","description":"Số đơn đang giao"},{"name":"delivered","type":"number","description":"Số đơn đã giao"},{"name":"returned","type":"number","description":"Số đơn hoàn"},{"name":"cancelledAfterFinalized","type":"number","description":"Số đơn huỷ sau khi đã chốt"},{"name":"productCount","type":"number","description":"Số sản phẩm"}],"example":{"api":"marketing-performance","version":1,"page":1,"has_more":false,"count":1,"rows":[{"marketerEmployeeId":"string","marketerName":"string","marketId":"string","marketName":"string","orgUnitCode":"string","structurePath":"string","orderCount":"number","confirmedOrders":"number","actualRevenue":"number","gmvAfterDiscount":"number","revenue":"number","totalMarketingCost":"number","partnerFee":"number","partnerFeeRatioOnGmvAfterDiscount":"number","partnerFeeRatioOnRevenue":"number","productCogs":"number","productCogsRatioOnGmvAfterDiscount":"number","productCogsRatioOnRevenue":"number","productCogsRatioOnCogs":"number","giftCogs":"number","giftCogsRatioOnGmvAfterDiscount":"number","giftCogsRatioOnRevenue":"number","giftCogsRatioOnCogs":"number","cogs":"number","cogsRatioOnGmvAfterDiscount":"number","cogsRatioOnRevenue":"number","expectedProfit":"number","expectedProfitRatioOnGmvAfterDiscount":"number","expectedProfitRatioOnRevenue":"number","netProfit":"number","netProfitRatioOnGmvAfterDiscount":"number","netProfitRatioOnRevenue":"number","performance":"number","marketingCostRatioOnGmvAfterDiscount":"number","marketingCostRatioOnRevenue":"number","roasOnGmvAfterDiscount":"number","roasOnRevenue":"number","roasOffPlatform":"number","confirmedAov":"number","confirmedAovOnRevenue":"number","totalOrders":"number","processing":"number","confirmed":"number","cancelled":"number","waitingShipment":"number","shipping":"number","delivered":"number","returned":"number","cancelledAfterFinalized":"number","productCount":"number"}]}}]}