> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xanhcard.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tự động hóa theo sự kiện

> Hướng dẫn tạo quy tắc tự động chạy hành động khi thẻ được tạo, tải xuống, lưu vào ví, quét, gỡ khỏi ví, vô hiệu hoặc hết hạn.

Sau khi làm theo hướng dẫn này, bạn sẽ có một quy tắc tự động chạy hành động — ví dụ đổi ảnh đại diện ngay khi khách lưu thẻ vào ví, hoặc gửi thông báo khi thẻ hết hạn — mà không cần thao tác thủ công.

## Luồng hoạt động

```mermaid theme={null}
flowchart LR
    A["Sự kiện xảy ra<br/>lưu ví, quét, hết hạn..."] --> B["Quy tắc khớp<br/>sự kiện + bộ lọc + điều kiện"]
    B --> C["Hành động<br/>đổi dữ liệu, thông báo..."]
    C --> D["Lịch sử chạy<br/>theo dõi từng lần chạy"]
```

Quy tắc chạy **ngầm, sau khi sự kiện xảy ra** — không làm chậm thao tác của khách hay nhân viên quét. Mỗi lần chạy được ghi lại để bạn kiểm tra.

## Mở trang Tự động hóa

Chọn **Tự động hóa** từ thanh điều hướng bên trái. Trang này liệt kê mọi quy tắc của dự án: tên, sự kiện đã chọn, chế độ kích hoạt, số hành động, cùng nút bật/tắt, **Lịch sử chạy**, **Chỉnh sửa** và xóa.

<img src="https://mintcdn.com/xanhcard/rPjYaFf3KMfDr4-C/images/automations/01-rule-list.png?fit=max&auto=format&n=rPjYaFf3KMfDr4-C&q=85&s=e36fbc2a9a62ddcb9196b6e529d70c57" alt="Danh sách quy tắc tự động hóa" width="3200" height="1752" data-path="images/automations/01-rule-list.png" />

## Tạo quy tắc

Nhấn **Tạo tự động hóa**. Cửa sổ soạn thảo chia hai cột: bên trái là *khi nào chạy* (sự kiện, bộ lọc, đối tượng), bên phải là *làm gì* (hành động).

<img src="https://mintcdn.com/xanhcard/rPjYaFf3KMfDr4-C/images/automations/02-rule-editor.png?fit=max&auto=format&n=rPjYaFf3KMfDr4-C&q=85&s=c8600300c71095d2df849208b837550d" alt="Soạn quy tắc tự động hóa" width="3200" height="1752" data-path="images/automations/02-rule-editor.png" />

<Steps>
  <Step title="Đặt tên và chế độ kích hoạt">
    Nhập **Tên** (ví dụ "Đổi avatar khi lưu ví") và **Mô tả** nếu cần. Ở **Chế độ kích hoạt**, chọn:

    * **Mỗi lần xảy ra** — chạy mỗi khi có sự kiện khớp.
    * **Một lần mỗi pass** — mỗi thẻ chỉ chạy tối đa một lần, dù sau đó còn sự kiện khác.

    Muốn "lần đầu tải **hoặc** lần đầu lưu ví" thì tạo một quy tắc *Một lần mỗi pass* và chọn cả hai sự kiện — sự kiện nào đến trước sẽ kích hoạt, sự kiện sau bị bỏ qua.
  </Step>

  <Step title="Chọn sự kiện">
    Trong mục **Khi các sự kiện này xảy ra**, tick các sự kiện bạn muốn. Sự kiện chia ba nhóm, và nhóm quyết định những hành động nào được dùng:

    | Nhóm | Sự kiện | Hành động cho phép |
    | - | - | - |
    | Vòng đời pass | Pass được tạo, Pass được tải, Đã lưu vào thiết bị, Đã xóa khỏi thiết bị | Đầy đủ |
    | Tương tác | Pass được quét | Đầy đủ, trừ Tăng/Giảm giá trị (việc cộng điểm thuộc về cấu hình máy quét) |
    | Kết thúc | Pass bị vô hiệu, Pass hết hạn | Chỉ Gửi thông báo và Gọi webhook |
  </Step>

  <Step title="Lọc sự kiện (tùy chọn)">
    Tùy sự kiện đã chọn, mục **Bộ lọc sự kiện** sẽ hiện thêm:

    * **Nền tảng** — chỉ Apple Wallet hoặc chỉ Google Wallet.
    * **Kết quả quét** — chỉ lượt quét thành công hoặc chỉ lượt quét bị từ chối (ví dụ quét thẻ đã vô hiệu).
    * **Máy quét** — chỉ một số máy quét (nhập ID, cách nhau bằng dấu phẩy).
  </Step>

  <Step title="Chọn đối tượng">
    Trong mục **Đối tượng**, chọn **Tất cả pass** để áp dụng cho mọi thẻ, hoặc **Điều kiện** để chỉ áp dụng cho thẻ khớp điều kiện — ví dụ chỉ hạng Vàng.

    <img src="https://mintcdn.com/xanhcard/rPjYaFf3KMfDr4-C/images/automations/03-segment-conditions.png?fit=max&auto=format&n=rPjYaFf3KMfDr4-C&q=85&s=3bcd2e942cfee9aa4910e568f724b9f4" alt="Điều kiện lọc thẻ" width="3200" height="1752" data-path="images/automations/03-segment-conditions.png" />

    Điều kiện gộp theo nhóm với **AND** (mọi điều kiện trong nhóm đều đúng) hoặc **OR** (chỉ cần một điều kiện đúng), và **Khớp TẤT CẢ nhóm** / **Khớp BẤT KỲ nhóm nào** để kết hợp các nhóm. Xóa hết nhóm sẽ đưa quy tắc về *Tất cả pass*.
  </Step>

  <Step title="Thêm hành động">
    Ở cột **Hành động**, nhấn **Thêm hành động** rồi chọn loại và cấu hình:

    * **Cập nhật dữ liệu pass** — chọn trường trong mô hình dữ liệu và nhập giá trị mới. Tab **Mã JSON** cho phép sửa trực tiếp.

    * **Tăng giá trị / Giảm giá trị** — chọn trường số và bước nhảy.

    * **Vô hiệu hoá pass** — vô hiệu thẻ ngay lập tức.

    * **Đồng bộ ví** — đẩy bản mới nhất xuống ví mà không đổi dữ liệu.

    * **Gửi thông báo** — nhập tin nhắn và thêm bản dịch theo ngôn ngữ.

          <img src="https://mintcdn.com/xanhcard/rPjYaFf3KMfDr4-C/images/automations/04-notify-translations.png?fit=max&auto=format&n=rPjYaFf3KMfDr4-C&q=85&s=d63aff996f63ec9e1d4ebbb59a64f9d2" alt="Hành động gửi thông báo kèm bản dịch" width="3200" height="1752" data-path="images/automations/04-notify-translations.png" />

    * **Gọi webhook** — nhập URL, phương thức xác thực và thời gian chờ để báo cho hệ thống khác.

    Dùng nút mũi tên để đổi thứ tự — hành động chạy lần lượt từ trên xuống dưới.
  </Step>

  <Step title="Bật và lưu">
    Gạt **Đang bật** rồi nhấn **Lưu**. Quy tắc có hiệu lực trong vài giây và chỉ áp dụng cho sự kiện xảy ra **sau** lúc tạo — sự kiện cũ không kích hoạt quy tắc mới.
  </Step>
</Steps>

## Xem lịch sử chạy

Nhấn **Lịch sử chạy** trên thẻ quy tắc để xem từng lần chạy, mới nhất trước: sự kiện nào đã kích hoạt, thẻ nào, trạng thái **Hoàn thành** / **Thất bại** / **Đang chờ**, và kết quả từng hành động.

<img src="https://mintcdn.com/xanhcard/rPjYaFf3KMfDr4-C/images/automations/05-run-history.png?fit=max&auto=format&n=rPjYaFf3KMfDr4-C&q=85&s=a8888af40c9ea9a76f5ad11d0cfeef80" alt="Lịch sử chạy của quy tắc" width="3200" height="1752" data-path="images/automations/05-run-history.png" />

## Lưu ý quan trọng

<Warning>
  Quy tắc nhóm **Kết thúc** (vô hiệu, hết hạn) chỉ gửi thông báo và gọi webhook — không thể đổi dữ liệu thẻ đã kết thúc vòng đời.
</Warning>

<Info>
  Quy tắc **Pass được quét** chạy *sau* khi máy quét trả kết quả, nên không bao giờ làm đổi kết quả quét. Lượt quét bị từ chối (thẻ vô hiệu, hết hạn) vẫn kích hoạt quy tắc nếu bạn không lọc kết quả.
</Info>

* Một hành động lỗi không chặn các hành động còn lại — lỗi được ghi vào lịch sử chạy.
* Cùng một sự kiện gửi lại nhiều lần cũng chỉ chạy hành động đổi dữ liệu **đúng một lần**; thông báo và webhook có thể lặp lại trong trường hợp hiếm này.
* Nếu thẻ bị vô hiệu hoặc hết hạn trong lúc chờ chạy, các hành động đổi dữ liệu sẽ ghi lỗi, còn thông báo và webhook vẫn chạy.

Xem thêm [Lịch sự kiện](/events/overview) cho chiến dịch theo thời gian cố định, [Hành động quét](/scanners/actions) cho xử lý ngay lúc quét, và [Thông báo](/distribution/notifications) để tìm hiểu cách thông báo đến ví người dùng.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.