Merchant API phiên bản v1beta đã ngừng hoạt động và ngừng cung cấp từ ngày 28 tháng 2 năm 2026. Để biết các bước chuyển đổi sang phiên bản ổn định mới nhất, hãy xem phần Di chuyển từ v1beta sang v1.

Lệnh gọi API trực tiếp

Trong phương pháp tương tác với Merchant API này, hãy trực tiếp đưa ra các yêu cầu thô đến các điểm cuối của API, thường là qua HTTP(S). Bạn phải tự xử lý các khía cạnh như tạo nội dung yêu cầu, đặt tiêu đề (bao gồm cả quy trình xác thực) và phân tích cú pháp phản hồi.

Bước 1. Đăng ký làm nhà phát triển

Để sử dụng Merchant API, bạn phải đăng ký thông tin liên hệ của nhà phát triển.

Quy trình đăng ký sẽ thực hiện những việc sau:

Tạo một người liên hệ kỹ thuật cho tài khoản Merchant Center của bạn bằng cách chỉ định vai trò API developer cho một người dùng. Việc này cho phép Google gửi các thông tin cập nhật quan trọng, đặc biệt là về API và các tính năng mà nhà phát triển đang sử dụng, chẳng hạn như thông báo về dịch vụ và thông tin về các tính năng mới. Những thông tin này có thể không hữu ích đối với những người không phải là nhà phát triển.
Cho phép bạn làm việc với nhiều tài khoản người bán mà không cần đăng ký nhiều lần. Khi bạn đăng ký, mã dự án trên đám mây Google Cloud dùng để xác thực với Merchant API sẽ được liên kết với tài khoản Merchant Center của bạn. Tài khoản này có người liên hệ kỹ thuật (API developer). Bằng cách này, bạn có thể nhận được các thông tin cập nhật quan trọng cho tất cả tài khoản người bán mà bạn quản lý miễn là bạn xác thực bằng dự án trên đám mây của Google đã đăng ký.

Khi đăng ký, hãy tuân thủ các điều kiện tiên quyết và hạn chế được nêu chi tiết trong phần Đăng ký.

Để đăng ký bằng phương thức developerRegistration.registerGcp, bạn có thể bắt đầu với ví dụ này, thay thế {DEVELOPER_EMAIL} bằng địa chỉ email thích hợp trong nội dung yêu cầu.

POST https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/developerRegistration:registerGcp

{
  "developerEmail": "{DEVELOPER_EMAIL}"
}

Một lệnh gọi thành công sẽ trả về tài nguyên DeveloperRegistration, xác nhận mối liên kết giữa dự án và tài khoản của bạn.

{
  "name": "accounts/{ACCOUNT_ID}/developerRegistration",
  "gcpIds": [
    "123456789012345"
  ]
}

Bước 2. Quản lý người liên hệ và quyền của nhà phát triển

Khi bạn đăng ký:

Nếu địa chỉ email thuộc về một người dùng trong tài khoản Merchant Center, thì người dùng đó sẽ được cấp vai trò API_DEVELOPER.
Nếu địa chỉ email không thuộc về người dùng hiện có, thì một lời mời sẽ được gửi đến địa chỉ đó. Người nhận phải chấp nhận lời mời để được thêm làm người dùng mới có vai trò API_DEVELOPER.

Sau lần đăng ký ban đầu, bạn nên thêm nhiều nhà phát triển và cấp cho họ các quyền truy cập bổ sung.

Bước 2a. Cấp thêm quyền

Bạn phải có vai trò API_DEVELOPER để nhận các thông báo quan trọng, nhưng vai trò này có quyền tối thiểu trong Merchant Center. Để cho phép người dùng này thực hiện các lệnh gọi API khác hoặc quản lý chế độ cài đặt trong giao diện người dùng Merchant Center, bạn cần cấp cho họ các vai trò bổ sung, chẳng hạn như STANDARD hoặc ADMIN. Để biết thêm thông tin, hãy xem Các loại quyền truy cập.

Bạn có thể cập nhật quyền truy cập của người dùng bằng phương thức accounts.users.patch.

Ví dụ sau đây cho biết cách cập nhật người dùng để cấp cho họ cả vai trò ADMIN và API_DEVELOPER. Việc này cho phép họ quản lý đầy đủ tài khoản và họ cũng sẽ nhận được thông tin liên lạc liên quan đến API.

PATCH https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/users/{DEVELOPER_EMAIL}?update_mask=access_rights

{
  "access_rights": [
    "ADMIN",
    "API_DEVELOPER"
  ]
}

Bước 2b. Thêm nhà phát triển dự phòng

Để ngăn chặn việc quyền truy cập API của bạn bị gián đoạn nếu người liên hệ chính của nhà phát triển rời khỏi tổ chức của bạn, bạn nên thêm ít nhất một nhà phát triển dự phòng.

Bạn có thể thêm người dùng bằng phương thức accounts.users.create hoặc cập nhật người dùng bằng phương thức accounts.users.patch. Bạn nên cấp cho người dùng này cả vai trò ADMIN và API_DEVELOPER.

Bước 3. Tạo nguồn dữ liệu sản phẩm chính

Để chèn một sản phẩm, bạn cần có nguồn dữ liệu sản phẩm chính. Yêu cầu sau đây cho biết cách tạo nguồn dữ liệu mà bạn có thể dùng để chèn một sản phẩm vào tài khoản của mình:

POST https://merchantapi.googleapis.com/datasources/v1/accounts/{ACCOUNT_ID}/dataSources

{
  "primaryProductDataSource": {
    "contentLanguage": "en",
    "countries": [
      "US"
    ],
    "feedLabel": "US"
  },
  "name": "primary-data-source",
  "displayName": "Primary Products Data Source"
}

Thay thế {ACCOUNT_ID} bằng mã của tài khoản Merchant Center mà bạn đã tạo.

Sau khi chạy yêu cầu này thành công, bạn sẽ thấy phản hồi sau:

{
  "name": "accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}",
  "dataSourceId": "{DATASOURCE_ID}",
  "displayName": "Primary Products Data Source",
  "primaryProductDataSource": {
    "feedLabel": "US",
    "contentLanguage": "en",
    "countries": [
      "US"
    ],
    "defaultRule": {
      "takeFromDataSources": [
        {
          "self": true
        }
      ]
    }
  },
  "input": "API"
}

Sao chép giá trị của trường name. Bạn sẽ cần giá trị này để chèn một sản phẩm.

Bạn có thể xem nguồn dữ liệu này trong giao diện người dùng Merchant Center. Để biết thêm thông tin, hãy xem Cách tìm thẻ Nguồn dữ liệu.

Bước 4. Chèn sản phẩm

Sau khi tạo nguồn dữ liệu, hãy thử chèn một sản phẩm vào nguồn dữ liệu đó. Chạy lệnh sau, cung cấp ACCOUNT_ID chính xác. Thay thế {DATASOURCE_NAME} bằng giá trị mà bạn đã sao chép trước đó.

POST https://merchantapi.googleapis.com/products/v1/accounts/{ACCOUNT_ID}/productInputs:insert?dataSource={DATASOURCE_NAME}
{
  "contentLanguage": "en",
  "feedLabel": "US",
  "name": "Red T-shirt",
  "productAttributes": {
    "gender": "MALE",
    "brand": "New brand"
  },
  "offerId": "tshirt-123"
}