Quyết định 522/QĐ-TTYQG năm 2025 về “Tài liệu kỹ thuật đặc tả API Hệ thống cơ sở dữ liệu về dược” phiên bản 1.0 do Trung tâm Thông tin y tế Quốc gia, Bộ Y tế ban hành

BỘ Y TẾ
TRUNG TÂM THÔNG TIN Y TẾ QUỐC GIA
-------

CỘNG HÒA XÃ HỘI CHỦ NGHĨA VIỆT NAM
Độc lập - Tự do - Hạnh phúc
---------------

Số: 522/QĐ-TTYQG

Hà Nội, ngày 18 tháng 12 năm 2025

Nơi nhận:
- Như Điều 4;
- Bộ trưởng (để báo cáo);
- Các đồng chí Thứ trưởng (để báo cáo);
- Cục Khoa học công nghệ và Đào tạo;
- Cục Quản lý Dược;
- Sở Y tế các tỉnh, thành phố trực thuộc Trung ương;
- Công Thông tin điện tử Bộ y tế;
- Các đơn vị tại Điều 2(để thực hiện);
- Lưu: VT.

GIÁM ĐỐC




Đỗ Trường Duy

BỘ Y TẾ
TRUNG TÂM THÔNG TIN Y TẾ QUỐC GIA
-------

CỘNG HÒA XÃ HỘI CHỦ NGHĨA VIỆT NAM
Độc lập - Tự do - Hạnh phúc
---------------

Số: 522/QĐ-TTYQG

Hà Nội, ngày 18 tháng 12 năm 2025

Nơi nhận:
- Như Điều 4;
- Bộ trưởng (để báo cáo);
- Các đồng chí Thứ trưởng (để báo cáo);
- Cục Khoa học công nghệ và Đào tạo;
- Cục Quản lý Dược;
- Sở Y tế các tỉnh, thành phố trực thuộc Trung ương;
- Công Thông tin điện tử Bộ y tế;
- Các đơn vị tại Điều 2(để thực hiện);
- Lưu: VT.

GIÁM ĐỐC




Đỗ Trường Duy

STT

Thuật ngữ/Từ viết tắt

Mô tả

1

API

Application Programming Interface

Giao diện lập trình ứng dụng

2

HTTP

HyperText Transfer Protocol

Giao thức truyền tải siêu văn bản

3

HTTPS/TLS

Giao thức truyền dữ liệu an toàn qua mạng, sử dụng chứng chỉ TLS 1.3 để mã hóa. Bắt buộc cho tất cả API call.

4

JSON

JavaScript Object Notation

Định dạng dữ liệu nhẹ, dễ đọc, dùng để trao đổi thông tin giữa phần mềm và API.

5

OAuth 2.0

Tiêu chuẩn ủy quyền mở, sử dụng để xác thực và cấp quyền truy cập API mà không chia sẻ mật khẩu.

6

Token (Access Token)

Chuỗi mã hoá tạm thời được cấp sau khi xác thực, dùng để uỷ quyền các API Request. Token sẽ hết hạn sau một khoảng thời gian cụ thể

7

Cơ sở Dược

Tên gọi chung cho Cơ sở sản xuất/Cơ sở nhập khẩu/Cơ sở phân phối/Cơ sở bán lẻ dược phẩm

STT

Nội dung

Mô tả

1

Kiểu API

RESTful API

2

Giao thức

HTTPS

3

Phiên bản hiện hành

v2 (bắt buộc từ 01/01/2026)

4

Định dạng dữ liệu

JSON (UTF-8)

5

Xác thực

OAuth2 + Bearer Token

STT

Nội dung

Mô tả

1

Base URL Production

https://api.csdlduoc.com.vn/v2

2

Base URL Sandbox

https://api-sandbox.csdlduoc.com.vn/v2

STT

Nhóm API

Tên API

URL

1

Xác thực

Xác thực bằng tài khoản

POST /auth/login

2

Danh mục

Hoạt chất

GET /master/active-ingredients

3

Đơn vị tính

GET /master/units

4

Quốc gia

GET /master/countries

5

Nhóm thuốc

GET /master/drug-groups

6

Đường dùng

GET /master/routes

7

Nhà sản xuất

GET /master/manufactures

8

Tỉnh/Thành phố

GET /master/provinces

9

Xã/Phường

GET /master/communes

10

Thuốc

Danh sách thuốc

GET /master/drugs

11

Thông tin chi tiết thuốc

GET /master/drugs/{drug_id}

12

Giao dịch nhập - xuất - điều chuyển - kiểm kho

Tạo phiếu nhập kho

POST /transactions/stock-in

13

Xem thông tin chi tiết phiếu nhập kho

GET /transaction/stock- in/{transaction_id}

14

Tra cứu trạng thái xử lý phiếu nhập kho

GET /transaction/stock- in/{transaction_id}/status

15

Tạo phiếu xuất kho

POST /transactions/stock-out

16

Xem thông tin chi tiết phiếu xuất kho

GET /transactions/stock- out/{transaction_id}

17

Tra cứu trạng thái xử lý phiếu xuất kho

GET /transactions/stock- out/{transaction_id}/status

18

Tạo phiếu kiểm kho

POST /transactions/stock-taking

19

Tra cứu trạng thái/xem thông tin phiếu kiểm kho

GET /transactions/stock- taking/{transaction_id}

20

Tra cứu trạng thái xử lý phiếu kiểm kho

GET /transactions/stock- taking/{transaction_id}/status

21

Báo cáo tồn kho

Gửi báo cáo tồn kho theo tháng

POST /inventory-reports/monthly

22

Gửi báo cáo tồn kho theo quý

POST /inventory-reports/quarterly

23

Gửi báo cáo tồn kho theo năm

POST /inventory-reports/yearly

24

Xem chi tiết báo cáo tồn kho

GET /inventory-reports/{reportId}

25

Kiểm tra trạng thái xử lý báo cáo

GET /inventory- reports/{reportId}/status

26

Hoá đơn bán lẻ thuốc

Gửi dữ liệu hoá đơn bán lẻ thuốc

POST /invoices

27

Xem thông tin chi tiết hoá đơn bán lẻ thuốc

GET /invoices/{invoiceId}

28

Tra cứu trạng thái xử lý hoá đơn bán lẻ thuốc

GET /invoices/{invoiceId}/status

TT

Thuộc tính

Bắt buộc

Giá trị

Mô tả

1

Content-Type

x

application/json

TT

Tên trường

Kiểu dữ liệu

Độ dài tối đa

Bắt buộc

Mô tả

1

username

string

200

x

Tên đăng nhập của cơ sở dược được cấp phát để liên thông dữ liệu.

2

password

string

200

x

Mật khẩu đăng nhập của cơ sở kinh doanh dược được cấp đã được mã hoá Base64.

Ví dụ: nếu mật khẩu đăng nhập của cơ sở kinh doanh dược là “123456a@” thì trường này phải truyền giá trị là “MTIzNDU2YUA=”

TT

Tên trường

Kiểu dữ liệu

Mô tả

1

access_token

string

JWT Token được sử dụng để gọi các API nghiệp vụ

2

token_type

string

Loại token. Mặc định là: “Bearer”

3

expires_in

integer

Thời gian hiệu lực của access_token (giây).

TT

Thuộc tính

Bắt buộc

Giá trị

Mô tả

1

Content-Type

x

application/json

2

Authorization

x

Bearer {access_token}

access_token

nhận được từ các API xác thực

TT

Thuộc tính

Kiểu dữ liệu

Bắt buộc

Mô tả

1

page

integer

Số trang cần lấy (mặc định là 1)

2

page_size

integer

Số bản ghi trên mỗi trang (mặc định là 20, tối đa 50)

TT

Tên trường

Kiểu dữ liệu

Mô tả

1

page

integer

Số trang dữ liệu

2

total

integer

Tổng số bản ghi

3

data

array

Danh sách các hoạt chất

3.1

id

string

Mã hoạt chất

3.2

name

string

Tên hoạt chất

TT

Thuộc tính

Bắt buộc

Giá trị

Mô tả

1

Content-Type

x

application/json

2

Authorization

x

Bearer {access_token}

access_token nhận được từ các API xác thực

TT

Thuộc tính

Kiểu dữ liệu

Bắt buộc

Mô tả

1

page

integer

Số trang cần lấy (mặc định là 1)

2

page_size

integer

Số bản ghi trên mỗi trang (mặc định là 20, tối đa 50)

TT

Tên trường

Kiểu dữ liệu

Mô tả

1

page

integer

Số trang dữ liệu

2

total

integer

Tổng số bản ghi

3

data

array

Danh sách các đơn vị tính

3.1

id

string

Mã đơn vị tính

3.2

name

string

Tên đơn vị tính

TT

Thuộc tính

Bắt buộc

Giá trị

Mô tả

1

Content-Type

x

application/json

2

Authorization

x

Bearer {access_token}

access_token nhận được từ các API xác thực

TT

Thuộc tính

Kiểu dữ liệu

Bắt buộc

Mô tả

1

page

integer

Số trang cần lấy (mặc định là 1)

2

page_size

integer

Số bản ghi trên mỗi trang (mặc định là 20, tối đa 50)

TT

Tên trường

Kiểu dữ liệu

Mô tả

1

page

integer

Số trang dữ liệu

2

total

integer

Tổng số bản ghi

3

data

array

Danh sách các đơn vị tính

3.1

id

string

Mã quốc gia (ISO-3166)

3.2

name

string

Tên quốc gia

TT

Thuộc tính

Bắt buộc

Giá trị

Mô tả

1

Content-Type

x

application/json

2

Authorization

x

Bearer {access_token}

access_token nhận được từ các API xác thực

TT

Thuộc tính

Kiểu dữ liệu

Bắt buộc

Mô tả

1

page

integer

Số trang cần lấy (mặc định là 1)

2

page_size

integer

Số bản ghi trên mỗi trang (mặc định là 20, tối đa 50)

TT

Tên trường

Kiểu dữ liệu

Mô tả

1

page

integer

Số trang dữ liệu

2

total

integer

Tổng số bản ghi

3

data

array

Danh sách nhóm thuốc

3.1

id

string

Mã nhóm thuốc

3.2

name

string

Tên nhóm thuốc

TT

Thuộc tính

Bắt buộc

Giá trị

Mô tả

1

Content-Type

x

application/json

2

Authorization

x

Bearer {access_token}

access_token nhận được từ các API xác thực

TT

Thuộc tính

Kiểu dữ liệu

Bắt buộc

Mô tả

1

page

integer

Số trang cần lấy (mặc định là 1)

2

page_size

integer

Số bản ghi trên mỗi trang (mặc định là 20, tối đa 50)

TT

Tên trường

Kiểu dữ liệu

Mô tả

1

page

integer

Số trang dữ liệu

2

total

integer

Tổng số bản ghi

3

data

array

Danh sách các đơn vị tính

3.1

id

string

Mã đường dùng

3.2

name

string

Tên đường dùng

TT

Thuộc tính

Bắt buộc

Giá trị

Mô tả

1

Content-Type

x

application/json

2

Authorization

x

Bearer {access_token}

access_token nhận được từ các API xác thực

TT

Thuộc tính

Kiểu dữ liệu

Bắt buộc

Mô tả

1

page

integer

Số trang cần lấy (mặc định là 1)

2

page_size

integer

Số bản ghi trên mỗi trang (mặc định là 20, tối đa 50)

TT

Tên trường

Kiểu dữ liệu

Mô tả

1

page

integer

Số trang dữ liệu

2

total

integer

Tổng số bản ghi

3

data

array

Danh sách các đơn vị tính

3.1

id

string

Mã nhà sản xuất

3.2

name

string

Tên nhà sản xuất

3.3

country_id

string

Mã quốc gia

3.4

province_id

string

Địa chỉ của nhà sản xuất - Mã tỉnh/thành phố

3.5

commune_id

string

Địa chỉ của nhà sản xuất - Mã xã/phường

3.6

street

string

Địa chỉ của nhà sản xuất - Số nhà, tên đường, …

TT

Thuộc tính

Bắt buộc

Giá trị

Mô tả

1

Content-Type

x

application/json

2

Authorization

x

Bearer {access_token}

access_token nhận được từ các API xác thực

TT

Thuộc tính

Kiểu dữ liệu

Bắt buộc

Mô tả

1

page

integer

Số trang cần lấy (mặc định là 1)

2

page_size

integer

Số bản ghi trên mỗi trang (mặc định là 20, tối đa 50)

TT

Tên trường

Kiểu dữ liệu

Mô tả

1

page

integer

Số trang dữ liệu

2

total

integer

Tổng số bản ghi

3

data

array

Danh sách Tỉnh/Thành phố

3.1

id

string

Mã tỉnh/thành phố

3.2

name

string

Tên tỉnh/thành phố

TT

Thuộc tính

Bắt buộc

Giá trị

Mô tả

1

Content-Type

x

application/json

2

Authorization

x

Bearer {access_token}

access_token nhận được từ các API xác thực

TT

Thuộc tính

Kiểu dữ liệu

Bắt buộc

Mô tả

1

page

integer

Số trang cần lấy (mặc định là 1)

2

page_size

integer

Số bản ghi trên mỗi trang (mặc định là 20, tối đa 50)

3

province_id

string

Mã tỉnh/thành phố

TT

Tên trường

Kiểu dữ liệu

Mô tả

1

page

integer

Số trang dữ liệu

2

total

integer

Tổng số bản ghi

3

data

array

Danh sách Xã/Phường

3.1

id

string

Mã Xã/Phường

3.2

name

string

Tên Xã/Phường

3.3

province_id

string

Mã Tỉnh/Thành phố

TT

Thuộc tính

Bắt buộc

Giá trị

Mô tả

1

Content-Type

x

application/json

2

Authorization

x

Bearer {access_token}

access_token nhận được từ các API xác thực

TT

Thuộc tính

Kiểu dữ liệu

Bắt buộc

Mô tả

1

page

integer

Số trang cần lấy (mặc định là 1)

2

page_size

integer

Số bản ghi trên mỗi trang (mặc định là 20, tối đa 50)

TT

Tên trường

Kiểu dữ liệu

Mô tả

1

page

integer

Số trang dữ liệu

2

total

integer

Tổng số bản ghi

3

data

array

Danh sách các thuốc

3.1

id

string

Mã định danh thuốc

3.2

name

string

Tên thuốc

3.3

drug_group_id

string

Mã nhóm thuốc

3.4

registration_number

string

Số giấy phép lưu hành

3.5

active_ingredient_list

array

Danh sách các hoạt chất

3.5.1

active_ingredient_list[].id

string

Mã hoạt chất

3.5.2

active_ingredient_list[].name

string

Tên hoạt chất

3.5.3

active_ingredient_list[].is_main_active_ingre dient

boolean

Cho biết hoạt chất có phải là hoạt chất chính không. Các giá trị:

- true: Đây là hoạt chất chính

- false: Không phải là hoạt chất chính

3.6

strength

string

Hàm lượng

3.7

route_id

string

Mã đường dùng

3.8

prescription_status

integer

Phân loại thuốc kê đơn. Chi tiết tại mục 6.4.4.

3.9

special_control_type

integer

Phân loại thuốc kiểm soát đặc biệt. Chi tiết tại mục 6.4.5.

3.10

packagings

array

Các quy cách đóng gói của thuốc

3.10.1

packagings[].unit_id

string

Mã đơn vị tính

3.10.2

packagings[].unit_name

string

Tên đơn vị tính

3.10.3

packagings[].conversion_rate_to_base

integer

Tỷ lệ quy đổi so với đơn vị tính cơ bản

3.10.4

packagings[].gtin

string

Mã GTIN tương ứng với cấp độ đóng gói

3.10.5

packagings[].is_basic_unit

boolean

Cho biết đây có phải đơn vị tính cơ bản không.

- true: Đơn vị tính cơ bản

- false : Không phải đơn vị tính cơ bản.

3.11

manufacturer

object

Thông tin nhà sản xuất

3.11.1

manufacturer.id

string

Mã nhà sản xuất

3.11.2

manufacturer.name

string

Tên nhà sản xuất

3.11.3

manufacturer.country

string

Mã quốc gia sản xuất

3.12

approval_date

date

Ngày cấp số giấy phép lưu hành.

3.13

expiry_date

date

Ngày hết hiệu lực lưu hành.

TT

Thuộc tính

Bắt buộc

Giá trị

Mô tả

1

Content-Type

x

application/json

2

Authorization

x

Bearer {access_token}

access_token nhận được từ các API xác thực

TT

Thuộc tính

Kiểu dữ liệu

Độ dài tối đa

Bắt buộc

Mô tả

1

drug_id

string

20

x

Mã định danh thuốc/Số giấy phép lưu hành

TT

Tên trường

Kiểu dữ liệu

Mô tả

1

id

string

Mã định danh thuốc

2

name

string

Tên thuốc

3

registration_number

string

Số giấy phép lưu hành

4

drug_group_id

string

Mã nhóm thuốc

5

active_ingredient_list

array

Danh sách các hoạt chất

5.1

active_ingredient_list[].id

string

Mã hoạt chất

5.2

active_ingredient_list[].name

string

Tên hoạt chất

5.3

active_ingredient_list[].is_main_active_ingredient

boolean

Cho biết hoạt chất có phải là hoạt chất chính không. Các giá trị:

- true: Đây là hoạt chất chính

- false: Không phải là hoạt chất chính

6

strength

string

Hàm lượng

7

route_id

string

Mã đường dùng

8

prescription_status

integer

Phân loại thuốc kê đơn. Chi tiết tại mục 6.4.4.

9

special_control_type

integer

Phân loại thuốc kiểm soát đặc biệt. Chi tiết tại mục 6.4.5.

10

packagings

array

Các quy cách đóng gói của thuốc

10.1

packagings[].unit_id

string

Mã đơn vị tính

10.2

packagings[].unit_name

string

Tên đơn vị tính

10.3

packagings[].quantity

integer

Số lượng quy đổi so với đơn vị tính cơ bản

10.4

packagings[].gtin

string

Mã GTIN tương ứng với cấp độ đóng gói

10.5

packagings[].is_basic_unit

boolean

Cho biết đây có phải đơn vị tính cơ bản không. Các giá trị:

- true: Đơn vị tính cơ bản

- false : Không phải đơn vị tính cơ bản.

11

manufacturer

object

Nhà sản xuất

11.1

manufacturer.id

string

Mã nhà sản xuất

11.2

manufacturer.name

string

Tên nhà sản xuất

11.3

manufacturer.country

string

Mã quốc gia sản xuất

12

approval_date

date

Ngày cấp số giấy phép lưu hành.

13

expiry_date

date

Ngày hết hiệu lực lưu hành.

TT

Thuộc tính

Bắt buộc

Giá trị

Mô tả

1

Content-Type

x

application/json

2

Authorization

x

Bearer {access_token}

access_token nhận được từ các API xác thực

TT

Tên trường

Kiểu dữ liệu

Độ dài tối đa

Bắt buộc

Mô tả

1

transaction_date

datetime

x

Ngày/giờ nhập kho.

2

reason

string

20

x

Lý do nhập/Loại phiếu nhập kho. Chi tiết tại Mục 6.4.1.

3

supplier_id

string

50

Mã định danh nhà cung cấp. Nếu reason là “supplier”.

4

source_store_id

string

50

Mã định danh chi nhánh xuất kho (nếu cơ sở có chuỗi nhà thuốc) trong trường hợp reason là “transfer-in”

5

source_warehouse_id

string

50

Mã kho xuất trong trường hợp reason là “transfer-in”

6

target_store_id

string

50

Mã định danh chi nhánh nhập kho (nếu cơ sở có chuỗi nhà thuốc) trong trường hợp reason là “transfer-in”

7

target_warehouse_id

string

50

Mã kho nhập trong trường hợp reason là “transfer-in”

8

reference_number

string

50

x

Số chứng từ nhập kho

9

note

string

500

Ghi chú

10

items

array

x

Danh sách thuốc trong phiếu nhập

10.1

items[].drug_id

string

20

x

Mã định danh thuốc

10.2

items[].unit_id

string

20

x

Mã đơn vị tính

10.3

items[].quantity

integer

x

Số lượng

10.4

items[].batch_no

string

50

x

Số lô sản xuất

10.5

items[].expiry_date

date

x

Hạn sử dụng

10.6

items[].manufacturer

object

Thông tin chi tiết nhà sản xuất

10.6.1

items[].manufacturer.id

string

20

Mã nhà sản xuất

10.6.2

items[].manufacturer.name

string

200

Tên nhà sản xuất

10.6.3

items[].manufacturer.country

string

5

Mã quốc gia sản xuất

10.7

items[].gtin

string

50

Mã GTIN tương ứng với từng cấp độ đóng gói

10.8

items[].price

float

Đơn giá (độ chính xác tới 2 chữ số thập phân).

TT

Tên trường

Kiểu dữ liệu

Mô tả

1

transaction_id

string

Mã ID của giao dịch

2

status

string

Trạng thái tiếp nhận/xử lý của hệ thống. Chi tiết tại Mục 6.2.

TT

Thuộc tính

Bắt buộc

Giá trị

Mô tả

1

Content-Type

x

application/json

2

Authorization

x

Bearer {access_token}

access_token nhận được từ các API xác thực

TT

Thuộc tính

Kiểu dữ liệu

Độ dài tối đa

Bắt buộc

Mô tả

1

transaction_id

string

50

x

Mã Id của phiếu nhập kho

TT

Tên trường

Kiểu dữ liệu

Mô tả

1

transaction_id

string

Mã ID của phiếu nhập kho

2

transaction_date

datetime

Ngày/giờ nhập kho

3

reason

string

Lý do nhập. Chi tiết tại Mục 6.4.1

4

supplier_id

string

Mã định danh nhà cung cấp trong trường hợp reason có giá trị là “supplier”

5

source_store_id

string

Mã định danh chi nhánh nhập kho (nếu cơ sở có chuỗi nhà thuốc) trong trường hợp reason là “transfer-in”

6

source_warehouse_id

string

Mã kho nhập trong trường hợp reason là “transfer-in”

7

target_store_id

string

Mã định danh chi nhánh xuất kho (nếu cơ sở có chuỗi nhà thuốc) trong trường hợp reason là “transfer-in”

8

target_warehouse_id

string

Mã kho xuất trong trường hợp reason là “transfer-in”

9

reference_number

string

Số chứng từ

10

items

array

Danh sách thuốc có trong phiếu nhập

10.1

items[].drug_id

string

Mã định danh thuốc

10.2

items[].unit_id

string

Mã đơn vị tính

10.3

items[].quantity

integer

Số lượng

10.4

items[].batch_no

string

Số lô sản xuất

10.5

items[].expiry_date

date

Hạn sử dụng

10.6

items[].manufacturer

object

Thông tin nhà sản xuất

10.6.1

items[].manufacturer.id

string

Mã nhà sản xuất

10.6.2

items[].manufacturer.name

string

Tên nhà sản xuất

10.6.3

items[].manufacturer.country

string

Mã quốc gia sản xuất

10.7

items[].gtin

string

Mã gtin tương ứng với cấp độ đóng gói

10.8

items[].price

float

Đơn giá (độ chính xác tới 2 chữ số thập phân).

11

status

string

Trạng thái tiếp nhận/xử lý của hệ thống đối với phiếu nhập kho.

TT

Thuộc tính

Bắt buộc

Giá trị

Mô tả

1

Content-Type

x

application/json

2

Authorization

x

Bearer {access_token}

access_token nhận được từ các API xác thực

TT

Thuộc tính

Kiểu dữ liệu

Độ dài tối đa

Bắt buộc

Mô tả

1

transaction_id

string

50

x

Mã Id của giao dịch nhập kho

TT

Tên trường

Kiểu dữ liệu

Mô tả

1

transaction_id

string

Mã ID của giao dịch

2

status

string

Trạng thái xử lý của hệ thống. Tham khảo Mục 6.2.

3

messages

array[string]

Danh sách các thông báo lỗi của hệ thống nếu có.

4

submitted_at

datetime

Thời gian hệ thống tiếp nhận.

TT

Thuộc tính

Bắt buộc

Giá trị

Mô tả

1

Content-Type

x

application/json

2

Authorization

x

Bearer {access_token}

access_token nhận được từ các API xác thực

TT

Tên trường

Kiểu dữ liệu

Độ dài tối đa

Bắt buộc

Mô tả

1

transaction_date

dateti me

x

Ngày/giờ xuất kho

2

reason

string

20

x

Loại phiếu xuất kho/Lý do xuất kho. Chi tiết tại Mục 6.4.2.

3

source_store_id

string

50

Mã định danh chi nhánh xuất kho (nếu cơ sở có chuỗi nhà thuốc) trong trường hợp reason là “transfer-out”

4

source_warehouse_id

string

50

Mã kho xuất trong trường hợp là phiếu xuất điều chuyển (giá trị của reason là transfer-out)

5

target_store_id

string

50

Mã định danh chi nhánh nhập kho (nếu cơ sở có chuỗi nhà thuốc) trong trường hợp reason là “transfer-out”

6

target_warehouse_id

string

50

Mã kho nhập trong trường hợp là phiếu xuất điều chuyển (giá trị của reason là transfer-out)

7

supplier_id

string

50

Mã định danh nhà cung cấp trong trường hợp xuất hàng trả lại nhà cung cấp (giá trị của trường reason là “return”)

8

reference_number

string

50

x

Số chứng từ xuất kho

9

note

string

500

Ghi chú

10

items

array

x

Danh sách thuốc trong phiếu xuất kho

10.1

items[].drug_id

string

20

x

Mã định danh thuốc

10.2

items[].unit_id

string

20

x

Mã đơn vị tính

10.3

items[].quantity

integer

x

Số lượng

10.4

items[].batch_no

string

20

x

Số lô sản xuất

10.5

items[].expiry_date

date

x

Hạn sử dụng

10.6

items[].manufacturer

object

Nhà sản xuất

10.6.1

items[].manufacturer.id

string

20

Mã nhà sản xuất

10.6.2

items[].manufacturer.name

string

200

Tên nhà sản xuất

10.6.3

items[].manufacturer.count ry

string

5

Mã quốc gia sản xuất

10.7

items[].gtin

string

50

Mã GTIN tương ứng với từng cấp độ đóng gói

10.8

items[].price

float

Đơn giá (độ chính xác tới 2 chữ số thập phân).

TT

Tên trường

Kiểu dữ liệu

Mô tả

1

transaction_id

string

Mã ID của giao dịch

TT

Thuộc tính

Bắt buộc

Giá trị

Mô tả

1

Content-Type

x

application/json

2

Authorization

x

Bearer {access_token}

access_token nhận được từ các API xác thực

TT

Thuộc tính

Kiểu dữ liệu

Độ dài tối đa

Bắt buộc

Mô tả

1

transaction_id

string

50

x

Mã Id của giao dịch nhập kho

TT

Tên trường

Kiểu dữ liệu

Mô tả

1

transaction_id

string

Mã ID của giao dịch

2

transaction_date

datetime

Ngày giờ xuất kho

3

reason

string

Loại phiếu xuất kho/Lý do xuất. Chi tiết tại Mục 6.4.2.

4

source_store_id

string

Mã định danh chi nhánh xuất kho (nếu cơ sở có chuỗi nhà thuốc) trong trường hợp reason là “transfer-out”

5

source_warehouse_id

string

Mã định danh kho xuất trong trường hợp phiếu xuất điều chuyển (giá trị của reason là “transfer-out”)

6

target_store_id

string

Mã định danh chi nhánh nhập kho (nếu cơ sở có chuỗi nhà thuốc) trong trường hợp reason là “transfer-out”

7

target_warehouse_id

string

Mã định danh kho nhập trong trường hợp phiếu xuất điều chuyển (giá trị của reason là “transfer-out”)

8

supplier_id

datetime

Mã định danh nhà cung cấp trường trường phiếu xuất trả nhà cung cấp (giá trị reason là “return”)

9

reference_number

string

Số chứng từ

10

note

string

Ghi chú

11

items

array

Danh sách thuốc có trong phiếu nhập

11.1

items[].drug_id

string

Mã định danh thuốc

11.2

items[].unit_id

string

Mã đơn vị tính

11.3

items[].quantity

integer

Số lượng

11.4

items[].batch_no

string

Số lô sản xuất

11.5

items[].expiry_date

date

Hạn sử dụng

11.6

items[].manufacturer

object

Thông tin nhà sản xuất

11.6.1

items[].manufacturer.id

string

Mã nhà sản xuất

11.6.2

items[].manufacturer.name

string

Tên nhà sản xuất

11.6.3

items[].manufacturer.country

string

Mã quốc gia sản xuất

11.7

items[].gtin

string

Mã GTIN tương ứng với cấp độ đóng gói

11.8

items[].price

float

Đơn giá (độ chính xác tới 2 chữ số thập phân).

12

status

string

Trạng thái xử lý của hệ thống đối với phiếu xuất kho. Chi tiết tại Mục 6.2.

TT

Thuộc tính

Bắt buộc

Giá trị

Mô tả

1

Content-Type

x

application/json

2

Authorization

x

Bearer {access_token}

access_token nhận được từ các API xác thực

TT

Thuộc tính

Kiểu dữ liệu

Độ dài tối đa

Bắt buộc

Mô tả

1

transaction_id

string

50

x

Mã Id của giao dịch xuất kho

TT

Tên trường

Kiểu dữ liệu

Mô tả

1

transaction_id

string

Mã ID của giao dịch

2

status

string

Trạng thái xử lý của hệ thống. Chi tiết tại Mục 6.2.

3

messages

array[string]

Danh sách các thông báo lỗi của hệ thống nếu có.

4

submitted_at

datetime

Thời gian hệ thống tiếp nhận.

TT

Thuộc tính

Bắt buộc

Giá trị

Mô tả

1

Content-Type

x

application/json

2

Authorization

x

Bearer {access_token}

access_token nhận được từ các API xác thực

TT

Tên trường

Kiểu dữ liệu

Độ dài tối đa

Bắt buộc

Mô tả

1

transaction_date

datetime

x

Ngày/giờ kiểm kho.

2

store_id

string

50

Mã chi nhánh (trong trường hợp cơ sở kinh doanh dược có nhiều chi nhánh).

3

warehouse_id

string

50

Mã kho (trong trường hợp cơ sở kinh doanh dược hoặc các chi nhánh của cơ sở kinh doanh dược có nhiều kho).

4

reference_number

string

50

x

Số chứng từ kiểm kho

5

note

string

500

Ghi chú

6

items

array

x

Danh sách thuốc kiểm kho

6.1

items[].drug_id

string

20

x

Mã định danh thuốc

6.2

items[].unit_id

string

20

x

Mã đơn vị tính

6.3

items[].quantity

integer

x

Số lượng

6.4

items[].batch_no

string

50

x

Số lô sản xuất

6.5

items[].expiry_date

date

x

Hạn sử dụng

6.6

items[].manufacturer

object

Thông tin nhà sản xuất

6.6.1

items[].manufacturer.id

string

20

Mã nhà sản xuất

6.6.2

items[].manufacturer.name

string

200

Tên nhà sản xuất

6.6.3

items[].manufacturer.country

string

5

Mã quốc gia sản xuất

6.7

items[].gtin

string

50

Mã GTIN tương ứng với cấp độ đóng gói

6.8

items[].price

float

Đơn giá (độ chính xác tới 2 chữ số thập phân).

6.9

items[].system_quantity

int

x

Tồn hệ thống

6.10

items[].actual_quantiy

int

x

Tồn thực tế

TT

Tên trường

Kiểu dữ liệu

Mô tả

1

transaction_id

string

Mã ID của giao dịch

2

status

string

Trạng thái xử lý của hệ thống. Chi tiết tại Mục 6.2

TT

Thuộc tính

Bắt buộc

Giá trị

Mô tả

1

Content-Type

x

application/json

2

Authorization

x

Bearer {access_token}

access_token nhận được từ các API xác thực

TT

Thuộc tính

Kiểu dữ liệu

Độ dài tối đa

Bắt buộc

Mô tả

1

transaction_id

string

50

x

Mã Id của giao dịch nhập kho

TT

Tên trường

Kiểu dữ liệu

Mô tả

1

transaction_id

string

Mã ID của giao dịch

2

transaction_date

string

Ngày kiểm kho

3

facility_id

string

Mã chi nhánh (trong trường hợp cơ sở kinh doanh dược có nhiều chi nhánh).

4

warehouse_id

string

Mã kho (trong trường hợp cơ sở kinh doanh dược hoặc các chi nhánh của cơ sở kinh doanh dược có nhiều kho).

5

reference_number

string

Số chứng từ

6

note

string

Ghi chú

7

items

array

Danh sách thuốc trong phiếu kiểm kho

7.1

items[].drug_id

string

Mã định danh thuốc

7.2

items[].unit_id

string

Mã đơn vị tính

7.3

items[].quantity

integer

Số lượng

7.4

items[].batch_no

string

Số lô sản xuất

7.5

items[].expiry_date

date

Hạn sử dụng

7.6

items[].manufacturer

object

Mã định danh nhà sản xuất

7.6.1

items[].manufacturer.id

string

Mã nhà sản xuất

7.6.2

items[].manufacturer.name

string

Tên nhà sản xuất

7.6.3

items[].manufacturer.country

string

Mã quốc gia sản xuất

7.6.4

items[].gtin

string

Mã GTIN tương ứng với cấp độ đóng gói

7.7

items[].price

float

Đơn giá (độ chính xác tới 2 chữ số thập phân).

7.8

items[].system_quantity

integer

Tồn hệ thống

7.9

items[].actual_quantity

integer

Tồn thực tế

TT

Thuộc tính

Bắt buộc

Giá trị

Mô tả

1

Content-Type

x

application/json

2

Authorization

x

Bearer {access_token}

access_token nhận được từ các API xác thực

TT

Thuộc tính

Kiểu dữ liệu

Độ dài tối đa

Bắt buộc

Mô tả

1

transaction_id

string

50

x

Mã Id của giao dịch kiểm kho

TT

Tên trường

Kiểu dữ liệu

Mô tả

1

transaction_id

string

Mã ID của giao dịch

2

status

string

Trạng thái xử lý của hệ thống. Chi tiết tại Mục 6.2.

3

messages

array[string]

Danh sách các thông báo lỗi của hệ thống nếu có.

4

submitted_at

datetime

Thời gian hệ thống tiếp nhận.

TT

Thuộc tính

Bắt buộc

Giá trị

Mô tả

1

Content-Type

x

application/json

2

Authorization

x

Bearer {access_token}

access_token nhận được từ các API xác thực

TT

Tên trường

Kiểu dữ liệu

Độ dài tối đa

Bắt buộc

Mô tả

1

period

string

10

x

Tháng báo cáo. Định dạng: YYYY-MM

2

store_id

string

50

Mã chi nhánh (trong trường hợp cơ sở kinh doanh dược có nhiều chi nhánh).

3

warehouse_id

string

50

Mã kho (trong trường hợp cơ sở kinh doanh dược hoặc các chi nhánh của cơ sở kinh doanh dược có nhiều kho).

4

items

array

x

Danh sách thuốc kiểm kho

4.1

items[].drug_id

string

20

x

Mã định danh thuốc

4.2

items[].unit_id

string

20

x

Mã đơn vị tính

4.3

items[].batch_no

string

50

x

Số lô sản xuất

4.4

items[].expiry_date

date

x

Hạn sử dụng

4.5

items[].manufacturer

object

Thông tin nhà sản xuất

4.5.1

items[].manufacturer.id

string

20

Mã nhà sản xuất

4.5.2

items[].manufacturer.name

string

200

Tên nhà sản xuất

4.5.3

items[].manufacturer.country

string

5

Mã quốc gia sản xuất

4.6

items[].gtin

string

50

Mã GTIN tương ứng với cấp độ đóng gói

4.7

items[].price

float

Đơn giá (độ chính xác tới 2 chữ số thập phân).

4.8

items[].quantity_begin

integer

x

Số lượng tồn đầu tháng

4.9

items[].quantity_in

integer

x

Số lượng nhập trong tháng

4.10

items[].quantity_out

integer

x

Số lượng xuất trong tháng

4.11

items[].quantity_end

integer

x

Số lượng tồn cuối tháng

TT

Tên trường

Kiểu dữ liệu

Mô tả

1

report_id

string

Mã ID của báo cáo

2

status

string

Trạng thái tiếp nhận/xử lý báo cáo. Chi tiết tại Mục 6.2

TT

Thuộc tính

Bắt buộc

Giá trị

Mô tả

1

Content-Type

x

application/json

2

Authorization

x

Bearer {access_token}

access_token nhận được từ các API xác thực

TT

Tên trường

Kiểu dữ liệu

Độ dài tối đa

Bắt buộc

Mô tả

1

period

string

10

x

Quý báo cáo. Định dạng: YYYY-Qn. Ví dụ: 2025-Q1, 2025-Q2, 2025-Q3, 2025-Q4

2

store_id

string

50

Mã chi nhánh (trong trường hợp cơ sở kinh doanh dược có nhiều chi nhánh).

3

warehouse_id

string

50

Mã kho (trong trường hợp cơ sở kinh doanh dược hoặc các chi nhánh của cơ sở kinh doanh dược có nhiều kho).

4

items

array

x

Danh sách thuốc kiểm kho

4.1

items[].drug_id

string

20

x

Mã định danh thuốc

4.2

items[].unit_id

string

20

x

Mã đơn vị tính

4.3

items[].batch_no

string

50

x

Số lô sản xuất

4.4

items[].expiry_date

date

x

Hạn sử dụng

4.5

items[].manufacturer

object

Thông tin nhà sản xuất

4.5.

items[].manufacturer.id

string

20

Mã nhà sản xuất

4.5.

items[].manufacturer.name

string

200

Tên nhà sản xuất

4.5.

items[].manufacturer.country

string

5

Mã quốc gia sản xuất

4.5.

items[].gtin

string

50

Mã GTIN tương ứng với cấp độ đóng gói

4.6

items[].price

float

Đơn giá (độ chính xác tới 2 chữ số thập phân).

4.7

items[].quantity_begin

integer

x

Số lượng tồn đầu tháng

4.8

items[].quantity_in

integer

x

Số lượng nhập trong tháng

4.9

items[].quantity_out

integer

x

Số lượng xuất trong tháng

4.10

items[].quantity_end

integer

x

Số lượng tồn cuối tháng

TT

Tên trường

Kiểu dữ liệu

Mô tả

1

report_id

string

Mã ID của báo cáo

2

status

string

Trạng thái tiếp nhận/xử lý báo cáo. Chi tiết tại Mục 6.2

TT

Thuộc tính

Bắt buộc

Giá trị

Mô tả

1

Content-Type

x

application/json

2

Authorization

x

Bearer {access_token}

access_token nhận được từ các API xác thực

TT

Tên trường

Kiểu dữ liệu

Độ dài tối đa

Bắt buộc

Mô tả

1

period

string

4

x

Năm báo cáo. Ví dụ: 2025, 2026

2

store_id

string

50

Mã chi nhánh (trong trường hợp cơ sở kinh doanh dược có nhiều chi nhánh).

3

warehouse_id

string

50

Mã kho (trong trường hợp cơ sở kinh doanh dược hoặc các chi nhánh của cơ sở kinh doanh dược có nhiều kho).

4

items

array

x

Danh sách thuốc

4.1

items[].drug_id

string

x

Mã định danh thuốc

4.2

items[].unit_id

string

x

Mã đơn vị tính

4.3

items[].batch_no

string

x

Số lô sản xuất

4.4

items[].expiry_date

date

x

Hạn sử dụng

4.5

items[].manufacturer

object

Mã định danh nhà sản xuất

4.5.1

items[].manufacturer.id

string

Mã nhà sản xuất

4.5.2

items[].manufacturer.name

string

Tên nhà sản xuất

4.5.3

items[].manufacturer.country

string

Mã quốc gia sản xuất

4.6

items[].gtin

string

Mã GTIN tương ứng với cấp độ đóng gói

4.7

items[].price

float

Đơn giá (độ chính xác tới 2 chữ số thập phân).

4.8

items[].quantity_begin

integer

x

Số lượng tồn đầu năm

4.9

items[].quantity_in

integer

x

Số lượng nhập trong năm

4.10

items[].quantity_out

integer

x

Số lượng xuất trong năm

4.11

items[].quantity_end

integer

x

Số lượng tồn cuối năm

TT

Tên trường

Kiểu dữ liệu

Mô tả

1

report_id

string

Mã ID của báo cáo

2

status

string

Trạng thái tiếp nhận/xử lý báo cáo. Chi tiết tại Mục 6.2

TT

Thuộc tính

Bắt buộc

Giá trị

Mô tả

1

Content-Type

x

application/json

2

Authorization

x

Bearer {access_token}

access_token nhận được từ các API xác thực

TT

Thuộc tính

Kiểu dữ liệu

Độ dài tối đa

Bắt buộc

Mô tả

1

report_id

string

50

x

Mã Id của báo cáo tồn kho đã gửi

TT

Tên trường

Kiểu dữ liệu

Mô tả

1

report_id

string

Mã ID của báo cáo

2

type

string

Loại báo cáo. Chi tiết tại Mục 6.4.3.

3

period

string

Chu kỳ báo cáo.

- Nếu chu kỳ báo cáo là tháng (monthly) thì giá trị có định dạng: YYYY-MM. Ví dụ: 2025-09, 2025-10, ….

- Nếu chu kỳ báo cáo là quý (quarter) thì giá trị có định dạng: YYYY- Qn. Ví dụ: 2025-Q1, 2025-Q2, 2025-Q3, 2025-Q4.

- Nếu chu kỳ báo cáo là năm (yearly) thì giá trị có định dạng: YYYY. Ví dụ: 2025, 2026, …

4

store_id

string

Mã chi nhánh trong trường hợp cơ sở có chuỗi nhà thuốc

5

warehouse_id

string

Mã kho trong trường hợp quản lý nhiều kho

6

items

array

Danh sách thuốc trong báo cáo tồn kho

6.1

items[].drug_id

string

Mã định danh thuốc

6.2

items[].unit_id

string

Mã đơn vị tính

6.3

items[].batch_no

string

Số lô sản xuất

6.4

items[].expiry_date

date

Hạn sử dụng

6.5

items[].manufacturer

object

Thông tin nhà sản xuất

6.5.1

items[].manufacturer.id

string

Mã nhà sản xuất

6.5.2

items[].manufacturer.name

string

Tên nhà sản xuất

6.5.3

items[].manufacturer.country

string

Mã quốc gia sản xuất

6.5.4

items[].gtin

string

Mã GTIN tương ứng với cấp độ đóng gói

6.6

items[].price

float

Đơn giá (độ chính xác tới 2 chữ số thập phân).

6.7

items[].quantity_begin

integer

Số lượng tồn đầu tháng

6.8

items[].quantity_in

integer

Số lượng nhập trong tháng

6.9

items[].quantity_out

integer

Số lượng xuất trong tháng

6.10

items[].quantity_end

integer

Số lượng tồn cuối tháng

7

status

string

Trạng thái xử lý của hệ thống. Tham khảo tại Mục 6.2. Bảng mã trạng thái xử lý của hệ thống.

TT

Thuộc tính

Bắt buộc

Giá trị

Mô tả

1

Content-Type

x

application/json

2

Authorization

x

Bearer {access_token}

access_token nhận được từ các API xác thực

TT

Thuộc tính

Kiểu dữ liệu

Độ dài tối đa

Bắt buộc

Mô tả

1

report_id

string

50

x

Mã Id của báo cáo

TT

Tên trường

Kiểu dữ liệu

Mô tả

1

report_id

string

Mã ID của báo cáo

2

store_id

string

Mã ID của chi nhánh trường hợp cơ sở gồm chuỗi nhà thuốc

3

warehouse_id

string

Mã ID của kho trong trường hợp có nhiều kho

4

type

string

Loại báo cáo. Chi tiết tại Mục 6.4.3

5

period

string

Chu kỳ báo cáo.

- Nếu chu kỳ báo cáo là tháng (monthly) thì giá trị có định dạng: YYYY- MM. Ví dụ: 2025-09, 2025-10, ….

- Nếu chu kỳ báo cáo là quý (quarter) thì giá trị có định dạng: YYYY- Qn. Ví dụ: 2025-Q1, 2025-Q2, 2025-Q3, 2025-Q4.

- Nếu chu kỳ báo cáo là năm (yearly) thì giá trị có định dạng: YYYY. Ví dụ: 2025, 2026, …

6

status

string

Trạng thái xử lý của hệ thống. Chi tiết tại Mục 6.2. Bảng mã trạng thái xử lý của hệ thống.

7

submitted_at

datetime

Thời gian hệ thống tiếp nhận.

8

messages

array[string]

Danh sách các thông báo lỗi của hệ thống nếu có.

TT

Thuộc tính

Bắt buộc

Giá trị

Mô tả

1

Content-Type

x

application/json

2

Authorization

x

Bearer {access_token}

access_token nhận được từ các API xác thực

TT

Tên trường

Kiểu dữ liệu

Độ dài tối đa

Bắt buộc

Mô tả

1

invoice_date

datetime

x

Thời điểm lập hoá đơn

2

invoice_no

string

50

x

Số hoá đơn

3

store_id

string

50

Mã chi nhánh (trong trường hợp cơ sở kinh doanh dược có nhiều chi nhánh)

4

prescription_code

string

50

Mã đơn thuốc quốc gia

5

customer_name

string

200

Tên khách hàng

6

customer_phone

string

20

Số điện thoại khách hàng

7

note

string

500

Ghi chú

8

items

array

x

Danh sách thuốc kiểm kho

8.1

items[].drug_id

string

20

x

Mã định danh thuốc

8.2

items[].unit_id

string

20

x

Mã đơn vị tính

8.3

items[].quantity

integer

x

Số lượng

8.4

items[].batch_no

string

50

x

Số lô sản xuất

8.5

items[].expiry_date

date

x

Hạn sử dụng

8.6

items[].manufacturer

object

Thông tin nhà sản xuất

8.6.1

items[].manufacturer.id

string

20

Mã nhà sản xuất

8.6.2

items[].manufacturer.name

string

200

Tên nhà sản xuất

8.6.3

items[].manufacturer.country

string

5

Mã quốc gia sản xuất

8.7

items[].gtin

string

50

Mã GTIN tương ứng với cấp độ đóng gói

8.8

items[].price

float

Đơn giá (độ chính xác tới 2 chữ số thập phân).

8.9

items[].usage_instruction

string

500

Hướng dẫn sử dụng

TT

Tên trường

Kiểu dữ liệu

Mô tả

1

invoice_id

string

Mã ID của hoá đơn bán lẻ thuốc

2

status

string

Trạng thái xử lý của hệ thống. Chi tiết tại Mục 6.2

TT

Thuộc tính

Bắt buộc

Giá trị

Mô tả

1

Content-Type

x

application/json

2

Authorization

x

Bearer {access_token}

access_token nhận được từ các API xác thực

TT

Thuộc tính

Kiểu dữ liệu

Dữ liệu tối đa

Bắt buộc

Mô tả

1

invoice_id

string

50

x

Mã Id của hoá đơn bán lẻ thuốc

TT

Tên trường

Kiểu dữ liệu

Mô tả

1

invoice_id

datetime

Mã Id của hoá đơn bán lẻ thuốc

2

invoice_date

datetime

Thời điểm lập hoá đơn

3

invoice_no

string

Số hoá đơn

4

store_id

string

Mã chi nhánh (trong trường hợp cơ sở kinh doanh dược có nhiều chi nhánh)

5

prescription_code

string

Mã đơn thuốc quốc gia

6

customer_name

string

Tên khách hàng

7

customer_phone

string

Số điện thoại khách hàng

8

note

string

Ghi chú

9

items