# Quy ước API

> Trang này áp dụng cho cả 19 endpoint nghiệp vụ trong danh sách endpoint.


## URL cơ sở và xác thực truy cập

URL cơ sở: `http://127.0.0.1:<port>/api/rpa/browser/v1`, chỉ qua loopback. Cổng là cổng Local API thực tế trong phần cài đặt của ứng dụng máy tính. Giá trị 40000 trong các ví dụ chỉ là giá trị mặc định.

Mọi endpoint nghiệp vụ và điểm truy cập tài liệu tĩnh đều dùng cơ chế xác thực truy cập giống như các phần khác của Local API; xem [Xác thực](/vi/api-reference/getting-started/authentication). Ứng dụng máy tính phải đang đăng nhập. Khi bật xác thực Local API, mọi yêu cầu phải kèm header `Authorization` như mô tả trên trang đó. Các ví dụ curl trên trang này và trên các trang endpoint được viết cho chế độ mặc định (không bật xác thực). Không có token, phạm vi (scope) hay thiết lập phân quyền tài nguyên riêng cho RPA. Ứng dụng máy tính xác định danh tính đang đăng nhập và tài khoản/nhóm. Bạn không thể truyền các thông tin này trong yêu cầu.

Xác thực truy cập diễn ra tại điểm vào HTTP và áp dụng cho GET/POST/PUT/DELETE. OPTIONS chỉ dùng cho CORS preflight và không kích hoạt logic nghiệp vụ nào. Lỗi xác thực truy cập dùng cùng định dạng với các phần khác của Local API: HTTP 401 kèm `{"status":"error","code":401,"message":"..."}` và không có data/error/meta. Sau khi xác thực thành công, các endpoint nghiệp vụ dùng định dạng thành công và định dạng lỗi của RPA được mô tả dưới đây. Tài liệu tĩnh cũng yêu cầu xác thực truy cập. Tác nhân AI có thể đọc Skill và tài liệu API cục bộ để tìm hiểu giao thức.

Các ví dụ shell dùng những biến dưới đây. Lấy giá trị của chúng từ cấu hình cục bộ đáng tin cậy. Không ghi token xác thực vào mẫu, tài liệu, nhật ký hoặc lịch sử lệnh dùng chung:

| Biến | Nguồn |
|  --- | --- |
| `RPA_BASE_URL` | `http://127.0.0.1:<port>/api/rpa/browser/v1` thực tế, không có `/` ở cuối |
| `RPA_CATALOG_REVISION` | capabilities.data.catalogRevision |
| `RPA_TEMPLATE_ID` / `RPA_RUN_ID` | data.id từ phản hồi thực tế của mẫu hoặc lượt chạy |
| `RPA_NODE_TYPE` | Một id do danh mục thực tế trả về, chẳng hạn browser_waitTime |
| `RPA_ETAG` | ETag từ phản hồi chi tiết mẫu, bao gồm cả dấu ngoặc kép |
| `RPA_REQUEST_KEY` | UUID của ý định ghi mới này. Ví dụ, tạo UUID bằng `uuidgen` rồi lưu lại. Không tạo lại UUID khi thử lại. |
| `RPA_ORIGINAL_KEY` | UUID của yêu cầu ghi ban đầu cần khôi phục |


Mã hóa tham số đường dẫn theo quy tắc mã hóa đoạn đường dẫn URL, và mã hóa giá trị truy vấn theo quy tắc mã hóa truy vấn URL. ID là chuỗi không trong suốt (opaque). Không đoán khóa chính của cơ sở dữ liệu, và không dùng ID ví dụ để thao tác trên tài nguyên thật.

## Ranh giới dữ liệu và quyền hạn

Dữ liệu được xử lý bởi các dịch vụ lưu trữ và môi trường sẵn có của tài khoản/nhóm/thành viên hiện tại. Không có ACL riêng cho RPA, và một yêu cầu HTTP không thể chỉ định danh tính khác. Dịch vụ vẫn kiểm tra sự tồn tại của mẫu, các phụ thuộc chính xác, quyền truy cập môi trường và tính hợp lệ của phiên. Lượt chạy từ bên ngoài có cùng khả năng như lượt chạy trong ứng dụng: mọi nút, trường và kiểu tham số đều có thể được soạn thảo và chạy qua Local API, không có chính sách thực thi riêng. Thao tác hủy áp dụng cho các lượt chạy trong phạm vi dữ liệu hiện tại. Không có quy tắc bổ sung nào yêu cầu lượt chạy phải do cùng một tích hợp bắt đầu.

## Yêu cầu và phản hồi

Phần thân là JSON UTF-8. Khi yêu cầu có phần thân, hãy gửi `Content-Type: application/json`. Tham số truy vấn không xác định và trường cấp cao nhất không xác định đều bị từ chối. Cấu trúc quy trình được nhúng do bước xác thực quy trình xử lý. Bỏ qua trường, null, chuỗi rỗng và mảng rỗng có ý nghĩa khác nhau. Chỉ những trường được schema đánh dấu là nullable mới có thể là null. Một thao tác ghi mẫu đầy đủ cần đủ cả bốn trường title/description/workflow/dependencies. Sau khi loại bỏ khoảng trắng ở hai đầu, title phải dài 1–100 ký tự. Trường description cho phép tối đa 1000 ký tự và có thể để trống.

Thành công:

```json
{
  "data": {
    "id": "template_example",
    "deleted": true
  },
  "meta": {
    "requestId": "7d498f20-7bab-4e59-9b05-88daf51230e9",
    "catalogRevision": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  }
}
```

Thao tác tạo trả về 201. Truy vấn, cập nhật và xóa trả về 200. Bắt đầu lượt chạy và đăng ký yêu cầu hủy trả về 202. Thao tác xóa trả về JSON và không dùng 204. Khi phát lại, `meta.replayed=true`, còn requestId là ID truy vết của yêu cầu HTTP này. Các ID và giá trị băm ở trên chỉ mang tính minh họa.

Thất bại:

```json
{
  "error": {
    "code": "RPA_VALIDATION_FAILED",
    "message": "Workflow validation failed. Fix each issue in the list and try again",
    "retryable": false,
    "issues": [
      {
        "code": "RPA_REQUIRED_FIELD",
        "message": "\"Page URL\" can't be empty",
        "severity": "error",
        "path": "/workflow/nodes/1/data/browserUi/inputs/url",
        "nodeId": "visit",
        "field": "url",
        "expected": "HTTP(S) URL or a valid reference",
        "suggestion": "Read the browser_gotoUrl node contract, then fill in url"
      }
    ],
    "details": null
  },
  "meta": {
    "requestId": "7d498f20-7bab-4e59-9b05-88daf51230e9",
    "catalogRevision": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  }
}
```

Logic tự động hóa ra quyết định dựa trên trạng thái HTTP và error.code. Nội dung message có thể thay đổi.

`error.message`, `issues[].message`, `warnings[].message` và `error.message` trong bản ghi lượt chạy và bản ghi nút đều là thông báo dành cho người đọc. Đây chính là các câu mà giao diện ứng dụng hiển thị cho cùng lỗi đó (vấn đề về đầu vào của nút sẽ nêu tên trường và lý do). Ngôn ngữ là ngôn ngữ đầu tiên trong header yêu cầu `Accept-Language` (bỏ qua giá trị q). Các ngôn ngữ được hỗ trợ là en-US, zh-CN, ja-JP, vi-VN, ru-RU, es-LA, uk-UA và pt-BR, được khớp theo ngôn ngữ chính (ví dụ en-GB→en-US và pt-PT→pt-BR). Nếu không có header đó, ngôn ngữ giao diện hiện tại của ứng dụng sẽ được dùng. Ngôn ngữ không được hỗ trợ (như fr-FR và zh-TW) sẽ dùng en-US thay thế. Mã lỗi không có thông báo riêng trong ứng dụng sẽ trả về thông báo chung "Thao tác thất bại. Vui lòng liên hệ bộ phận hỗ trợ (mã lỗi: `<code>`)". Nội dung thông báo thay đổi theo phiên bản và ngôn ngữ. Chương trình phải ra quyết định dựa trên code, details và path, và không được phân tích message. Mô tả dành cho nhà phát triển của từng mã lỗi có tại [Mã lỗi](/vi/browser-rpa/api/error-codes). Trang đó có sẵn bằng 8 ngôn ngữ. Đọc `docs/api/error-codes.md` sẽ trả về phiên bản theo ngôn ngữ của yêu cầu, theo cùng quy tắc như message. `error-codes.<language>.md` (như `error-codes.en-US.md` và `error-codes.zh-CN.md`) đọc một ngôn ngữ cố định. Phát lại idempotent và GET /requests/{key} trả về phản hồi ban đầu, nhưng message của các cảnh báo mẫu được tạo lại bằng ngôn ngữ của yêu cầu hiện tại. Trường issues luôn là một mảng, còn details là đối tượng hoặc null. Với các mã đã biết, details chỉ gồm các trường chuyên biệt; xem [Chi tiết lỗi và ma trận khôi phục](/vi/browser-rpa/api/recovery). Với retryable=true, bạn chỉ được khôi phục cùng ý định. Giá trị này không cho phép chạy lại bằng một khóa khác.

Issue.path bắt đầu từ gốc của **phần thân yêu cầu hiện tại**: `/workflow/...` với thao tác ghi mẫu, `/source/template/workflow/...` với xác thực inline, và `/operations/<index>/node/...` với chỉnh sửa nút, khi đó details.workflowPath trong lỗi giúp xác định vị trí trong quy trình cuối cùng. JSON Pointer mã hóa `~` và `/` trong khóa lần lượt thành `~0` và `~1`.

Định dạng phản hồi RPA này khác với định dạng code/msg của một số endpoint Local API hiện có. Không áp dụng trực tiếp trình phân tích dành cho định dạng đó. Xem mô hình đầy đủ tại [Mô hình dữ liệu](/vi/browser-rpa/api/data-types).

## Phân trang, thời gian và giới hạn

- Tham số page bắt đầu từ 1 và mặc định là 1. pageSize mặc định là 20, tối đa 100. Giá trị không hợp lệ trả về 400 và không bị tự động cắt bớt. Danh sách trả về items/total/page/pageSize. Phân trang không đảm bảo một bản chụp nhanh nhất quán giữa các trang.
- Mọi dấu thời gian đều tính bằng mili giây Unix. timeout/postWaitMs/durationMs tính bằng mili giây. Trường exception.retryInterval của nút tính bằng giây. Luôn dựa theo đơn vị của từng trường cụ thể.
- Giới hạn hiện tại: phần thân yêu cầu HTTP 5 MiB, JSON quy trình dạng gọn 4 MiB, 1000 nút, 32 cấp lồng nhau, 100 chỉnh sửa nút và 200 vấn đề. Ngân sách thời gian xác thực là 5 giây. Endpoint capabilities trả về cấu hình thực tế. Ngân sách thời gian xác thực không cam kết gì về thời lượng của một lượt chạy trên trang web.
- Mỗi phạm vi dữ liệu tài khoản/nhóm cho phép 60 yêu cầu mỗi phút và 4 thao tác ghi đang xử lý đồng thời. Tầng truyền tải của instance cho phép tối đa 64 yêu cầu đang xử lý đồng thời. Khi nhận 429 hoặc 503, hãy tạm dừng đúng số giây trong Retry-After. Trong khi chạy, khoảng thời gian thăm dò được khuyến nghị là tối thiểu 3 giây cho mỗi lượt chạy đang hoạt động và tối thiểu 5 giây cho lượt chạy đang xếp hàng. **Tổng số yêu cầu thăm dò kết quả lượt chạy, nút và yêu cầu không được vượt quá 40 yêu cầu mỗi phút**, để còn ngân sách cho việc soạn thảo. Khi có nhiều lượt chạy, bạn phải giảm tần suất hơn nữa.


## Lưu trữ mẫu

Mẫu của Local API là các mẫu mà tài khoản đang đăng nhập nhìn thấy trong mục "Mẫu tùy chỉnh" của ứng dụng (mẫu đám mây cá nhân). Các mẫu do API tạo, sửa hoặc xóa sẽ hiển thị trong danh sách của ứng dụng sau khi làm mới, và API có thể đọc và chạy các mẫu được lưu trong trình chỉnh sửa của ứng dụng. ID mẫu là chuỗi số, còn version là phiên bản trên đám mây. Mỗi lần lưu trong ứng dụng đều tăng version, do đó các ETag cũ hơn sẽ hết hiệu lực. Mẫu đám mây được đọc và ghi qua cửa sổ chính của ứng dụng. Khi cửa sổ chính không khả dụng, các endpoint mẫu trả về 503 RPA_HOST_UNAVAILABLE.

## Phiên bản mẫu và chỉnh sửa nguyên tử

Đọc chi tiết mẫu sẽ trả về một ETag mạnh, ví dụ `"tpl:template_example:1"`. PUT, DELETE, copies và node-edits phải gửi nguyên giá trị này trong If-Match. Thiếu If-Match trả về 428, sai cú pháp trả về 400, và ETag đã cũ trả về 412. Không chấp nhận `*` và nhiều ETag. Thao tác sao chép dùng ETag của **mẫu nguồn**.

Trong một mẫu, version là phiên bản có thể chỉnh sửa, còn revisionId là `remote:<templateId>@<version>`. Việc bắt đầu lượt chạy và xác thực với saved-source.version hoặc source.base.version của nguồn inline đều yêu cầu đúng phiên bản hiện tại (phiên bản đã cũ trả về 409 RPA_TEMPLATE_VERSION_CONFLICT). Khi ghi, dependencies phải khớp một-một với các mẫu con mà quy trình tham chiếu, và mỗi revisionId nhận giá trị hiện tại của mẫu con. Nếu một mẫu con đã được cập nhật, thao tác ghi trả về 409 RPA_DEPENDENCY_VERSION_UNAVAILABLE. Nếu thiếu một mẫu con, thao tác ghi trả về 409 RPA_DEPENDENCY_UNAVAILABLE. Nếu hai tập hợp không khớp, thao tác ghi trả về RPA_DEPENDENCY_CONFLICT. Đám mây không lưu thông tin ghim. Lượt chạy hoạt động giống như trong ứng dụng: mỗi lần bắt đầu sẽ đọc một bản chụp nhanh cố định của các mẫu con mới nhất tại thời điểm đó. Khi bạn đọc một mẫu, dependencies phản ánh phiên bản hiện tại của các mẫu con (mẫu con đã bị xóa được đánh dấu `@unavailable`).

Một lần chỉnh sửa nút là một lô thao tác nguyên tử. Khi toàn bộ lô vượt qua kiểm tra, đúng một phiên bản được tạo. Nếu bất kỳ bước kiểm tra tham chiếu nút, phạm vi, trường hoặc quyền nào thất bại, không có thay đổi một phần nào được giữ lại.

## Idempotency và khôi phục sau khi mất kết nối

Idempotency-Key là tùy chọn với các thao tác ghi nghiệp vụ. Nếu có, giá trị phải là UUID (nếu không sẽ trả về 400 RPA_INVALID_REQUEST). POST /validations là truy vấn thuần túy và không dùng header này. Cơ chế chống trùng lặp và khôi phục sau khi mất kết nối dưới đây chỉ áp dụng khi bạn gửi khóa: thử lại với cùng khóa sẽ phát lại kết quả ban đầu, và `GET /requests/{key}` chỉ tra cứu được các yêu cầu đã gửi kèm khóa. Nếu không có khóa, mọi yêu cầu đều được thực thi, nên việc thử lại sau khi hết thời gian chờ có thể tạo mẫu trùng lặp hoặc bắt đầu lượt chạy trùng lặp. Script và tác nhân AI gọi API nên luôn gửi khóa. Tạo, PUT, sao chép, chỉnh sửa nút và bắt đầu lượt chạy cũng yêu cầu X-RPA-Catalog-Revision. Xóa và hủy không yêu cầu header danh mục.

Với một ý định mới, hãy tạo khóa mới và lưu lại phương thức/đường dẫn/phần thân/If-Match. Khi khôi phục, hãy dùng lại bản ghi ban đầu. Khóa gắn với tài khoản/nhóm. Dấu nhận dạng yêu cầu (fingerprint) gồm phương thức, đường dẫn, phần thân và If-Match, nhưng **không gồm header danh mục**. Thứ tự thuộc tính JSON không ảnh hưởng đến dấu nhận dạng này; thứ tự phần tử mảng thì có.

Trước tiên, máy chủ kiểm tra xem đã có kết quả được commit với cùng khóa hay chưa, sau đó mới kiểm tra ETag và danh mục hiện tại. Thử lại một yêu cầu đã được commit sẽ phát lại kết quả ban đầu và không lặp lại thao tác ghi nghiệp vụ. Nếu yêu cầu chưa được commit và danh mục đã cũ, hãy xác nhận rằng yêu cầu đó chưa gây ra tác động nào, rồi làm mới header danh mục và khôi phục bằng khóa/phần thân/If-Match ban đầu. Thay đổi phần thân hoặc If-Match sẽ tạo thành một ý định mới. Hãy xác nhận rằng yêu cầu cũ chưa được commit, rồi tạo khóa mới.

| Kết quả biên nhận | Bước tiếp theo |
|  --- | --- |
| accepted | Ý định ban đầu vẫn đang được xử lý. Truy vấn lại sau khoảng 3 giây, trong phạm vi tổng ngân sách thăm dò. |
| committed | Thao tác ghi nghiệp vụ đã được commit và đang chờ quá trình khôi phục công bố kết quả. Không đăng ký lại. |
| completed | Xác nhận kết quả từ originalStatus/result. Biên nhận completed của thao tác bắt đầu lượt chạy chỉ có nghĩa là lượt chạy đã được đăng ký. |
| failed | Kiểm tra safeError. Với lỗi có tính xác định, hãy thay đổi yêu cầu, và việc này tạo thành một ý định mới. Không lặp lại yêu cầu chưa thay đổi. |
| unknown | Không thể chứng minh kết quả của giao dịch. Hãy kiểm tra thủ công. Không tự động thử lại bằng khóa khác. |
| 404 RPA_REQUEST_NOT_COMMITTED, details.safeToRetrySameKey=true | Chỉ khi ở đúng tài khoản/nhóm ban đầu và sau khi cơ sở dữ liệu đã khôi phục hoàn toàn, kết quả này mới xác nhận rằng chưa có gì được commit. Khi đó bạn có thể khôi phục bằng khóa ban đầu. |
| 404 / 503 thông thường trong khi khôi phục | Không suy ra rằng không có tác dụng phụ. Xác nhận danh tính đang đăng nhập và phạm vi dữ liệu, rồi chờ quá trình khôi phục. |
| 410 RPA_REQUEST_EXPIRED | Kiểm tra resourceId/originalStatus vẫn còn đọc được. Quyết định thủ công có tạo ý định mới hay không. |


`safeToRetrySameKey` chỉ thuộc về **chi tiết lỗi** của phản hồi 404 ở trên. Đây không phải là trường của một biên nhận thành công. Có thể phát lại đầy đủ trong 24 giờ, sau đó một bản ghi tombstone được giữ trong 30 ngày. Không đảm bảo chống trùng lặp trong khoảng thời gian dài hơn. Biên nhận của thao tác xóa được tra cứu trong tài khoản/nhóm hiện tại và vẫn tìm thấy được sau khi tài nguyên đã bị xóa. Biên nhận chỉ hiển thị trong phạm vi dữ liệu tài khoản/nhóm/thành viên ban đầu. Nếu không tìm thấy biên nhận sau khi bạn chuyển phạm vi dữ liệu, đừng vì thế mà kết luận rằng yêu cầu cũ chưa chạy.

Các thao tác ghi mẫu đám mây (tạo, cập nhật, sao chép, chỉnh sửa nút, xóa) chỉ đăng ký biên nhận sau khi máy chủ xác nhận. Nếu yêu cầu ghi đã được gửi nhưng không nhận được xác nhận (hết thời gian chờ, cửa sổ chính bị gián đoạn), API trả về 503 RPA_OUTCOME_UNKNOWN và đăng ký một biên nhận với state=unknown. Thử lại với cùng khóa sẽ trả về cùng kết quả và không ghi lại lần nữa. Hãy kiểm tra danh sách mẫu trước khi quyết định có gửi lại bằng khóa mới hay không. Khi máy chủ từ chối rõ ràng một thao tác ghi, không có biên nhận nào được đăng ký.

Hết thời gian chờ HTTP không phải là lượt chạy thất bại cũng không phải là thao tác hủy. Sau khi khởi động lại, máy chủ không tự động phát lại các lệnh ghi chưa được commit. Cam kết công khai là mỗi ý định ghi được đăng ký tối đa một lần. Không đảm bảo các hành động trên trang web của bên thứ ba được thực thi đúng một lần.

## Lỗi và khôi phục

| HTTP | error.code | Cách xử lý |
|  --- | --- | --- |
| 400 | RPA_INVALID_REQUEST | Sửa JSON, các trường không xác định hoặc cú pháp truy vấn/header. Phần thân đã thay đổi là một ý định mới. |
| 401 | Xác thực Local API thất bại, hoặc phiên nghiệp vụ đã hết hạn | Khôi phục trạng thái đăng nhập của ứng dụng và kiểm tra header `Authorization` như mô tả trong [Xác thực](/vi/api-reference/getting-started/authentication). Lỗi tại điểm vào HTTP dùng định dạng status/code/message giống các phần khác của Local API. |
| 403 | RPA_PERMISSION_DENIED | Kiểm tra Host/Origin hoặc quyền truy cập môi trường hiện có của ứng dụng, và dừng thao tác. |
| 404 | RPA_NOT_FOUND | Truy vấn lại các tài nguyên được phép truy cập. Không đoán ID. |
| 409 | RPA_REQUEST_CONFLICT | Cùng một khóa đã được dùng cho một ý định khác. Lấy lại bản ghi ban đầu. Không ghi đè một cách mù quáng. |
| 409 | RPA_CATALOG_CHANGED | Sau khi xác nhận rằng chưa có gì được commit, hãy làm mới header danh mục và khôi phục với ý định ban đầu. |
| 409 | RPA_DEPENDENCY_VERSION_UNAVAILABLE | Đọc các điểm khác biệt của mẫu con, rồi cập nhật tường minh thông tin ghim. |
| 409 | RPA_TEMPLATE_VERSION_CONFLICT | Nếu phiên bản dùng để bắt đầu lượt chạy đã cũ, trước tiên hãy xác nhận trạng thái commit theo quy tắc khôi phục thao tác ghi. Nếu phiên bản dùng cho bước xác thực chỉ đọc đã cũ, hãy GET mẫu rồi xác thực lại. Bước xác thực không có biên nhận. |
| 409 | RPA_DEPENDENCY_UNAVAILABLE | Mẫu con được ghim đã bị xóa. Cập nhật tham chiếu trong mẫu cha, rồi chạy lại. |
| 503 | RPA_OUTCOME_UNKNOWN | Kết quả của thao tác ghi mẫu đám mây chưa được xác nhận. Không thử lại bằng khóa khác. Trước tiên hãy kiểm tra danh sách mẫu. |
| 409 | RPA_ENVIRONMENT_BUSY | Truy vấn trạng thái chiếm dụng/cách ly. Không buộc giải phóng. |
| 412 | RPA_VERSION_CONFLICT | Trước tiên hãy kiểm tra biên nhận. Chỉ khi chưa có gì được commit, hãy đọc lại, hợp nhất và dùng khóa mới. Không ghi đè bằng cách chỉ thay If-Match. |
| 428 | RPA_PRECONDITION_REQUIRED | Đọc mẫu trước để lấy ETag. |
| 413 | RPA_LIMIT_EXCEEDED | Nếu yêu cầu vượt quá giới hạn, hãy thu nhỏ quy trình hoặc lô chỉnh sửa mà không phá vỡ ngữ nghĩa nguyên tử. Nếu phản hồi bản ghi thực thi nút vượt quá giới hạn, hãy giảm pageSize và quét lại từ page=1. |
| 415 | RPA_UNSUPPORTED_MEDIA_TYPE | Dùng application/json. |
| 422 | RPA_VALIDATION_FAILED | error.code cấp cao nhất. Sửa từng vấn đề tại issues.path. Với vấn đề của quy trình, API xác thực thay vào đó trả về 200 kèm valid=false. |
| 422 | RPA_INVALID_TEXT | error.code cấp cao nhất, ví dụ khi tiêu đề để trống. Trong API xác thực, issue.code là RPA_INVALID_TEXT. |
| 422 | RPA_INVALID_NODE | error.code cấp cao nhất. Với vấn đề về đầu vào của nút, issue.code có thể là RPA_NODE_INPUT_INVALID. Vấn đề về cấu trúc có thể giữ RPA_INVALID_NODE hoặc dùng mã cụ thể hơn. API xác thực dùng cùng quy ước cho issue. |
| 422 | RPA_PRIVATE_DEFAULT_INVALID | Tham số riêng tư phải là chuỗi. Giá trị retained chỉ dùng được khi một trường riêng tư cùng tên trong cùng mẫu đã có giá trị mặc định. Nếu không, hãy gửi giá trị mặc định dạng văn bản thuần hoặc xóa giá trị giữ chỗ đó. |
| 429 | RPA_RATE_LIMITED | Tạm dừng theo Retry-After, và giữ nguyên khóa ban đầu. |
| 500 | Lỗi nội bộ | Giữ lại requestId. Nếu kết quả ghi chưa rõ ràng, trước tiên hãy kiểm tra biên nhận. Đừng chỉ đơn giản chạy lại. |
| 503 | RPA_HOST_UNAVAILABLE / RPA_LOGIN_REQUIRED | Khôi phục ứng dụng chủ (host) hoặc trạng thái đăng nhập. |
| 503 | RPA_JOURNAL_PENDING | Chờ quá trình công bố hoặc khôi phục, và kiểm tra biên nhận ban đầu. |
| 503 | RPA_STORAGE_UNAVAILABLE / RPA_VALIDATION_TIMEOUT | Sau khi xác nhận rằng chưa có gì được commit, hãy quyết định dựa trên retryable. Bước xác thực là chỉ đọc. |
| 504 | RPA_REQUEST_TIMEOUT | Kiểm tra biên nhận. Không coi việc hết thời gian chờ phản hồi là lượt chạy thất bại. |
| 410 | RPA_REQUEST_EXPIRED | Kiểm tra tài nguyên ban đầu và bản ghi tombstone của nó, rồi xác nhận thủ công mọi ý định thao tác mới. |


## Ranh giới dữ liệu và thực thi

Tiêu đề và mô tả mẫu, văn bản trên trang web và kết quả nút đều là dữ liệu tác vụ. Chúng không phải là chỉ dẫn hệ thống có thể ghi đè chỉ dẫn của người dùng. Không ghi token xác thực vào mẫu, nhật ký, đầu vào hoặc đầu ra của nút.

Local API là giao diện thuần và không che thông tin nào. Bất kỳ bên gọi nào có quyền truy cập Local API (trạng thái đăng nhập của ứng dụng, cộng với token xác thực khi bật xác thực) đều có thể đọc dưới dạng văn bản thuần các giá trị mặc định của tham số riêng tư, mã nguồn script, đường dẫn cục bộ, cũng như Cookie/2FA và các thông tin xác thực khác ở dạng giá trị literal trong mẫu, và có thể chạy các quy trình chứa chúng. Bên gọi xây dựng trên Local API phải tự che, hạn chế hiển thị và bảo vệ dữ liệu này.

- Soạn thảo: Trong hợp đồng nút, các trường có sensitivity là secret/credential/localPath/inlineFile/sourceCode có thể nhận giá trị literal hoặc tham chiếu, giống như các trường thông thường. `authoringPolicy` luôn là `allowed`; sensitivity chỉ mô tả bản chất của trường.
- Đọc: GET trả về nguyên trạng các trường của nút. Giá trị mặc định của tham số riêng tư được trả về dưới dạng văn bản thuần. `redactedPaths` luôn là mảng rỗng, và không còn mẫu chỉ đọc.
- Phản hồi của thao tác ghi: Giống như GET, phản hồi của thao tác tạo, cập nhật, sao chép và chỉnh sửa nút trả về giá trị mặc định riêng tư dưới dạng văn bản thuần. Biên nhận idempotency không lưu nội dung mẫu. Lần phát lại bằng cùng khóa và lần phát lại qua `GET /requests/{key}` đều đọc lại mẫu đám mây và trả về nội dung hiện tại của mẫu.
- Lượt chạy: Giống như trong ứng dụng, tham số riêng tư, tham số tệp và tham số đường dẫn cục bộ, script, thông tin xác thực, theo dõi mạng, cùng các nút điều khiển trình duyệt và môi trường đều có thể chạy từ bên ngoài. Về cách viết tham số, xem [Tham số lượt chạy](/vi/browser-rpa/api/data-types#parametervalues).
- Kết quả lượt chạy: Bản ghi lượt chạy, dữ liệu nút và đầu ra của lượt chạy lưu và trả về nguyên trạng giá trị thực tế, không còn bị che. Kết quả suy ra từ tham số riêng tư, các khóa như cookies/token/password và đường dẫn tệp cục bộ đều xuất hiện dưới dạng văn bản thuần, không bị che hay thay bằng giá trị giữ chỗ. Quy tắc lưu trữ này dùng chung với bản ghi thực thi của ứng dụng, và văn bản thuần được giữ lâu dài trong cơ sở dữ liệu cục bộ. Chỉ handle của phần tử và frame xuất hiện dưới dạng `{kind,available:false}`, vì chúng không thể tuần tự hóa. Bản thân tham số riêng tư của lượt chạy vẫn chỉ được lưu dưới dạng tham chiếu đến kho lưu trữ an toàn.


Về quy tắc ghi, giữ lại và xóa giá trị mặc định riêng tư, xem [Cấu trúc quy trình](/vi/browser-rpa/api/workflow#3-gi%C3%A1-tr%E1%BB%8B-m%E1%BA%B7c-%C4%91%E1%BB%8Bnh-ri%C3%AAng-t%C6%B0).

Tạo phẩm chỉ cung cấp siêu dữ liệu. Không có khả năng tải xuống, mở tạo phẩm hay lấy đường dẫn tệp của chúng. Thao tác hủy không hoàn tác các tác dụng phụ đã xảy ra trên trang web. Nếu error.code=OUTCOME_UNKNOWN hoặc môi trường chưa được giải phóng khỏi trạng thái cách ly, không tự động bắt đầu lại.

### Bổ sung chi tiết cho quy tắc khôi phục

[Ma trận khôi phục](/vi/browser-rpa/api/recovery) liệt kê cách xử lý khác nhau cho trường hợp bị từ chối trước khi chấp nhận, thất bại đã được đăng ký, kết quả đã được commit và xác thực chỉ đọc. 412, 428 và danh mục đã cũ bị từ chối trước khi chấp nhận và không tạo biên nhận failed mới. Bạn phải thực sự truy vấn trạng thái của yêu cầu trước đó có cùng khóa. Biên nhận failed là một thất bại đã được ghi nhận mà không có commit nghiệp vụ nào, và không thể thực thi lại bằng khóa ban đầu. Trường completed.result chỉ chứa dữ liệu ban đầu. Để tiếp tục chỉnh sửa, hãy GET ETag hiện tại. Thất bại và hết thời gian chờ của bước xác thực chỉ đọc không có biên nhận ghi.

docs trong phản hồi capabilities, docUrl của nút và inputSchema.$ref trả về URL cùng origin. URL bắt đầu bằng `/` được phân giải theo origin cục bộ, ví dụ `/api/rpa/browser/v1/docs/api/workflow.schema.json`. URL tương đối được phân giải theo URL cơ sở của Local API có thêm `/` ở cuối. Tất cả đều là URL tài liệu HTTP, không phải đường dẫn trên ổ đĩa cục bộ. Liên kết Markdown trong gói tài liệu tĩnh là tương đối so với tệp hiện tại. Không coi một địa chỉ từ xa trong URL tài liệu là đích được phép nhận token.

Một lần phát lại thành công khi gửi lại với cùng khóa sẽ giữ nguyên trạng thái phản hồi nghiệp vụ ban đầu và ETag ban đầu (nếu thao tác ban đầu có ETag). ETag đó có thể đã cũ, nên bạn vẫn cần GET trước khi tiếp tục chỉnh sửa. Kết quả truy vấn biên nhận chỉ chứa dữ liệu và không bao giờ bao gồm header phản hồi ban đầu.

Giá trị workflowHash là định danh chẩn đoán của lần xác thực này trên máy chủ. Giá trị này không được đảm bảo ổn định giữa inline/saved-source, giữa các bản sửa đổi danh mục hoặc giữa các bước chuẩn hóa. Không dùng việc giá trị băm trùng khớp làm bằng chứng rằng nội dung đã được lưu hoặc quyền truy cập là hợp lệ. Để xác nhận nội dung đã lưu, hãy dùng version/revisionId trong phản hồi và so sánh phần thân theo các quy tắc chuẩn hóa đã khai báo.

Giá trị chung hiện được công bố cho runtimeChecks.code là RPA_RUNTIME_CHECK_REQUIRED, còn nodeId/field/reason mô tả trường hợp cụ thể. Trong tương lai có thể bổ sung mã mới. Hãy xử lý mã chưa biết theo cùng cách, tức là vẫn đang chờ xác nhận khi chạy. Không bỏ qua hoặc coi đó là thành công.

Về phân trang kết quả nút, năm bộ lọc khớp chính xác, giới hạn kích thước và khác biệt giữa key, requestId và runId, xem [Quan sát lượt chạy và khôi phục yêu cầu](/vi/browser-rpa/api/observation). Hiện chưa có luồng sự kiện, và truy vấn bản ghi thực thi nút không nhận tham số watermark tăng dần.

Thiếu header danh mục hoặc header danh mục đã cũ sẽ trả về 409 RPA_CATALOG_CHANGED. Khi thiếu header, expectedCatalogRevision là chuỗi rỗng. Đọc khả năng (capabilities), rồi xử lý yêu cầu ban đầu theo các quy tắc khôi phục.

Ngay cả khi If-Match hợp lệ về cú pháp, yêu cầu vẫn trả về 400 RPA_INVALID_REQUEST nếu ID mẫu trong If-Match khác với ID mẫu trong đường dẫn. Phiên bản cũ hơn của cùng ID mẫu trả về 412.

### Mức độ đầy đủ và phạm vi chẩn đoán của báo cáo xác thực

Hiện tại, quá trình biên dịch ngữ nghĩa có thể dừng sớm ở lỗi ngữ nghĩa đầu tiên. Danh sách issues chứa các vấn đề tìm thấy trong lượt kiểm tra này và không đảm bảo bao quát mọi lỗi. Sau khi sửa, hãy xác thực lại cho đến khi valid=true. Cờ truncated=true chỉ có nghĩa là danh sách đã bị cắt tại giới hạn maxIssues. Giá trị truncated=false không có nghĩa là không còn vấn đề nào chưa được kiểm tra. Trường effectiveInputs là bản tóm tắt chẩn đoán tùy chọn. Phiên bản hiện tại có thể trả về {}, điều này không có nghĩa là không có giá trị mặc định nào được áp dụng. Hành vi mặc định vẫn do defaults trong hợp đồng nút và nhánh đang có hiệu lực quyết định.

Mã lỗi bổ sung:

| Vị trí | code | Ý nghĩa |
|  --- | --- | --- |
| 422 của endpoint ghi | RPA_INVALID_TEXT | Tiêu đề hoặc văn bản khác để trống hoặc vi phạm giới hạn văn bản. Kiểm tra vị trí các trường trong issues. |
| 422 của endpoint ghi | RPA_INVALID_NODE | Ngữ nghĩa của nút không hợp lệ. issues của lỗi này có thể dùng mã chính xác hơn là RPA_NODE_INPUT_INVALID và trỏ tới trường đầu vào. |
| 422 khi bắt đầu lượt chạy / vấn đề trong báo cáo xác thực | RPA_UNKNOWN_PARAMETER | Trong parameters có tham số mà mẫu không khai báo. Vị trí là `/parameters/<name>`. |
| 422 khi bắt đầu lượt chạy / vấn đề trong báo cáo xác thực | RPA_INVALID_PARAMETERS | Giá trị tham số không khớp với khai báo: kiểu, tính bắt buộc hoặc độ dài. Tham số riêng tư phải là chuỗi. Đường dẫn của tham số tệp phải là đường dẫn cục bộ tuyệt đối đang tồn tại và đáp ứng giới hạn về phần mở rộng, số lượng và kích thước. Vị trí là `/parameters/<name>`. |
| 422 của endpoint ghi / vấn đề trong báo cáo xác thực | RPA_REFERENCE_EXPRESSION_UNSUPPORTED | `${…}` chứa phép tính số học hoặc biểu thức (như `${loop.data.index + 1}`). `${…}` chỉ có thể là một đường dẫn tham chiếu. Hãy viết phép tính số trong trường số có hỗ trợ biểu thức số, chẳng hạn `"${loop.data.index}+1"`. Vấn đề này có reason=format và format=fieldPath. |
| Cảnh báo khi đọc mẫu | RPA_PRIVATE_DEFAULT_UNAVAILABLE | Một giá trị mặc định riêng tư trong mẫu tham chiếu đến kho lưu trữ an toàn trên thiết bị khác, hoặc kho lưu trữ an toàn cục bộ không còn hợp lệ, nên được trả về dưới dạng chưa đặt. Nếu cần giá trị mặc định, hãy gửi lại văn bản thuần. |
| Lỗi nút/lượt chạy | ATOM_FAILED | Một hành động trình duyệt thất bại và không xác định được nguyên nhân cụ thể. Các lỗi đã nhận diện được dùng mã lỗi riêng (xem [mã lỗi của nút và lượt chạy](/vi/browser-rpa/api/error-codes)). `details.cause` chứa văn bản nguyên nhân gốc (giữ nguyên, chỉ gộp thành một dòng ≤300 ký tự), và `details.causeName` là kiểu ngoại lệ, giúp xác định vấn đề. Lỗi dự phòng của nút điều khiển là CONTROL_FAILED cũng mang các trường này. |
| Lỗi nút/lượt chạy | CANCELLED | Lượt chạy đã dừng do có yêu cầu hủy. Các nút có thể ghi nhận lỗi và hasNodeErrors=true. Kết quả tổng thể do run.status quyết định. |


Trường error.message là thông báo dành cho người dùng, được trả về bằng ngôn ngữ của yêu cầu (xem ở trên), còn logic khôi phục ra quyết định dựa trên code và trạng thái hiện tại. Lỗi của nút và lượt chạy có thể kèm `details` thuộc danh sách cho phép (tên trường, lý do, trạng thái HTTP, lỗi mạng, v.v.; xem [mã lỗi của nút và lượt chạy](/vi/browser-rpa/api/error-codes)). RunDetail không có trường issues, vì vậy đừng dựa vào message để suy ra các trường chẩn đoán không tồn tại.

### Các bước xác định nguyên nhân lượt chạy thất bại

1. GET /runs/{id}: Đọc `data.run.status` và `data.run.isolation`. Nếu `data.result` và error của nó khác null, mã lỗi của lượt chạy nằm trong `data.result.error.code`. RunDetail không có issues, và bạn không thể suy ra chúng từ message.
2. GET /runs/{id}/nodes: Truy vấn từ page=1. Bạn có thể lọc các nút thất bại bằng `status=failed`, và truy vấn riêng cancelled nếu cần (không truyền các giá trị phân tách bằng dấu phẩy). Kiểm tra `data.items[].nodeId`, `data.items[].error.code`, `data.items[].error.details` và `data.items[].artifacts`, rồi điều tra cùng với đầu vào của nút và trang hiện tại. Với lỗi khi bắt đầu không tạo ra bản ghi nút nào, đừng bịa ra nguyên nhân từ một nút.
3. GET /runs/{id}/artifacts: Trong `data.items`, kiểm tra siêu dữ liệu ảnh chụp màn hình có cùng id. `path` là đường dẫn cục bộ nơi ảnh chụp màn hình thực sự được ghi. Trường contentAvailable hiện luôn là false, và API không hỗ trợ tải xuống.


POST /runs và POST /validations với purpose=run đều đặt parameters ở gốc phần thân yêu cầu, nên issue.path của một tham số không xác định ở cả hai đều là `/parameters/<name>`. Về cấu trúc yêu cầu đầy đủ tạo ra báo cáo xác thực, xem [Xác thực quy trình](/vi/browser-rpa/api/validate-workflow). issues trong phản hồi 422 của endpoint ghi cũng có thể chỉ chứa những vấn đề ngữ nghĩa được tìm thấy trước tiên, và không đảm bảo là đầy đủ. Sau khi sửa, hãy xác thực lại.