Chuyển tới nội dung chính

Onboard Sản Phẩm qua Product Feed API

Tài liệu này dành cho NPT (Third-party / Mini App publisher) muốn đưa dữ liệu trang vào hệ thống VSF Search và Ads Affiliate.

1. Giới thiệu​

Product Feed API là cổng duy nhất để NPT đẩy dữ liệu trang vào hệ thống VSF Search và Ads Affiliate. Sau khi onboard, dữ liệu sẽ:

submit_sitemap

Luồng cơ bản:

NPT gọi API  →  Hệ thống validate  →  Lập chỉ mục (indexing)  →  Xuất hiện trên Search / Ads

Base URL:

Môi trườngURL
Productionhttps://api.v-app.vn/open/product-catalog/v1/public

2. Lấy API Token​

2.1 Tạo token mới​

  1. Đăng nhập vào VSF Console.
  2. Vào Cài Đặt → Tổng Quan → Tạo Mới Token.
  3. Điền thông tin:
TrườngBắt buộcMô tả
Tên TokenKhôngNhãn phân biệt, ví dụ: Product Feed CI/CD
Mô tả tokenCóMô tả mục đích sử dụng
Ngày hết hạnCóTối thiểu 1 ngày, tối đa 1 năm
ScopeCóChọn Product Feed

Scope quan trọng:

  • Product Feed — cho phép token truy cập và quản lý dữ liệu product feed cho search engine. Bắt buộc chọn.
  • Deploy — chỉ dùng cho CI/CD, không cần cho onboarding sản phẩm.

submit_sitemap

  1. Nhấn Tạo Token và lưu token lại ngay — token chỉ hiển thị một lần.

2.2 Sử dụng token​

Truyền token vào mọi request qua header:

X-API-Key: <your-token>

3. Nạp sản phẩm vào hệ thống​

Endpoint​

POST /v1/public/feed/items/batch

Request​

curl -X POST \
  'https://api.v-app.vn/open/product-catalog/v1/public/feed/items/batch' \
  -H 'X-API-Key: <your-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "org_code": "my-org",
    "app_id": "my-app",
    "schema_name": "product_ecom_merchant",
    "payload": {
      "@context": "https://schema.org",
      "@type": "DataFeed",
      "name": "My Product Feed",
      "feed_version": "1.0",
      "inLanguage": "vi-VN",
      "dateModified": "2026-04-23T10:00:00Z",
      "dataFeedElement": [
        {
          "@type": "DataFeedItem",
          "dateModified": "2026-04-23T10:00:00Z",
          "item": {
            "@type": "Product Ecom Merchant",
            "@id": "https://example.vn/products/SKU-001",
            "identifier": "SKU-001",
            "name": "Áo thun cotton cao cấp",
            "brand": { "@type": "Brand", "name": "VinFashion" },
            "category": "Thời trang > Áo",
            "price": 299000,
            "platform": "api",
            "description": "Áo thun cotton 100%, thoáng mát.",
            "image": "https://cdn.example.vn/products/sku-001.jpg",
            "url": "https://shop.example.vn/product/sku-001",
            "sameAs": "vapp://miniapp/shop/product/SKU-001"
          }
        }
      ]
    }
  }'

Các trường body​

TrườngBắt buộcMô tả
org_codeCóMã tổ chức của NPT
app_idCóID ứng dụng Mini App
schema_nameCóTên schema validate dữ liệu (xem Schema Reference)
payloadCóObject DataFeed chứa danh sách sản phẩm
org_nameKhôngTên hiển thị của tổ chức (tuỳ chọn)

Response thành công — 201 Created​

{
  "success": true,
  "data": {
    "task_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "items": ["uuid-item-1", "uuid-item-2"]
  }
}
TrườngÝ nghĩa
task_idID của batch — dùng để kiểm tra trạng thái xử lý
itemsDanh sách internal UUID của từng item

Giới hạn batch​

Giới hạnHành vi
≤ 200 sản phẩm và ≤ 500 KBXử lý đồng bộ — sản phẩm sẵn sàng ngay sau response
> 200 sản phẩm hoặc > 500 KBXử lý bất đồng bộ — trả về task_id với trạng thái VERIFYING

Khuyến nghị: Giữ mỗi batch ≤ 100 sản phẩm để dễ theo dõi.

4. Kiểm tra trạng thái nạp​

Sau khi nạp batch lớn (xử lý bất đồng bộ), dùng task_id để kiểm tra:

curl 'https://api.v-app.vn/open/product-catalog/v1/public/feed/tasks/3fa85f64-5717-4562-b3fc-2c963f66afa6' \
  -H 'X-API-Key: <your-token>'

Response:

{
  "success": true,
  "data": {
    "task_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "INDEXED",
    "total_items": 50,
    "indexed_items": 50,
    "failed_items": 0,
    "created_at": "2026-04-23T10:00:00Z",
    "updated_at": "2026-04-23T10:01:30Z"
  }
}

Đợi cho đến khi status chuyển sang INDEXED hoặc FAILED_API_VALIDATION.

5. Cập nhật trạng thái sản phẩm (Hiện/Ẩn)​

Dùng endpoint này để hiển thị hoặc ẩn sản phẩm khỏi kết quả tìm kiếm mà không xoá dữ liệu.

Endpoint​

PATCH /v1/public/feed/items/{partner_item_id}
  • partner_item_id là giá trị trường identifier khi nạp sản phẩm (ví dụ: SKU-001).

Ẩn sản phẩm​

curl -X PATCH \
  'https://api.v-app.vn/open/product-catalog/v1/public/feed/items/SKU-001?in_language=vi-VN' \
  -H 'X-API-Key: <your-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "org_code": "my-org",
    "app_id": "my-app",
    "is_active": false
  }'

Hiển thị lại sản phẩm​

curl -X PATCH \
  'https://api.v-app.vn/open/product-catalog/v1/public/feed/items/SKU-001?in_language=vi-VN' \
  -H 'X-API-Key: <your-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "org_code": "my-org",
    "app_id": "my-app",
    "is_active": true
  }'

Query params​

ParamBắt buộcMô tả
in_languageCóNgôn ngữ của sản phẩm, ví dụ vi-VN

Request body​

TrườngBắt buộcMô tả
org_codeCóMã tổ chức
app_idCóID ứng dụng
is_activeCótrue = hiển thị, false = ẩn

Response thành công — 200 OK​

{
  "success": true,
  "data": {
    "partner_item_id": "SKU-001",
    "is_active": false,
    "status": "INDEXED"
  }
}

Thay đổi is_active được đồng bộ ngay lập tức lên Search index — sản phẩm sẽ ẩn / hiện trong vòng vài giây.

6. Trạng thái sản phẩm​

Trạng tháiÝ nghĩaHành động tiếp theo
ENQUEUEDĐã qua validation, đang chờ lập chỉ mụcĐợi
PROCESSINGĐang được lập chỉ mụcĐợi
INDEXEDĐã lên kết quả tìm kiếmHoàn tất
VERIFYINGBatch lớn — đang xác thực bất đồng bộDùng task_id kiểm tra lại sau
INDEXED_FAILEDLập chỉ mục thất bại (lỗi hệ thống)Liên hệ hỗ trợ
FAILED_API_VALIDATIONPayload không khớp schemaKiểm tra trường failure trong response
CANCELEDĐã bị huỷ (có phiên bản mới hơn thay thế)Bình thường

7. Lỗi thường gặp​

Lỗi HTTP​

Mã HTTPNguyên nhânCách khắc phục
401 UnauthorizedThiếu header X-API-Key hoặc token saiKiểm tra lại token, đảm bảo header đúng
403 ForbiddenToken không có scope Product FeedTạo token mới với scope Product Feed
403 Forbiddenorg_code / app_id không khớp với tokenKiểm tra lại org_code và app_id
404 Not Foundpartner_item_id không tồn tại (khi PATCH)Nạp sản phẩm qua POST batch trước
422 Unprocessable EntityBody thiếu trường bắt buộc hoặc sai kiểu dữ liệuXem message lỗi trong response
500 Internal Server ErrorLỗi hệ thống nội bộThử lại sau; nếu kéo dài liên hệ hỗ trợ

Lỗi validation sản phẩm (HTTP 201 nhưng item thất bại)​

Khi sản phẩm không khớp schema, hệ thống vẫn trả về 201 nhưng item sẽ có trạng thái FAILED_API_VALIDATION. Xem chi tiết lỗi trong trường failure:

{
  "success": true,
  "data": {
    "task_id": "...",
    "items": [],
    "failure": [
      {
        "partner_item_id": "SKU-001",
        "error": "'name' is a required property"
      }
    ]
  }
}

Các lỗi validation hay gặp​

LỗiNguyên nhânCách khắc phục
'name' is a required propertyThiếu trường name trong itemThêm trường name vào item
'identifier' is a required propertyThiếu identifierMỗi item phải có identifier duy nhất
identifier does not match patternidentifier chứa ký tự không hợp lệChỉ dùng a-z A-Z 0-9 _ -, bắt đầu bằng chữ hoặc số
'sameAs' is a required propertyThiếu deep linkThêm sameAs theo định dạng vapp://miniapp/...
'sameAs' does not match deep_link_formatDeep link sai định dạngKiểm tra URL scheme deep link
image: url_connection failedURL ảnh không truy cập đượcĐảm bảo URL ảnh public và trả về 200
price must be >= 0Giá âmTruyền giá ≥ 0
Additional properties are not allowedCó trường không được phép (schema additionalProperties: false)Xoá các trường không có trong schema
'schema_name' not foundTên schema không tồn tạiXem danh sách schema tại Schema Reference
dataFeedElement must have at least 1 itemMảng rỗngGửi ít nhất 1 sản phẩm trong batch

sameAs phải theo chuẩn deep link của VSF Mini App. Ví dụ đúng:

vapp://miniapp/<app_id>/product/SKU-001

Ví dụ sai:

https://example.vn/product/SKU-001   ← đây là URL web, không phải deep link

8. Các trang cần onboard​

Ads Affiliate yêu cầu dữ liệu giá chính xác. Cần đảm bảo các trường sau trước khi onboard:

  • offers.price hoặc offers.lowPrice / offers.highPrice — bắt buộc
  • offers.priceCurrency — bắt buộc ("VND")
  • offers.availability — nên có ("InStock" / "OutOfStock")
  • image — URL ảnh truy cập công khai
  • sameAs — deep link đúng định dạng
  • Url - URL phải đúng với định dạng https quy định

Tài liệu liên quan​