Đăng ký quyền truy cập sớm

Nhập tên và địa chỉ email công việc của bạn. Chúng tôi sẽ gửi liên kết để xác nhận yêu cầu truy cập Tajo.

Trên trang này

Hướng dẫn tích hợp Shopify

Tajo kết nối Shopify với Brevo ở hai nơi. Ứng dụng Tajo Shopify biến các webhook Shopify thành thao tác ghi vào Brevo ngay khi chúng đến. Quy tắc đồng bộ, do tác nhân xây dựng và một người phê duyệt, chuyển bản ghi vào Brevo theo lịch. Trang này trình bày cả hai, sau đó là các công cụ Shopify mà Tajo cung cấp qua MCP.

Điều kiện tiên quyết

Trước khi bắt đầu tích hợp, hãy đảm bảo bạn có:

Cửa hàng Shopify trên bất kỳ gói nào (Basic, Shopify, Advanced hoặc Plus)
Tài khoản Tajo (Tajo đang trong giai đoạn early access)
Tài khoản Brevo, đích đến của việc đồng bộ
Quyền quản trị trên cửa hàng Shopify của bạn

Bước 1: Kết nối cửa hàng Shopify của bạn

Tajo đang trong giai đoạn early access. Ứng dụng Shopify không được liệt kê trên Shopify App Store và không có liên kết tự cài đặt. Liên hệ nhóm để được thiết lập. Khi không gian làm việc Tajo của bạn đã sẵn sàng:

Trong Tajo, mở Connections.
Nhập tên miền myshopify.com của cửa hàng và chọn Connect Shopify. Shopify hiển thị các phạm vi quyền mà Tajo yêu cầu và đưa bạn trở lại Tajo khi bạn chấp thuận.
Xem mỗi phạm vi quyền dùng để làm gì, và Tajo ghi gì ngược lại Shopify, trong Giải thích các quyền Shopify.

Bước 2: Ứng dụng Tajo Shopify gửi gì sang Brevo

Ứng dụng xác minh từng webhook Shopify, lưu lại, đưa vào hàng đợi và xử lý ngay. Các chủ đề khách hàng và sản phẩm chờ khoảng bốn giây trước. Không có khung thời gian xử lý theo lô. Một tác vụ thất bại sẽ được thử lại với thời gian chờ tăng dần.

Chủ đề webhook

Ứng dụng Tajo Shopify đăng ký các chủ đề webhook Shopify sau:

Chủ đề webhook	Mục đích
`customers/create`, `customers/update`, `customers/delete`	Giữ các liên hệ Brevo luôn cập nhật
`orders/create`, `orders/updated`, `orders/fulfilled`, `orders/cancelled`	Sự kiện đơn hàng và chỉ số đơn hàng cho Brevo
`orders/paid`, `refunds/create`	Cộng và trừ điểm khách hàng thân thiết
`checkouts/create`, `checkouts/update`	Khôi phục giỏ thanh toán bị bỏ trong Brevo
`products/create`, `products/update`, `products/delete`	Giữ danh mục sản phẩm trong Brevo luôn cập nhật
`inventory_levels/update`	Giữ tồn kho sản phẩm trong Brevo luôn cập nhật
`collections/create`, `collections/update`, `collections/delete`	Giữ các bộ sưu tập luôn cập nhật
`companies/`, `company_contacts/`, `company_locations/*` (create, update, delete)	Đồng bộ công ty B2B
`app/uninstalled`, `app/scopes_update`, `app_subscriptions/update`	Vòng đời ứng dụng

Các webhook quyền riêng tư bắt buộc của Shopify (yêu cầu dữ liệu khách hàng, xóa dữ liệu khách hàng, xóa dữ liệu cửa hàng) cũng được xử lý. Ứng dụng không đăng ký carts/*. Giỏ hàng bị bỏ đến từ các chủ đề checkouts/*.

Những gì đến được Brevo:

Sự kiện Shopify	Trong Brevo
Khách hàng được tạo hoặc cập nhật	Liên hệ được tạo hoặc cập nhật với tên, email và trạng thái đồng ý nhận marketing. Trên các gói trả phí, ứng dụng thêm thẻ, số đơn hàng, số tiền đã chi và đơn hàng gần nhất.
Khách hàng bị xóa	Liên hệ bị hủy đăng ký, không bị xóa
Đơn hàng được tạo, cập nhật, thanh toán, hoàn tất hoặc hủy	Đơn hàng qua API đơn hàng của Brevo, cùng các sự kiện `order_paid`, `order_completed` và `order_cancelled`
Hoàn tiền được tạo	Sự kiện `order_refunded`. Nếu bạn chạy chương trình khách hàng thân thiết Brevo qua Tajo, điểm sẽ bị trừ theo tỷ lệ tương ứng.
Đơn hàng được thanh toán, có chương trình khách hàng thân thiết Brevo	Cộng điểm theo tỷ lệ điểm trên mỗi đô la của bạn
Thanh toán được tạo hoặc cập nhật, có email và sản phẩm	Các sự kiện `cart_updated` và `cart_abandoned`. Tự động hóa Brevo của bạn quyết định khi nào gửi.
Sản phẩm hoặc bộ sưu tập được tạo, cập nhật hoặc xóa	Danh mục sản phẩm và danh mục phân loại của Brevo
Mức tồn kho được cập nhật	Tồn kho của sản phẩm trong danh mục Brevo. Khi một biến thể chuyển từ 0 lên trên 0, mỗi người mua đã yêu cầu được thông báo nhận một sự kiện `back_in_stock`, một lần cho mỗi đợt nhập lại hàng.

Ứng dụng không thêm nút “Notify me” vào giao diện cửa hàng của bạn. Yêu cầu thông báo khi có hàng lại phải đến từ storefront của bạn, ví dụ từ một nút bạn tự thêm.

Dữ liệu hiện có

Khi cài đặt, ứng dụng nhập các khách hàng hiện có của bạn thành liên hệ Brevo. Đồng bộ toàn bộ dữ liệu lịch sử được khởi chạy từ trang đồng bộ của ứng dụng. Trên các gói trả phí, ứng dụng cũng nhập sản phẩm, bộ sưu tập, công ty và đơn hàng.

Bước 3: Xây dựng quy tắc đồng bộ với tác nhân

Quy tắc đồng bộ là định nghĩa khai báo của một lần đồng bộ: một tài nguyên nguồn, một hành động Brevo, một ánh xạ trường và một bộ lọc. Bạn không viết nó bằng tay. Bạn mô tả, tác nhân xây dựng, và một người phê duyệt.

Trong Tajo, mở Agents và yêu cầu Brevo Integration Architect thực hiện việc đồng bộ bằng ngôn ngữ thông thường. Ví dụ: “Gửi các khách hàng Shopify đã đồng ý nhận email marketing sang Brevo dưới dạng liên hệ.”
Tác nhân kiểm tra connector Shopify. Mẫu dữ liệu của nó trả về tên trường và kiểu dữ liệu, không bao giờ trả về giá trị của khách hàng.
Tác nhân đề xuất một quy tắc với ánh xạ trường và bộ lọc, sau đó xác thực ánh xạ trường với hành động Brevo và chạy thử khô bản nháp. Không bước nào đọc bản ghi khách hàng.
Tác nhân lưu quy tắc dưới dạng bản nháp. Bạn cũng có thể bắt đầu từ một mẫu trong Connections > Syncs and mappings > New sync from template.
Request publish approval chạy bản xem trước trên cửa hàng của bạn. Bản xem trước đọc tối đa 10 bản ghi, không ghi gì vào Brevo và không di chuyển con trỏ. Nó chỉ ghi lại số lượng: bản ghi đã lấy, đủ điều kiện, đã ánh xạ và bị bộ lọc loại bỏ, cùng các lỗi ánh xạ. Nếu bản xem trước thất bại, không có yêu cầu phê duyệt nào được tạo.
Một người phê duyệt yêu cầu trên trang Approvals, kèm lý do bằng văn bản. Phê duyệt gắn với mã băm SHA-256 của quy tắc và hết hạn sau 30 phút. Trang quy tắc sau đó hiển thị Publish approved version.

Chỉnh sửa một quy tắc đã xuất bản sẽ đưa nó về bản nháp. Quy tắc phải qua lại bước xem trước và phê duyệt trước khi chạy lại.

Một quy tắc thực tế

Đây là mẫu Shopify customers -> Brevo contacts đúng như Tajo định nghĩa:

sourceSlug: "shopify",
sourceResource: "customers",
destinationSlug: "brevo",
destinationAction: "upsert_contact",
fieldMap: [
  { source: "email", destination: "email", transform: "toLowerCase" },
  { source: "first_name", destination: "attributes.FIRSTNAME" },
  { source: "last_name", destination: "attributes.LASTNAME" },
  { source: "phone", destination: "attributes.PHONE" },
  { source: "total_spent", destination: "attributes.TOTAL_SPENT", transform: "toNumber" },
  { source: "orders_count", destination: "attributes.ORDERS_COUNT", transform: "toNumber" },
  { source: "tajo_email_marketing_consent", destination: "attributes.OPT_IN", transform: "toBoolean" },
  { source: "tags", destination: "attributes.SHOPIFY_TAGS" },
  { source: "id", destination: "attributes.SHOPIFY_ID", transform: "toString" },
  { source: "created_at", destination: "attributes.SHOPIFY_CREATED_AT" },
  { source: "updated_at", destination: "attributes.SHOPIFY_UPDATED_AT" },
],
filterExpression:
  "($json.tajo_email_marketing_consent === true) && ($json.tajo_email_suppressed === false)",

Bộ lọc chính là bước kiểm tra sự đồng ý. Tajo suy ra cả hai giá trị từ email_marketing_consent.state của Shopify, hoặc từ cờ cũ accepts_marketing. Một quy tắc ghi liên hệ vào Brevo không thể được xuất bản nếu thiếu bộ lọc này. Mẫu Shopify còn lại, Shopify orders → Brevo orders, ghi đơn hàng vào Brevo cho những người mua đã đồng ý nhận marketing khi thanh toán.

Khi nào quy tắc chạy

Quy tắc đồng bộ liên hệ mặc định chạy mỗi 15 phút. Mỗi lần chạy bắt đầu từ con trỏ của quy tắc.
Trang của một quy tắc đang hoạt động có nút Test run (1 batch).
Một quy tắc Shopify orders → Brevo orders đang hoạt động và đã xuất bản cũng chạy mỗi 15 phút. Lần chạy theo lịch đầu tiên bắt đầu vài phút trước thời điểm đó và không gửi các đơn hàng cũ hơn. Mỗi lần chạy sau đó gửi các đơn hàng được cập nhật kể từ lần chạy trước.
Đơn hàng cũ chỉ đến Brevo khi bạn tự chạy quy tắc: bằng Test run (1 batch), hoặc yêu cầu tác nhân Sync Operator chạy nó.
Quy tắc đơn hàng chỉ chạy theo lịch khi dùng bộ lọc đồng ý nhận marketing của người mua theo mẫu. Quy tắc có bộ lọc đã bị chỉnh sửa chỉ chạy khi bạn khởi chạy nó.
Sau năm lần chạy thất bại liên tiếp, quy tắc tự tạm dừng và trang của nó hiển thị lỗi gần nhất. Hãy khắc phục nguyên nhân, rồi xuất bản lại.

Mỗi lần chạy được liệt kê trong lịch sử chạy của quy tắc, với số bản ghi đã đọc, đã ghi và thất bại, cùng thời lượng chạy.

Connector Shopify đọc và ghi những gì

Quy tắc đồng bộ chỉ ghi vào đích, ở đây là Brevo. Chúng không bao giờ ghi vào Shopify.

Ứng dụng Tajo Shopify yêu cầu 12 phạm vi quyền và thực hiện một danh sách ngắn các thao tác ghi vào Shopify, chẳng hạn như từ chối nhận marketing và thẻ khách hàng thân thiết. Giải thích các quyền Shopify liệt kê mọi phạm vi quyền và mọi thao tác ghi, cùng điều gì kích hoạt chúng.

Tác nhân và máy chủ MCP truy cập cửa hàng qua connector Shopify:

Đọc	Ghi
Thông tin cửa hàng, khách hàng (liệt kê và tìm kiếm), đơn hàng, sản phẩm, metafield khách hàng, mức tồn kho, trạng thái xuất dữ liệu hàng loạt	Metafield khách hàng và thẻ khách hàng, và khởi chạy xuất dữ liệu hàng loạt. Mỗi thao tác ghi được chuẩn bị dưới dạng đề xuất và chỉ chạy sau khi được phê duyệt.

Connector cũng khai báo thao tác điều chỉnh tồn kho. Thao tác này cần phạm vi quyền write_inventory, mà ứng dụng Tajo Shopify không yêu cầu.

Bước 4: Dùng các công cụ Shopify qua MCP

Tajo cung cấp connector Shopify dưới dạng máy chủ MCP tại https://alto.tajo.io/mcp/connectors/shopify. Thêm nó vào Claude Code:

claude mcp add --transport http tajo-shopify https://alto.tajo.io/mcp/connectors/shopify

Máy chủ MCP phát hiện máy chủ OAuth của Tajo và mở trang đăng nhập Tajo. Quyền truy cập chỉ dành cho các tài khoản early access. Máy chủ cung cấp 12 công cụ:

Công cụ	Chức năng
`preview_tajo_shopify_app`	Bản xem trước tương tác của ứng dụng Tajo Shopify, hiển thị dưới dạng MCP UI
`get_shop`	Thông tin của cửa hàng
`search_customers`	Tìm khách hàng bằng cú pháp truy vấn Shopify, chẳng hạn `tag:tajo-vip` hoặc `total_spent:>100`
`list_customers`	Liệt kê khách hàng, có phân trang
`list_orders`	Liệt kê đơn hàng, có phân trang
`list_products`	Liệt kê sản phẩm cùng biến thể, hình ảnh và tồn kho
`get_customer_metafields`	Đọc metafield của một khách hàng
`get_inventory_levels`	Đọc tồn kho của một biến thể tại các địa điểm
`poll_bulk_export`	Kiểm tra một lần xuất dữ liệu hàng loạt và lấy liên kết tải xuống khi hoàn tất
`calculate_rewards_profile`	Tính hạng, điểm và số dư phần thưởng của khách hàng từ dữ liệu thương mại đã đồng bộ
`shopify_propose`	Chuẩn bị một thao tác ghi Shopify dưới dạng đề xuất. Không có gì được gửi đi.
`shopify_apply`	Chạy một đề xuất đã được phê duyệt

Khắc phục sự cố

Liên hệ không xuất hiện trong Brevo: xem liên hệ bị thiếu trong Brevo.
Quy tắc không chạy hoặc tự tạm dừng: xem dữ liệu không đồng bộ.

Bước tiếp theo

Hiểu về đồng bộ dữ liệu, cách quy tắc đồng bộ hoạt động
Giải thích các quyền Shopify, mọi phạm vi quyền và mọi thao tác ghi
Shopify + Brevo, hướng dẫn tích hợp
Liên hệ nhóm để được thiết lập