Lấy dữ liệu chứng khoán Việt Nam vào chương trình của bạn

Dataset theo nhóm

• Danh mục→Mã được phân theo loại. Mỗi chỉ tiêu đều kèm tên tiếng Việt, đơn vị và loại chủ thể áp dụng.metrics2 dataset
• Chuỗi theo ngày→Lấy dữ liệu cho một chủ thể hoặc 1–50 mã cùng loại trong một lượt, mỗi chỉ tiêu tương ứng một cột.multi_series2 dataset
• Lát cắt một ngày→Mỗi cổ phiếu hoặc ETF là một dòng, mỗi chỉ tiêu là một cột, hỗ trợ sắp xếp và lấy N dòng đầu.cross_section1 dataset
• Doanh nghiệp→Báo cáo tài chính theo mẫu biểu, sự kiện và hồ sơ doanh nghiệp.financial_statements3 dataset
• Chỉ số tự tính→Các chỉ số tự tính: thị trường, ba nhóm vốn hoá, ba bậc ngành, ba nhóm dòng tiền, 24 ngành, cùng thành viên và tỷ trọng.computed_indices2 dataset

Dành cho ai

• Nhà đầu tư tự xây dựng bảng theo dõi bằng Python hoặc Excel.
• Nhà phân tích cần dữ liệu chuỗi dài, nhiều mã và đúng đơn vị.
• Người phát triển công cụ nội bộ cần một nguồn dữ liệu cuối ngày ổn định.

API chỉ trả về dữ liệu có sẵn trong kho: không cung cấp tin tức, không tính toán khi gọi và không gọi AI. Nếu muốn hỏi bằng tiếng Việt, hãy dùng MCP. Nếu không viết mã, hãy dùng trang «Tải dữ liệu» trong tài khoản.

1. 01

   Tạo khoásắp có

   Đăng nhập vào trang tài khoản, vào mục «Khoá API», đặt tên rồi bấm «Tạo khoá».

2. 02

   Sao chép ngay

   Khoá có dạng dlck_ kèm 52 ký tự và chỉ hiển thị một lần duy nhất lúc tạo.

3. 03

   Gửi trong header

   Đặt khoá vào Authorization: Bearer <khoá>. Không đưa khoá vào địa chỉ URL, kể cả khi gọi bằng GET.

• Mỗi tài khoản có tối đa 5 khoá còn hiệu lực.
• Nếu khoá bị lộ, hãy thu hồi ở trang «Khoá API»; thu hồi có hiệu lực ngay.

https://api.dulieuchungkhoan.vn/v1/

• Đường

  GET hoặc POST /v1/<dataset>

  Làm gì

  Để lấy dữ liệu của một dataset: dùng GET với tham số trên query, hoặc POST với tham số trong thân JSON. Cùng tham số sẽ cho cùng kết quả. Danh sách mười đường nằm ở mục «Dataset».

  Khoá, lượt

  Cần khoá; tính một lượt.

• Đường

  GET /v1/catalog

  Làm gì

  Danh mục dataset, tham số và chỉ tiêu: mỗi chỉ tiêu kèm giải nghĩa ngắn, nhịp và giờ cập nhật. Máy khách bỏ qua trường lạ.

  Khoá, lượt

  Không cần khoá.

• Đường

  GET /v1/usage

  Làm gì

  Phần trăm hạn mức đã dùng.

  Khoá, lượt

  Cần khoá; không tính lượt.

curl "https://api.dulieuchungkhoan.vn/v1/symbols?instrument_type=stock&format=csv" \
  -H "Authorization: Bearer <khoá của bạn>" -o ma.csv

curl -X POST "https://api.dulieuchungkhoan.vn/v1/series?format=csv" \
  -H "Authorization: Bearer <khoá của bạn>" -H "Content-Type: application/json" \
  -d '{"symbol": "FPT", "metrics": ["adjusted_close", "volume"], "start_date": "2026-10-01"}' -o fpt.csv

import requests

r = requests.get("https://api.dulieuchungkhoan.vn/v1/metrics", timeout=60,
                 headers={"Authorization": "Bearer <khoá của bạn>"},
                 params={"group": "price", "format": "csv"})
r.raise_for_status()
open("chi_tieu.csv", "wb").write(r.content)

Invoke-RestMethod -Method Post -Uri "https://api.dulieuchungkhoan.vn/v1/symbols?format=csv" `
  -Headers @{ Authorization = "Bearer <khoá của bạn>" } -ContentType "application/json" `
  -Body '{"instrument_type": "industry"}' -OutFile nganh.csv

Nhiều mã trong một lượt

multi_series lấy chuỗi theo ngày của 1–50 mã cùng loại theo dạng dài: mỗi dòng gồm một cặp ngày và mã, mỗi chỉ tiêu một cột. Danh sách mã viết cách nhau bằng dấu phẩy, hoặc lặp lại khoá trên query.

GET https://api.dulieuchungkhoan.vn/v1/multi-series?symbols=FPT,HPG,VNM&metrics=adjusted_close,volume&start_date=2026-01-01

Phong bì JSON

Mọi phản hồi JSON thành công đều gồm data (mảng object, mỗi dòng là một object) và meta (dataset, columns, truncated, notes, timezone). Ô thiếu dữ liệu nhận giá trị null. Mỗi phần tử của meta.columns có dạng {id, name_vi, unit, unit_vi, type}.

{
  "data": [
    {
      "date": "2026-10-01",
      "adjusted_close": 118300,
      "volume": 4512300
    },
    {
      "date": "2026-10-02",
      "adjusted_close": 119100,
      "volume": null
    }
  ],
  "meta": {
    "dataset": "series",
    "columns": [
      {
        "id": "date",
        "name_vi": "Ngày",
        "unit": null,
        "unit_vi": null,
        "type": "date"
      },
      {
        "id": "adjusted_close",
        "name_vi": "Giá đóng cửa điều chỉnh",
        "unit": "vnd_per_share",
        "unit_vi": "đồng/cp",
        "type": "number"
      },
      {
        "id": "volume",
        "name_vi": "Khối lượng",
        "unit": "shares",
        "unit_vi": "cổ phiếu",
        "type": "number"
      }
    ],
    "truncated": false,
    "notes": [],
    "timezone": "Asia/Ho_Chi_Minh"
  }
}

Excel «Từ Web» và Google Sheets IMPORTDATA không hỗ trợ đặt header khoá nên không gọi trực tiếp API được. Bạn có thể dùng một đoạn mã như trên, hoặc dùng trang «Tải dữ liệu»: chọn dữ liệu, xem trước miễn phí rồi bấm tải CSV.

• Nhóm

  Danh mục

  Dataset

  symbols

  Đường

  /v1/symbols

  Trả về

  Danh sách mã theo loại: cổ phiếu, ETF, chỉ số sàn, hợp đồng phái sinh nối, ngành.

• Nhóm

  Danh mục

  Dataset

  metrics

  Đường

  /v1/metrics

  Trả về

  Danh sách chỉ tiêu công khai: mã, tên tiếng Việt, đơn vị, nhóm, áp dụng cho loại chủ thể nào.

• Nhóm

  Chuỗi theo ngày

  Dataset

  series

  Đường

  /v1/series

  Trả về

  Chuỗi theo ngày của một chủ thể: mỗi chỉ tiêu một cột, ghép theo ngày.

• Nhóm

  Chuỗi theo ngày

  Dataset

  multi_series

  Đường

  /v1/multi-series

  Trả về

  Chuỗi theo ngày của 1–50 mã cùng loại trong một lượt, dạng dài.

• Nhóm

  Lát cắt một ngày

  Dataset

  cross_section

  Đường

  /v1/cross-section

  Trả về

  Lát cắt một ngày: mỗi cổ phiếu hoặc ETF một dòng, mỗi chỉ tiêu một cột; sắp và lấy N dòng đầu.

• Nhóm

  Doanh nghiệp

  Dataset

  financial_statements

  Đường

  /v1/financial-statements

  Trả về

  Báo cáo tài chính một cổ phiếu theo mẫu biểu của loại doanh nghiệp, mỗi kỳ một cột, tối đa 40 kỳ mỗi lượt.

• Nhóm

  Doanh nghiệp

  Dataset

  events

  Đường

  /v1/events

  Trả về

  Dòng thời gian sự kiện doanh nghiệp và thị trường: mỗi ngày của một sự kiện là một dòng.

• Nhóm

  Doanh nghiệp

  Dataset

  company_profile

  Đường

  /v1/company-profile

  Trả về

  Hồ sơ doanh nghiệp: thẻ công ty, cổ đông lớn, ban lãnh đạo, công ty con và liên kết, kế hoạch năm so thực hiện.

• Nhóm

  Chỉ số tự tính

  Dataset

  computed_indices

  Đường

  /v1/computed-indices

  Trả về

  Lát cắt một ngày cho các chỉ số tự tính: thị trường, ba nhóm vốn hoá, ba bậc ngành, ba nhóm dòng tiền, 24 ngành.

• Nhóm

  Chỉ số tự tính

  Dataset

  computed_index_members

  Đường

  /v1/computed-index-members

  Trả về

  Thành viên và tỷ trọng của một chỉ số tự tính ở kỳ phân nhóm hiện hành.

• Mã chỉ tiêu là mã công khai, ví dụ adjusted_close. Danh sách kèm tên tiếng Việt và đơn vị có tại GET /v1/metrics hoặc GET /v1/catalog (ở đó mỗi chỉ tiêu còn có giải nghĩa ngắn, nhịp và giờ cập nhật).
• Mỗi chỉ tiêu chỉ áp dụng cho đúng loại chủ thể tương ứng. Nếu gọi sai loại, API sẽ báo lỗi kèm danh sách mã hợp lệ.
• Mỗi lượt đều có trần dòng, ô, dung lượng và thời gian. Khi vượt trần dòng hoặc ô, kết quả sẽ bị cắt: meta.truncated là true (header X-Dlck-Truncated: 1) kèm câu chỉ cách thu hẹp trong meta.notes. Hệ thống không bao giờ cắt câm. Kết quả vượt quá 4 MiB sẽ trả lỗi 422 result_too_large, truy vấn quá 20 giây sẽ trả lỗi 504 query_timeout.

• Với JSON: meta.columns[].name_vi là tên tiếng Việt, unit_vi là đơn vị. Với CSV: hàng đầu là mã cột, ví dụ date,adjusted_close,volume. Tệp tải từ trang «Tải dữ liệu» có tiêu đề tiếng Việt kèm đơn vị.
• Số tổng (giá trị giao dịch, vốn hoá) tính bằng tỷ đồng, số trên mỗi cổ phần tính bằng đồng/cp, chỉ số tính bằng điểm, còn tỷ lệ tính bằng % (đã nhân 100).
• Dữ liệu không làm tròn, dấu thập phân là dấu chấm. Ngày có dạng YYYY-MM-DD theo ngày giao dịch Việt Nam.
• Ô trống được để trống trong CSV và là null trong JSON. Giá trị boolean là true hoặc false.
• Giá điều chỉnh và giá thô là hai mã khác nhau. Giá giao ngay và giá tương lai của tài sản không bao giờ chung một cột.
• JSON dùng số dấu phẩy động, nên các số có hơn 15 chữ số có nghĩa có thể bị mất chữ số cuối. Nếu cần chính xác tuyệt đối, bạn hãy dùng CSV.

• Mỗi lượt gọi dữ liệu (GET hay POST tới một đường dataset) sẽ trừ một lượt. Mọi khoá của bạn và trang «Tải dữ liệu» đều dùng chung một hạn mức. Thao tác xem trước trên trang tải không tính.
• Mỗi tài khoản đều có trần theo phút, và mỗi khoá chỉ chạy một lượt tại một thời điểm. Việc chia lượt qua nhiều khoá cũng không tránh được trần phút.
• Khi bị chặn (HTTP 429), hãy đọc header Retry-After (số giây) rồi mới gọi lại.
• Lượt bị trừ ngay khi yêu cầu qua bước kiểm khoá và hạn mức, trước khi đọc dữ liệu. Do đó, các kết quả lỗi 400, 404, 413, 422 (tham số sai), 500, 503 server_busy, 504 cũng tốn lượt. Các trường hợp không tốn lượt gồm: sai phương thức (405), khoá sai (401), gọi quá nhanh, khoá đang có lượt chạy, hết lượt, hệ thống xác thực bận hoặc API tạm ngưng, lang sai.

{
  "data": {
    "windows": [
      {
        "window": "day",
        "used_pct": 37,
        "resets_at": "2026-10-18T00:00:00+07:00",
        "seconds_remaining": null
      },
      {
        "window": "minute",
        "used_pct": 3,
        "resets_at": null,
        "seconds_remaining": 41
      }
    ]
  }
}

used_pct là số nguyên 0–100, resets_at là giờ đặt lại của cửa sổ ngày, còn seconds_remaining là số giây tới lúc trần phút đặt lại. Khoá không áp dụng sẽ là null.

{
  "type": "https://dulieuchungkhoan.vn/docs/api/errors#invalid_parameter",
  "title": "Invalid parameter",
  "status": 422,
  "detail": "Unknown metric: adjusted_clos.",
  "code": "invalid_parameter",
  "errors": [
    {
      "parameter": "metrics",
      "detail": "Unknown metric: adjusted_clos."
    }
  ],
  "valid_values": [
    "adjusted_close",
    "close",
    "volume"
  ]
}

• HTTP

  400

  code

  invalid_body

  Khi nào

  Thân POST không phải là một object JSON.

• HTTP

  401

  code

  invalid_api_key

  Khi nào

  Thiếu khoá, sai định dạng, đã bị thu hồi hoặc tài khoản bị khoá.

• HTTP

  404

  code

  not_found, no_data

  Khi nào

  Đường không có dưới /v1, hoặc yêu cầu CSV mà không có dòng nào khớp.

• HTTP

  405

  code

  method_not_allowed

  Khi nào

  Sai phương thức, ví dụ DELETE /v1/series hay HEAD.

• HTTP

  413

  code

  too_large

  Khi nào

  Thân yêu cầu quá 16 KiB.

• HTTP

  422

  code

  invalid_parameter, dataset_not_found, symbol_not_found, metric_not_applicable, unsupported_format, result_too_large

  Khi nào

  Đầu vào sai, kèm danh sách giá trị hợp lệ, hoặc kết quả vượt quá 4 MiB.

• HTTP

  429

  code

  rate_limited, request_in_progress, quota_exceeded

  Khi nào

  Gọi quá nhanh, khoá đang có một lượt chạy, hoặc hết lượt trong ngày (kèm resets_at).

• HTTP

  500

  code

  internal_error

  Khi nào

  Lỗi ngoài dự kiến, vui lòng thử lại sau.

• HTTP

  503

  code

  server_busy, service_paused

  Khi nào

  Kho hoặc hệ thống xác thực đang bận, hoặc API đang tạm ngưng.

• HTTP

  504

  code

  query_timeout

  Khi nào

  Truy vấn vượt quá 20 giây: hãy thu hẹp start_date, end_date hoặc giảm bớt chỉ tiêu.

• Mã lỗi→Bảng đầy đủ mọi mã lỗi, mỗi mã là một mục có neo. Trường `type` của mọi lỗi đều trỏ vào đó.

• Nhóm chỉ tiêu hoặc dataset

  money_flow, index, futures

  Thường xong lúc

  15:58

  Muộn nhất

  16:00

• Nhóm chỉ tiêu hoặc dataset

  price

  Thường xong lúc

  16:06

  Muộn nhất

  16:10

• Nhóm chỉ tiêu hoặc dataset

  ratio

  Thường xong lúc

  17:25

  Muộn nhất

  17:35

• Nhóm chỉ tiêu hoặc dataset

  market

  Thường xong lúc

  17:41

  Muộn nhất

  17:52

• Nhóm chỉ tiêu hoặc dataset

  technical

  Thường xong lúc

  17:49

  Muộn nhất

  18:02

• Nhóm chỉ tiêu hoặc dataset

  events

  Thường xong lúc

  18:13

  Muộn nhất

  18:14

• Nhóm chỉ tiêu hoặc dataset

  financial_statements

  Thường xong lúc

  18:17

  Muộn nhất

  18:42

• Nhóm chỉ tiêu hoặc dataset

  company_profile

  Thường xong lúc

  20:30, cả tuần

  Muộn nhất

  20:33

Số đo trên sáu phiên 08–15/10/2026; ngày nào nguồn chậm thì có thể muộn hơn. Trong giờ giao dịch, phiên mới nhất trong API là phiên hôm trước. Vĩ mô và tài sản được cập nhật theo nhịp của nguồn, cả tuần.

API có dữ liệu trong phiên không?

Không. API trả dữ liệu cuối ngày. Trong giờ giao dịch, phiên mới nhất là phiên hôm trước.

Hết lượt thì sao?

API trả 429 quota_exceeded kèm resets_at. Hạn mức được đặt lại lúc 00:00 giờ Việt Nam.

Kết quả lỗi có tốn lượt không?

Có, nếu yêu cầu đã qua bước kiểm khoá và hạn mức. Bạn nên kiểm tra tham số trước khi gọi, hoặc thử trên trang «Tải dữ liệu» với bản xem trước miễn phí.

Mã chỉ tiêu có bị thay đổi không?

Với /v1 thì không: việc thêm dataset, tham số, cột hay chỉ tiêu mới không làm đổi /v1, và mã đã công bố không bị gỡ. Việc đổi nghĩa hay gỡ chỉ xảy ra ở /v2.

Vì sao P/E kỳ quý 4 lại khác số tính theo năm?

Chỉ tiêu bốn quý gần nhất (eps_ttm, pe, ps…) luôn cộng bốn báo cáo quý, kể cả khi kỳ gần nhất là quý 4. Do đó, kết quả có thể khác số cả năm, nhất là các năm trước 2024.

Nếu mã cổ phiếu cũ bị công ty khác dùng lại thì sao?

API chỉ trả mã đang niêm yết. Lịch sử của công ty cũ cùng mã không tra được qua API.

Có mất phí không?

Không.