# Tài liệu nhà phát triển DANIX

Open API của DANIX cho phần mềm bên ngoài làm việc với dữ liệu của MỘT shop: đọc và ghi đơn hàng, sản phẩm, kho, khách hàng, vận đơn và hội thoại chat, rồi nhận dữ liệu mới ngay khi có thay đổi thông qua luồng tự động. Tài liệu này viết bằng tiếng Việt cho người viết tích hợp và cho các trợ lý AI giúp họ; mỗi trang có bản Markdown thuần ở cùng địa chỉ với đuôi `.md`.

Có hai cách làm việc, và thường dùng cùng nhau:

- **Gọi API.** Phần mềm của bạn gửi request tới `https://danix.vn/api/open/v1/…` kèm một khoá API. Mọi request thuộc về đúng shop sở hữu khoá.
- **Nhận dữ liệu.** Trong ứng dụng Tự động hoá của shop, bạn dựng một luồng: khi có sự kiện (đơn mới, tin nhắn mới…) luồng gửi dữ liệu tới địa chỉ HTTPS của bạn, ký bằng chữ ký để bạn kiểm tra. Xem [Luồng tự động và webhook](/developers/webhooks).

## Bắt đầu nhanh

### 1. Tạo ứng dụng kết nối và lấy khoá

Quản trị viên shop (hoặc người có quyền `automation.connections.manage`) mở ứng dụng **Tự động hoá**, vào mục **Kết nối API** và tạo một "ứng dụng kết nối". Khi tạo, bạn chọn đúng những quyền ứng dụng cần, và với chat thì chọn thêm các trang Facebook hay Zalo mà ứng dụng được làm việc. Bạn chỉ chọn được quyền và trang mà chính bạn đang có.

Khoá hiện **đúng một lần** khi tạo (hoặc khi xoay), có dạng `dnx_live_` kèm 38 ký tự. Hãy lưu nó ngay vào nơi giữ bí mật của hệ thống bạn. Chi tiết về quyền, xoay và thu hồi: [Xác thực](/developers/authentication).

### 2. Gọi thử bằng curl

```bash
curl "https://danix.vn/api/open/v1/shop" \
  -H "Authorization: Bearer dnx_live_…"
```

Thay `dnx_live_…` bằng khoá của bạn. Phản hồi có dạng sau (rút gọn); nhận được nó là thành công: khoá hợp lệ và shop còn dùng được.

```json
{
  "id": "…",
  "slug": "ten-shop",
  "name": "Tên shop",
  "application": {
    "name": "Tên ứng dụng kết nối",
    "permissions": ["pos.orders.read"],
    "pageIds": []
  },
  "readOnly": false
}
```

`application.permissions` liệt kê quyền khoá đang có, và `readOnly` là `true` khi gói của shop hết hạn (khoá chỉ còn đọc được). Nếu nhận lỗi, đối chiếu mã `code` ở trang [Lỗi](/developers/errors); lỗi thường gặp nhất là `invalid-api-key` (sai khoá) và `insufficient-permission` (khoá chưa được cấp quyền cho đường vừa gọi).

Đọc danh sách đơn hàng (cần quyền `pos.orders.read`):

```bash
curl "https://danix.vn/api/open/v1/orders?limit=20" \
  -H "Authorization: Bearer dnx_live_…"
```

Phản hồi là `{ "data": [...], "nextCursor": "..." }`; lặp lại với `cursor=<nextCursor>` để đọc trang kế. Xem [Phân trang và đồng bộ](/developers/pagination).

### 3. Tạo một luồng gửi dữ liệu tới địa chỉ thử

1. Trong ứng dụng Tự động hoá, mở mục **Luồng tự động** và bấm **Tạo luồng**.
2. Trên bảng vẽ, giữ khối **Kích hoạt** và chọn sự kiện, ví dụ `order.created`.
3. Thêm khối **Gửi HTTP**, nối dây từ Kích hoạt sang nó. Điền địa chỉ HTTPS của bên nhận (một địa chỉ thử như dịch vụ nhận webhook công cộng, hoặc máy chủ của bạn), phương thức `POST`.
4. Bấm **Chạy thử** để gửi một sự kiện mẫu, rồi **Lưu** và bật luồng.

Mỗi lượt gửi mang chữ ký theo chuẩn [Standard Webhooks](https://www.standardwebhooks.com/). Trước khi tin nội dung, hãy kiểm chữ ký bằng mã mẫu ở trang [Luồng tự động và webhook](/developers/webhooks). Người đã quen n8n nên đọc thêm [Cách luồng chạy](/developers/flow-logic).

## Đọc tiếp

- [Xác thực](/developers/authentication): khoá, quyền, xoay và thu hồi.
- [Lỗi](/developers/errors): định dạng lỗi và bảng mã.
- [Hạn mức gọi](/developers/rate-limits), [Phân trang và đồng bộ](/developers/pagination), [Idempotency-Key](/developers/idempotency).
- [Luồng tự động và webhook](/developers/webhooks), [Cách luồng chạy (cho người quen n8n)](/developers/flow-logic), [Sự kiện](/developers/events).
- [Phiên bản](/developers/versioning).
- Tham chiếu từng endpoint: [Shop](/developers/reference/shop), [Đơn hàng](/developers/reference/orders), [Sản phẩm](/developers/reference/products), [Kho](/developers/reference/inventory), [Khách hàng](/developers/reference/customers), [Địa giới hành chính](/developers/reference/geo), [Vận đơn](/developers/reference/shipments), [Hội thoại](/developers/reference/chat).
- Đặc tả máy đọc: [openapi.json](/openapi.json). Cho trợ lý AI: [llms.txt](/llms.txt) và [llms-full.txt](/llms-full.txt).

> Không có nút "gọi thử" trên trang này và API không mở CORS: khoá API không bao giờ được đặt trong trình duyệt. Hãy gọi từ máy chủ của bạn.