Quyết định 232/QĐ-TTYQG 2026 ban hành 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.1 và hướng dẫn sử dụng

BỘ Y TẾ
TRUNG TÂM THÔNG TIN
Y TẾ QUỐC GIA
^__________
Số: 232/QĐ-TTYQG

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

Hà Nội, ngày 17 tháng 7 năm 2026

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
^{______________________}

Ngày thay đổi

Vị trí thay đổi

A*, M, D

Nguồn gốc

Phiên bản cũ

Mô tả thay đổi

Phiên bản mới

01/01/2026

Toàn bộ

A*

Tạo mới

1.0

01/07/2026

5.1

D

1.0

Chỉnh sửa thông tin cấu hình Header API

1.1

01/07/2026

5.2.1, 5.5, 5.6

D

1.0

Xóa mục 5.2.1, 5.5, 5.6

1.1

01/07/2026

5.3

D

1.0

- Bỏ các thông tin liên quan đến nguyên liệu làm thuốc (ingredients) trong response body

- Bổ sung thêm trường thông tin lưu giá trị Số GPLH cũ (old_registration_number) và Địa chỉ nhà sản xuất (manufacturer.address) trong response body

1.1

01/07/2026

5.3.1

D

1.0

- Bỏ các thông tin liên quan đến nguyên liệu làm thuốc (ingredients) trong response body

- Bỏ các trường thông tin packagings[].conversion_rate_to_ba se; packagings[].is_basic_unit

- Bổ sung tiêu chí lọc theo khoảng thời gian cập nhật dữ liệu thuốc last_update_from, last_update_to

- Bổ sung thêm trường thông tin lưu giá trị Số GPLH cũ (old_registration_number) , Địa chỉ nhà sản xuất (manufacturer.address) và Ngày cập nhật mới nhất (last_update_time)

1.1

01/07/2026

5.4.1, 5.4.4, 5.4.7

D

1.0

- Bổ sung trường thông tin Quy cách đóng gói (items[]. packaging_specifications)

- Bổ sung trường thông tin Số giấy chứng nhận đủ điều kiện sản xuất/kinh doanh thuốc (practice_license_code)

1.1

01/07/2026

6.4.1, 6.4.2

D

1.0

Bổ sung thêm loại phiếu nhập khác và xuất khác

1.1

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ở xuất 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

Đơn vị tính

GET /master/units

3

Quốc gia

GET /master/countries

4

Nhóm thuốc

GET /master/drug-groups

5

Đường dùng

GET /master/routes

6

Nhà sản xuất

GET /master/manufacturers

7

Tỉnh/Thành phố

GET /master/provinces

8

Xã/Phường

GET /master/communes

9

Thuốc

Danh sách thuốc

GET /master/drugs

10

Thông tin chi tiết thuốc

GET /master/drugs/{drug_id}

11

Giao dịch nhập - xuất

Tạo phiếu nhập hàng

POST /transactions/stock-in

12

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

GET /transaction/stock- in/{transaction_id}

13

Xem trạng thái xử lý phiếu nhập hàng

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

14

Tạo phiếu xuất hàng

POST /transactions/stock-out

15

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

GET /transactions/stock- out/{transaction_id}

16

Xem trạng thái xử lý phiếu xuất hàng

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

17

Tạo phiếu kiểm kho

POST /transactions/stock-taking

18

Xem thông tin chi tiết phiếu kiểm kho

GET /transactions/stock- taking/{transaction_id}

19

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

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

TT

Thuộc tính

Bắt buộc

Giá trị

Mô tả

1

Content-Type

x

application/x-www- form-urlencoded

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/x-www- form-urlencoded

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)

3

last_update_from

date

Ngày cập nhật dữ liệu thuốc từ

4

last_update_to

date

Ngày cập nhật dữ liệu thuốc đến

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

old_registration_number

string

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

3.6

active_pharmaceutical_ingredient

string

Hoạt chất.

Ví dụ: Coptis Rhizoma Dried Extract (4.5 ~ 7 → 1) 8,75mg, Ivy Leaf 30% Ethanol dried extract (5~7.5 →1) 26,25mg

3.7

strength

string

Hàm lượng.

Ví dụ: (0,025%) 0,25mg/ml

3.8

routes

array

Danh sách đường dùng

3.8.1

id

string

Mã đường dùng

3.8.2

name

string

Tên đường dùng

3.9

prescription_status

integer

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

3.10

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.4.

3.11

packagings

array

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

3.11.1

packagings[].unit_id

string

Mã đơn vị tính

3.11.2

packagings[].unit_name

string

Tên đơn vị tính

3.11.3

packagings[].gtin

string

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

3.12

last_update_time

date

Ngày chỉnh sửa gần nhất

3.13

manufacturer

object

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

3.13.1

manufacturer.id

string

Mã nhà sản xuất

3.13.2

manufacturer.name

string

Tên nhà sản xuất

3.13.3

manufacturer.country

string

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

3.13.4

manufacturer.address

string

Địa chỉ nhà sản xuất

3.14

approval_date

date

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

3.15

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

drug_group_id

string

Mã nhóm thuốc

4

registration_number

string

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

5

old_registration_number

string

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

6

active_pharmaceutical_ingredient

string

Hoạt chất. Ví dụ:

Coptis Rhizoma Dried Extract (4.5 ~ 7 → 1) 8,75mg, Ivy Leaf 30% Ethanol dried extract (5~7.5 →1) 26,25mg

7

strength

string

Hàm lượng.

Ví dụ: (0,025%) 0,25mg/ml

8

routes

array

Danh sách đường dùng

8.1

id

string

Mã đường dùng

8.2

name

string

Tên đường dùng

9

prescription_status

integer

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

10

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.4

11

packagings

array

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

11.1

packagings[].unit_id

string

Mã đơn vị tính

11.2

packagings[].unit_name

string

Tên đơn vị tính

11.3

packagings[].gtin

string

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

12

manufacturer

object

Nhà sản xuất

12.1

manufacturer.id

string

Mã nhà sản xuất

12.2

manufacturer.name

string

Tên nhà sản xuất

12.3

manufacturer.country

string

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

12.4

manufacturer.address

string

Địa chỉ nhà sản xuất

13

approval_date

date

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

14

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 hàng.

2

reason

string

20

x

Lý do nhập/Loại phiếu nhập hàng. 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 hàng (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 hàng (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 hàng

9

practice_license_code

string

50

Số giấy chứng nhận đủ điều kiện sản xuất/kinh doanh thuốc của cơ sở chi nhánh (nếu cơ sở có chuỗi nhà thuốc). Nhập thông tin nếu muốn dùng tài khoản cơ sở chính đẩy dữ liệu cho các cơ sở thành viên

10

note

string

500

Ghi chú

11

items

array

x

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

11.1

items[].drug_id

string

20

x

Mã định danh thuốc

11.2

items[].unit_id

string

20

x

Mã đơn vị tính

11.3

items[].quantity

integer

x

Số lượng

11.4

items[].batch_no

string

50

x

Số lô sản xuất

11.5

items[].packaging_specifications

string

500

Quy cách đóng gói

11.6

items[].expiry_date

date

x

Hạn sử dụng

11.7

items[].manufacturer

object

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

11.7.1

items[].manufacturer.id

string

20

Mã nhà sản xuất

11.7.2

items[].manufacturer.name

string

200

Tên nhà sản xuất

11.7.3

items[].manufacturer.country

string

5

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

11.8

items[].gtin

string

50

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

11.9

items[].price

float

Đơn giá nhập thuốc (độ 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 hàng

TT

Tên trường

Kiểu dữ liệu

Mô tả

1

transaction_id

string

Mã ID của phiếu nhập hàng

2

transaction_date

datetime

Ngày/giờ nhập hàng

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 hàng (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 hàng (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 hàng.