# Giới thiệu v2.0

{% hint style="warning" %}

* [**v3.0**](https://apidocs.nhanh.vn/v3) đã chính thức ra mắt từ **31-08-2025**.
* **v2.0** đã ngừng phát triển tính năng mới và sẽ ngừng hỗ trợ sau **30-11-2026**. Bạn nên chuyển đổi sang v3.0 để tránh gián đoạn sau khoảng thời gian này.
* Xem các thay đổi [từ v2.0 lên 3.0](https://apidocs.nhanh.vn/v2/tov3).
  {% endhint %}

## Khởi tạo ứng dụng

* Xem cách khởi tạo ứng dụng [tại đây](https://apidocs.nhanh.vn/app).
* Xem cách đăng nhập cấp quyền và lấy accessToken [tại đây](https://apidocs.nhanh.vn/app#lay-access-token).

## Request params

* Sau khi lấy được accessToken, bạn có thể bắt đầu gọi các API tới **pos.open.nhanh.vn**, bản 2.0 sẽ dùng **POST** method, body **form-data** và các params bắt buộc như sau:

{% hint style="info" %}
**Chú ý:** Nếu param type có dấu $$^{{\color{red}\*}}$$ là param bắt buộc (required), nếu không có là param không bắt buộc (optional).
{% endhint %}

| Param       | Type                          | Description                                                                            |
| ----------- | ----------------------------- | -------------------------------------------------------------------------------------- |
| version     | string $$^{{\color{red}\*}}$$ | 2.0                                                                                    |
| appId       | int $$^{{\color{red}\*}}$$    | Your app ID                                                                            |
| businessId  | int $$^{{\color{red}\*}}$$    | ID doanh nghiệp trên Nhanh.vn. Lúc bạn lấy accessToken, Nhanh API có trả về businessId |
| accessToken | string $$^{{\color{red}\*}}$$ | Your access token                                                                      |
| data        | string $$^{{\color{red}\*}}$$ | **json string** của **data array**. Các key của data array bạn xem tại từng API cụ thể |

### Postman sample

* Dùng [Postman](https://www.postman.com) lấy danh sách sản phẩm có phân trang.

![Postman: Lấy danh sách sản phẩm có phân trang](https://40622576-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MhIoEj3yOAgRRsZcqGM-887967055%2Fuploads%2Fgit-blob-59d98630d12fc3ed2f72b073efb47a00254ee7d3%2Fpostman_sample_product_paginator3_2.jpg?alt=media)

* Lấy danh sách địa chỉ vận chuyển

![Postman: Lấy danh sách địa chỉ vận chuyển](https://40622576-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MhIoEj3yOAgRRsZcqGM-887967055%2Fuploads%2Fgit-blob-a200c1c1f3fb2cca36c6296c330cdc6c2156568d%2Fpostman_code_snippet.jpg?alt=media)

### Postman collection

* Bạn có thể dùng [NhanhAPI Postman Collection](https://www.postman.com/nhanh-vn/workspace/open-nhanh-vn/overview) tham khảo params cho 1 số API hay dùng.
* Để sử dụng: Bạn click vào collection mình cần -> click **Fork**

![Postman: Tải về và tạo collection trên My Workspace của bạn](https://40622576-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MhIoEj3yOAgRRsZcqGM-887967055%2Fuploads%2Fgit-blob-506d89fc1d35903484ebc68c43b39d69cea2fa25%2Fpostman_create_fork.png?alt=media)

* Ở phần **Create Fork**: điền **Fork label** (Tên collection ở Workspace của bạn), **Workspace** (Chọn một không gian làm việc mà bạn muốn phân nhánh), xong click **Fork Collection**

![Postman: Tải về và tạo collection trên My Workspace của bạn](https://40622576-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MhIoEj3yOAgRRsZcqGM-887967055%2Fuploads%2Fgit-blob-a7e44525545cd353c6e27352ec5f5ca07b6c1296%2Fpostman_fork_collection.png?alt=media)

### Code sample

{% hint style="info" %}
Chú ý: Bản 2.0 hệ thống chưa hỗ trợ dùng javascript để gọi API (Sẽ bị báo lỗi CORS). API 3.0 dự kiến sẽ hỗ trợ mở CORS. Bạn có thể dùng Postman điền các params và click vào Code Snippet trên Postman để xem cách tạo syntax cho các ngôn ngữ (Nodejs, PHP, C#, Go, Java...):
{% endhint %}

![Postman generate code syntax](https://github.com/nvndocs/docs-pos-openapi/blob/v2/docs/img/postman_generate_code_snippet_2.jpg)

## Lỗi thường gặp

### Invalid data

* Khi bạn gửi request và nhận được response là **invalid data**: Lỗi này do data không phải là 1 chuỗi json string hợp lệ, thường do bạn không dùng các hàm json encode mà gõ thủ công gây thừa thiếu dấu hoặc không encode các kí tự đặc biệt. Bạn có thể kiểm tra chuỗi data json string bằng cách vào <https://jsonformatter.org> copy paste chuỗi của bạn vào textarea và click **Validate**.

### Error ERR\_403

* Khi bạn gửi request và nhận được response có errorCode = **ERR\_403**, messsages = **The app or accessToken is not authorized for this feature**: Lỗi này là do user đăng nhập cấp quyền chưa chọn quyền hoặc không có quyền thao tác với hành động đó. VD: user đăng nhập cấp quyền, chỉ có quyền xem danh sách sản phẩm, nên sẽ không hiện ra quyền danh sách đơn hàng, hoặc user có quyền nhưng không chọn ở bước đăng nhập cấp quyền, thì sau đó bạn sẽ không thể dùng accessToken để gọi API [/api/order/index](https://github.com/nvndocs/docs-pos-openapi/blob/v2/docs/order/index/README.md).
* Cách sửa: Báo user đăng nhập đúng tài khoản có quyền thao tác với dữ liệu và chọn quyền ở bước [đăng nhập cấp quyền](https://apidocs.nhanh.vn/#dang-nhap-cap-quyen).

### API Rate Limit

* Rate Limit là số lệnh gọi API mà ứng dụng của bạn có thể thực hiện trong khoảng thời gian nhất định. Nếu vượt quá giới hạn này thì ứng dụng có thể bị giới hạn tốc độ. Các lệnh gọi API do ứng dụng đang bị giới hạn tốc độ sẽ không thành công. Lỗi này thường gặp phải khi ứng dụng không lưu dữ liệu mà luôn gọi API (VD liên tục gọi API lấy danh sách sản phẩm, danh sách đơn hàng...). **Khuyến cáo:** Bạn cần lưu dữ liệu ở hệ thống của bên bạn, cập nhật [dữ liệu mới từ webhooks](https://apidocs.nhanh.vn/v2/webhooks/webhooks), khi gọi API chỉ nên lấy các dữ liệu có thay đổi, không lấy toàn bộ dữ liệu cũ (các API có hỗ trợ lọc theo updatedDateTimeFrom - updatedDateTimeTo hoặc updatedAtFrom - updatedAtTo).
* Rate Limit sẽ được kết hợp từ appId + businessId + API URL, nên ứng dụng của bạn có thể sẽ bị giới hạn ở 1 URL này, nhưng vẫn có thể gọi URL khác nếu URL đó không bị giới hạn, hoặc nếu ứng dụng của bạn dùng cho nhiều doanh nghiệp, thì bạn có thể bị giới hạn với businessId 1, nhưng vẫn có thể dùng được với businessId 2. **Chú ý:** Nếu bạn cố tình dùng nhiều ứng dụng để gọi liên tục API, hệ thống sẽ khóa toàn bộ các ứng dụng. Các ứng dụng bị khóa, sẽ không thể gọi bất kì API nào nữa.
* Rate Limit sẽ có mức chung mặc định là: 150 requests / 30 giây. Nếu 1 API có mức riêng, thì tài liệu của API đó sẽ có mô tả riêng.
* Khi vượt quá Rate Limit, bạn sẽ nhận được errorCode = ERR\_429. Bạn cần tạm ngừng gọi API tới URL này cho tới khi quá thời gian **unlockedAt**. Nếu vẫn tiếp tục phát sinh gọi API khi đang bị Rate Limit, lockedSeconds và unlockedAt sẽ bị tăng lên.

```json
{
  "code": 0,
  "message": "Your app exceeded the API Rate Limit",
  "errorCode": "ERR_429",
  "data": {
    "lockedSeconds": 10,
    "unlockedAt": 1733387520
  }
}
```

| Key           | Description                                                                             |
| ------------- | --------------------------------------------------------------------------------------- |
| lockedSeconds | Số giây bị khóa                                                                         |
| unlockedAt    | Thời gian được mở khóa theo Unix timestamp. VD: 1733387520 = 2024-12-05 15:32:00 GMT+07 |

## Thuật ngữ

### Trạng thái sản phẩm

| Value      | Mô tả                                                                                                                                                                                                           |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New        | Mới: Trạng thái này dùng để bán hàng ở cửa hàng offline                                                                                                                                                         |
| Active     | Đang bán: Trạng thái này dùng để hiện bán ở trên website online (nếu dùng website của Nhanh.vn) và cửa hàng offline                                                                                             |
| Inactive   | Ngừng bán: Trạng thái này để ẩn sản phẩm cả webiste online và cửa hàng offline, gõ gợi ý và mặc định ở danh sách sản phẩm cũng không hiện ra trừ khi lọc trạng thái Ngừng bán hoặc lọc chính xác id sản phẩm đó |
| OutOfStock | Hết hàng: Dùng để hiện trên website nhưng sẽ hiện thêm chữ Hết hàng và không cho đặt hàng, thường để website giữ link sản phẩm cũ, tránh lỗi 404                                                                |

### Order

Các thuật ngữ của đơn hàng online

* **shippingWeight**: bao gồm cân nặng thực tế của sản phẩm và toàn bộ cân nặng của các phụ kiện và vỏ hộp đóng gói đi kèm. Shipping weight được sử dụng để tính phí vận chuyển của đơn hàng. VD: Sản phẩm “Samsung Galaxy S2” nặng 300gr, Sản phẩm fullbox còn bao gồm 1 sạc (30gr), 1 tai nghe (10gr) and vỏ hộp đóng gói (30gr), vậy thì shippingWeight để tính phí vận chuyển sẽ là: 300 + 30 + 10 + 30 = 370 gr.
* **COD**: Cash on delivery (Collect on delivery) là 1 loại giao dịch mà người mua hàng sẽ trả tiền khi nhận được hàng. Nếu người mua không đồng ý thanh toán khi nhận hàng, đơn hàng sẽ được chuyển trả lại cho người bán. Phí thu tiền hộ **codFee** tùy thuộc vào số tiền cần thu của đơn hàng.
* **shipFee**: Phí vận chuyển, được tính dựa vào trọng lượng đơn hàng, địa chỉ gửi hàng và địa chỉ nhận hàng.
* **customerShipFee**: Phí thu của khách, là mức phí mà website thông báo cho khách đặt hàng, thường sẽ lấy bằng shipFee + codFee. Tình huống website có chương trình miễn phí vận chuyển cho khách thì set customerShipFee = 0.
* **Order Status:**

  Trạng thái đơn hàng

| Status             | Description             |
| ------------------ | ----------------------- |
| New                | Đơn mới                 |
| Confirming         | Đang xác nhận           |
| CustomerConfirming | Chờ khách xác nhận      |
| Confirmed          | Đã xác nhận             |
| Packing            | Đang đóng gói           |
| Packed             | Đã đóng gói             |
| ChangeDepot        | Đổi kho xuất hàng       |
| Pickup             | Chờ thu gom             |
| Shipping           | Đang chuyển             |
| Success            | Thành công              |
| Failed             | Thất bại                |
| Canceled           | Khách hủy               |
| Aborted            | Hệ thống hủy            |
| CarrierCanceled    | Hãng vận chuyển hủy đơn |
| SoldOut            | Hết hàng                |
| Returning          | Đang chuyển hoàn        |
| Returned           | Đã chuyển hoàn          |

* **Order Reason**

  Lý do theo trạng thái đơn hàng

| Reason                   | Description                                       |
| ------------------------ | ------------------------------------------------- |
| WrongProduct             | Đặt nhầm sản phẩm                                 |
| HighShipFee              | Phí vận chuyển cao                                |
| NotTransfer              | Không muốn chuyển khoản                           |
| Duplicated               | Đơn trùng                                         |
| CannotCall               | Không gọi được khách                              |
| SoldOut                  | Hết hàng                                          |
| WaitingTransfer          | Chờ chuyển khoản                                  |
| NotLikeProduct           | Khách không thích sản phẩm                        |
| NotPleasureDeliverer     | Khách không hài lòng về nhân viên vận chuyển      |
| SlowShipping             | Giao hàng chậm                                    |
| Bought                   | Đã mua sản phẩm tại cửa hàng                      |
| CustomerNotAtHome        | Khách đi vắng (sẽ giao hàng vào hôm khác)         |
| WrongAddress             | Sai địa chỉ người nhận                            |
| NotBuy                   | Khách không muốn mua nữa                          |
| CannotCallSender         | Không liên hệ được với người gửi                  |
| SellerNotSellOnline      | Người gửi không bán hàng Online / Ngoại tỉnh      |
| SellerNotHandoverCarrier | Người gửi không bàn giao hàng cho hãng vận chuyển |
| SellerNotProcessOrder    | Người gửi không xử lý đơn hàng                    |
| WrongPickupAddress       | Sai địa chỉ kho lấy hàng                          |
| WrongPrice               | Sai giá sản phẩm                                  |
| SelfShipping             | Người gửi tự vận chuyển                           |
| CarrierPickupLate        | Hãng vận chuyển lấy hàng muộn                     |
| CarrierLostProduct       | Hãng vận chuyển làm mất hàng                      |
| Other                    | Lý do khác                                        |

### Inventory

Các thuật ngữ về kho hàng

* Phiếu XNK, Sản phẩm XNK có 2 loại (type) là phiếu nhập, phiếu xuất và nhiều kiểu (mode) XNK khác nhau:
* Loại XNK:

| Type (int) | Description   |
| ---------- | ------------- |
| 1          | Loại nhập kho |
| 2          | Loại xuất kho |

* Kiểu XNK:

| Mode (int) | Description                    |
| ---------- | ------------------------------ |
| 1          | Kiểu giao hàng                 |
| 2          | Kiểu bán lẻ                    |
| 3          | Kiểu chuyển kho                |
| 4          | Kiểu quà tặng ở hóa đơn bán lẻ |
| 5          | Kiểu nhà cung cấp              |
| 6          | Kiểu bán sỉ                    |
| 8          | Kiểu kiểm kho                  |
| 10         | Kiểu khác                      |
| 18         | Kiểu quà tặng ở đơn hàng       |