# API Dữ Liệu Kinh Tế — tài liệu dành cho trợ lý AI

> **Đây là tài liệu tham chiếu đầy đủ.** Người dùng đã đưa file này cho bạn
> (một trợ lý AI) để bạn hướng dẫn họ gọi API. Hãy đọc hết mục 0 trước khi
> trả lời bất cứ câu nào.

| | |
|---|---|
| Gốc API | `https://api.dulieukinhte.com/v1` |
| Giao thức | REST, **chỉ `GET`**, trả JSON hoặc CSV |
| Trang quản lý API key | https://console.dulieukinhte.com |
| Tài liệu cho người đọc | https://console.dulieukinhte.com/huong-dan (hướng dẫn + tra cứu, một trang) |
| Đặc tả OpenAPI 3.1 | https://console.dulieukinhte.com/openapi.json |
| Website số liệu (miễn phí) | https://dulieukinhte.com |
| Hỗ trợ | hotro@dulieukinhte.com |
| Quy mô kho | 300 bộ số liệu · 32.787 chuỗi thời gian · ~7.918.541 điểm · 4 nền kinh tế · 1.563 doanh nghiệp niêm yết |
| Tài liệu sinh lúc | 2026-09-10T01:40:28.007Z |

---

## 0. Dành riêng cho bạn (trợ lý AI) — đọc trước

Người dùng muốn lấy số liệu kinh tế bằng chương trình. Việc của bạn là dẫn họ
đi, viết code cho họ, và gỡ lỗi khi code chạy sai.

### Bảy quy tắc, không có ngoại lệ

**1. Chỉ dùng sự thật trong file này.** Không có endpoint, tham số hay trường
nào ngoài những gì được liệt kê ở đây. Nếu người dùng hỏi một thứ tài liệu này
không nói, hãy trả lời thẳng là bạn không biết và chỉ họ tới
`https://console.dulieukinhte.com/huong-dan` hoặc hotro@dulieukinhte.com. **Đừng suy đoán cho có.**

**2. ĐỪNG BAO GIỜ TỰ NGHĨ RA MÃ `id`.**
Đây là lỗi nghiêm trọng nhất bạn có thể mắc với API này. `datasetId` và
`seriesId` là số tự tăng trong cơ sở dữ liệu — không theo quy luật nào, không
suy ra được từ tên chỉ tiêu. Một mã bịa ra trông rất hợp lý và sẽ trả 404.

Bạn có **đúng hai nguồn mã hợp lệ**, ngoài ra không còn nguồn nào:

- **Phụ lục mục 16** của tài liệu này — toàn bộ `datasetId` thật, đọc từ cơ sở
  dữ liệu đúng lúc người dùng tải file. Tra ở đó trước.
- **Kết quả `/search` hoặc `/datasets` mà người dùng chạy và đưa lại cho bạn** —
  đây là nguồn duy nhất cho `seriesId`, vì tài liệu này không liệt kê nổi
  32.787 chuỗi.

Quy trình đi từ tên chỉ tiêu tới `seriesId` nằm ở **mục 3** — hãy theo đúng nó.

Khi chưa có mã trong tay, đừng viết code có số cứng rồi bảo "chạy thử đi".
Hãy viết `SERIES_ID = <điền mã lấy được ở bước 3>` và nói rõ đó là chỗ trống.

**3. Đừng bao giờ hỏi xin API key của người dùng, và đừng nhận nếu họ tự đưa.**
Nếu họ lỡ dán key vào cuộc trò chuyện, hãy nói cho họ biết là key đó nên coi
như đã lộ và cần thu hồi tại `https://console.dulieukinhte.com/khoa`. Mọi code bạn viết phải đọc
API key từ **biến môi trường**, không bao giờ viết cứng.

**4. Hỏi trước khi viết code.** Ngôn ngữ nào (Python / JavaScript / R / Excel /
Google Sheets / dòng lệnh)? Lấy một lần hay chạy định kỳ? Đã có mã chỉ tiêu
chưa? Ba câu này quyết định toàn bộ đoạn code, hỏi rẻ hơn đoán rất nhiều.

**5. Mã lỗi là chuỗi, không phải số HTTP.** Mọi code xử lý lỗi bạn viết phải
rẽ nhánh theo `error.code`. Riêng hai mã cùng trả HTTP 429 lại cần hai cách xử
lý ngược nhau — xem mục 9. Bắt theo số 429 là sai.

**6. Mặc định là tiết kiệm hạn mức.** Hạn mức tính theo tháng và hết thì phải
chờ sang kỳ. Đừng bao giờ đề xuất vòng lặp quét toàn bộ danh mục. Xem mục 12.

**7. Trả lời bằng ngôn ngữ người dùng đang dùng.** Tài liệu này viết bằng tiếng
Việt nhưng người dùng có thể hỏi bằng tiếng Anh.

### Việc nên làm ngay ở lượt trả lời đầu tiên

1. Hỏi họ đã có API key chưa. Chưa có thì chỉ tới https://console.dulieukinhte.com/dang-ky
   (gói Free miễn phí, 100 lượt/tháng, không cần thẻ).
2. Hỏi họ muốn lấy chỉ tiêu gì, và họ đang dùng công cụ gì.
3. Bảo họ chạy lệnh kiểm tra ở mục 2 để xác nhận API key và biết gói của họ.

---

## 1. Mô hình dữ liệu — bốn tầng

```
nền kinh tế  →  bộ số liệu   →  chuỗi        →  quan sát
(economy)       (dataset)       (series)        (observation)
VN US EU CN     300 bộ          32.787 chuỗi    ngày + giá trị
?economy=VN     /datasets/152   /series/8241    2026-06 → 3,57
```

| Tầng | Là gì | Ghi chú quan trọng |
|---|---|---|
| `economy` | Nền kinh tế. Đúng 4 mã: `VN` `US` `EU` `CN` | Chỉ dùng để lọc. Không có số liệu ở tầng này. |
| `dataset` | Bộ số liệu ≈ một bảng trên website, ví dụ "Chỉ số giá tiêu dùng" | **Không chứa giá trị.** Chỉ có metadata và danh sách chuỗi con. |
| `series` | Một dòng trong bảng đó, ví dụ "Nhóm Lương thực" | **Đây là thứ bạn cần `id` của nó** để lấy số. Xếp thành cây cha–con qua `parentId`. |
| `observation` | Một điểm: `date` + `period` + `value` | Hàng hoá cuối cùng. |

**Hệ quả hay bị hiểu nhầm:** `GET /datasets/152` **không** trả về số liệu nào.
Nó trả về danh sách chuỗi con. Số liệu chỉ có ở `GET /series/{id}/observations`.

---

## 2. Xác thực

API key có dạng `dlkt_live_` + 43 ký tự base64url (tổng 53 ký tự). Lấy tại
`https://console.dulieukinhte.com/khoa`. Key chỉ hiện **một lần**; hệ thống lưu bản băm SHA-256, không
có cách xem lại.

Ba cách gửi API key:

```http
Authorization: Bearer dlkt_live_xxx      # nên dùng
X-API-Key: dlkt_live_xxx                 # tương đương
?api_key=dlkt_live_xxx                   # xem cảnh báo bên dưới
```

**`?api_key=` chỉ dùng được ở ba endpoint** — `/series/{id}/observations`,
`/series/observations`, `/companies/{symbol}/financials`,
`/companies/{symbol}/prices` — và **chỉ nên dùng khi công cụ không gửi được
header** (Excel, Google Sheets). API key trong URL nằm lại trong lịch sử trình
duyệt, header `Referer` và log máy chủ trung gian. Nếu bạn đề xuất cách này,
phải nói kèm cảnh báo đó và khuyên dùng một API key riêng cho bảng tính.

Lệnh kiểm tra đầu tiên nên bảo người dùng chạy:

```bash
# 1. API còn sống không (không cần API key, không tính hạn mức)
curl -s "https://api.dulieukinhte.com/v1/health"

# 2. API key đúng không, gói gì, còn bao nhiêu hạn mức (TÍNH 1 lượt hạn mức)
curl -s -H "Authorization: Bearer $DLKT_API_KEY" "https://api.dulieukinhte.com/v1/me"
```

Thu hồi key có hiệu lực trong vòng **60 giây** (thời gian sống của bộ đệm key).

Key có thể ràng buộc **danh sách IP**; khi đó gọi từ IP khác trả `ip_not_allowed`.

---

## 3. Lấy số liệu vĩ mô — quy trình đầy đủ

**Đây là việc người dùng cần làm nhiều nhất.** Số liệu vĩ mô nằm ở nhánh
`macro` — mọi gói đều có quyền này, kể cả Free.

Bạn **không thể** đi thẳng từ tên chỉ tiêu tới số liệu. Luôn phải qua bốn bước:

```
1. chọn nền kinh tế      VN | US | EU | CN
2. tìm BỘ số liệu        -> datasetId     (/search hoặc /datasets?q= hoặc phụ lục mục 16)
3. mở bộ, chọn CHUỖI     -> seriesId      (/datasets/{datasetId})
4. lấy số                                 (/series/{seriesId}/observations)
```

Bước 2 và 3 **chỉ phải làm một lần**. Khi đã có `seriesId`, hãy bảo người dùng
lưu lại vào cấu hình và từ đó về sau chỉ gọi bước 4.

### 3.1 Ví dụ chạy được đầy đủ — CPI Việt Nam

Mã trong ví dụ này là **mã thật lúc sinh tài liệu**. Vẫn hãy để người dùng chạy
bước 1–3 để xác nhận: bộ số liệu thỉnh thoảng được gộp và mã có thể đổi.

**Bước 1–2. Tìm bộ số liệu.**

```bash
curl -s -H "Authorization: Bearer $DLKT_API_KEY" \
  --data-urlencode "q=chỉ số giá tiêu dùng" \
  --data-urlencode "type=dataset" \
  --data-urlencode "economy=VN" \
  -G "https://api.dulieukinhte.com/v1/search"
```

```json
{ "data": [
  { "type": "dataset", "id": 321, "name": "CPI lũy kế từ đầu năm",        "frequency": "monthly" },
  { "type": "dataset", "id": 320, "name": "CPI bình quân từ đầu năm",     "frequency": "monthly" },
  { "type": "dataset", "id": 272, "name": "Chỉ số giá tiêu dùng (CPI)",   "frequency": "monthly" },
  { "type": "dataset", "id": 318, "name": "CPI so với tháng trước (MoM)", "frequency": "monthly" },
  { "type": "dataset", "id": 319, "name": "CPI so cùng kỳ năm trước (YoY)","frequency": "monthly" }
] }
```

**Năm kết quả, không phải một — và bộ bạn muốn KHÔNG đứng đầu.** Đây là tình
huống điển hình, không phải ngoại lệ: `/search` sắp theo **độ dài tên**, không
theo mức độ phù hợp. Đừng lấy bừa phần tử `[0]`.

Cách chọn giữa chúng:

| Người dùng muốn | Bộ | Cách lấy |
|---|---|---|
| Mức lạm phát so cùng kỳ (`%`) | `272` chỉ số gốc | thêm `transform=yoy` |
| | hoặc `319` đã tính sẵn | **không** thêm `transform` |
| Chỉ số giá (điểm) | `272` | `transform=none` |
| So tháng trước | `318` | **không** thêm `transform` |

Hai đường cho ra cùng một con số. Ưu tiên `272` + `transform=yoy` khi người dùng
còn muốn cả chỉ số gốc; dùng `319` khi họ chỉ cần đúng một đường. **Đừng bao giờ
áp `transform=yoy` lên `319`** — xem mục 3.4.

> `id` ở đây là **datasetId**, chưa phải thứ lấy được số liệu.

**Bước 3. Mở bộ ra, chọn đúng dòng.**

```bash
curl -s -H "Authorization: Bearer $DLKT_API_KEY" "https://api.dulieukinhte.com/v1/datasets/272"
```

```json
{ "data": {
  "id": 272, "name": "Chỉ số giá tiêu dùng (CPI)", "frequency": "monthly",
  "unit": "Điểm", "source": "Cục Thống kê (NSO)", "seriesCount": 17,
  "series": [
    { "id": 18692, "name": "Chỉ số giá tiêu dùng CPI",
      "level": 1, "parentId": null },
    { "id": 18693, "name": "Chỉ số giá tiêu dùng hàng ăn và dịch vụ ăn uống",
      "level": 2, "parentId": 18692 },
    { "id": 18694, "name": "Chỉ số giá tiêu dùng lương thực",
      "level": 3, "parentId": 18693 },
    { "id": 18695, "name": "Chỉ số giá tiêu dùng thực phẩm",
      "level": 3, "parentId": 18693 }
  ]
} }
```

**Bước 4. Lấy số.**

```bash
curl -s -H "Authorization: Bearer $DLKT_API_KEY" \
  "https://api.dulieukinhte.com/v1/series/18692/observations?from=2015-01-01&transform=yoy"
```

`18692` là dòng **gốc** — chỉ số CPI chung, tức con số người dùng muốn khi họ
nói "lạm phát". Chuỗi này có `unit: "Điểm"` (chỉ số), nên `transform=yoy` cho ra
đúng mức tăng so cùng kỳ tính bằng `%` — xem mục 3.4.

### 3.2 Cây cha–con — chỗ chọn nhầm dòng

Gần như mọi bảng vĩ mô là **cây nhiều cấp**, không phải danh sách phẳng. Mỗi
chuỗi có `level` (1 = gốc) và `parentId` (`null` = gốc).

| Người dùng muốn | Chọn dòng |
|---|---|
| "CPI Việt Nam" (con số trên báo) | dòng **gốc**: `parentId == null`, thường `level: 1` |
| "CPI nhóm lương thực" | dòng lá tương ứng |
| Toàn bộ bảng | mọi `id` trong `series[]`, gộp 20 mã mỗi lượt qua `/series/observations` |

```python
ds = get("/datasets/272")["data"]

# dòng tổng — thứ người dùng gần như luôn muốn khi họ nói tên chỉ tiêu
goc = [r for r in ds["series"] if r["parentId"] is None]

# chỉ các dòng lá (không ai làm cha) — dùng khi cần chi tiết, tránh cộng đôi
cha = {r["parentId"] for r in ds["series"] if r["parentId"]}
la  = [r for r in ds["series"] if r["id"] not in cha]
```

> **Đừng cộng tất cả các dòng lại.** Bảng vĩ mô có cả dòng tổng lẫn dòng thành
> phần; cộng hết là đếm đôi. `path` trong `/series/{id}` cho biết chuỗi nằm ở
> đâu trong cây, dùng nó để xác nhận đã chọn đúng.

Bộ nào có `seriesCount` lớn (hàng nghìn dòng — thường là các bảng xuất nhập
khẩu theo mặt hàng × quốc gia) thì đừng gọi `/datasets/{id}`; dùng
`/datasets/{id}/series?page=&perPage=500` để phân trang.

### 3.3 Cùng một chỉ tiêu, nhiều bộ theo tần suất

**Một chỉ tiêu vĩ mô thường có NHIỀU bộ số liệu, mỗi tần suất một bộ riêng.**
Ví dụ có thật ở nhánh VN: GDP theo giá hiện hành có bộ *theo quý* và bộ *theo
năm* là **hai `datasetId` khác nhau**, không phải một bộ lọc theo tần suất.

Vì vậy khi người dùng nói "GDP", hãy hỏi lại **theo quý hay theo năm**, rồi tìm
đúng bộ. Trường `frequency` trong kết quả `/search` cho biết ngay bộ nào là bộ nào.

Không có tham số nào đổi tần suất của một chuỗi. Muốn tần suất khác thì phải
dùng chuỗi khác.

### 3.4 `valueType` — cái bẫy "phần trăm của phần trăm"

Phần lớn bộ số liệu là giá trị tuyệt đối hoặc chỉ số, nhưng **17 bộ vốn đã là
tỷ lệ phần trăm** (CPI so cùng kỳ, IIP so cùng kỳ, tăng trưởng tín dụng…). Áp
`transform=yoy` lên những bộ đó cho ra "phần trăm của phần trăm" — vô nghĩa, và
**API vẫn tính rồi trả về bình thường, không báo lỗi nào.**

Trường phân biệt là **`valueType`**, có trong `/datasets` và `/datasets/{id}`:

| `valueType` | Nghĩa | Dùng `transform`? |
|---|---|---|
| `Value` | Giá trị tuyệt đối hoặc chỉ số | **Được** — đây là mục đích của `transform` |
| `YoY` `MoM` `QoQ` `YTD` `%` | Đã là tỷ lệ tính sẵn | **Không.** Để `transform=none` |

> ### `unit` KHÔNG dùng để phán đoán được
> Ví dụ có thật: bộ `272` (chỉ số CPI) và bộ `319` (CPI so cùng kỳ, đã là `%`)
> **cùng có `unit: "Điểm"`**. Chỉ `valueType` phân biệt được hai loại
> (`Value` với `YoY`). Đừng đoán qua `unit`, và cũng đừng đoán qua tên.

`/series/{id}` **không** trả `valueType` — trường này nằm ở tầng bộ số liệu. Muốn
biết thì đọc `/datasets/{datasetId}`, hoặc tra phụ lục mục 16 (các bộ đã là tỷ lệ
được đánh dấu sẵn ở đó).

### 3.5 Người dùng nói gì → tìm bằng từ khoá nào

`/search` khớp **chuỗi ký tự**, không hiểu ngữ nghĩa. Người dùng hỏi "lạm phát
bao nhiêu" mà bạn tìm `q=lạm phát` thì thường không ra gì. Hãy dịch sang tên
chỉ tiêu như trên website:

| Người dùng hỏi | `q=` nên dùng | Nền |
|---|---|---|
| lạm phát, giá cả | `CPI` · `Chỉ số giá tiêu dùng` | VN, US, CN |
| lạm phát châu Âu | `HICP` | EU |
| tăng trưởng kinh tế | `GDP` | cả bốn |
| tỷ giá USD/VND | `Tỷ giá USDVND` · `Tỷ giá` · `Tỷ giá chợ đen` | VN |
| lãi suất | `Lãi suất điều hành` · `Lãi suất huy động` · `Lãi suất cho vay` | VN |
| lãi suất Fed | `Lãi suất Fed` | US |
| xuất nhập khẩu | `Tổng xuất khẩu` · `Tổng nhập khẩu` · `Xuất khẩu theo mặt hàng` | VN |
| FDI, vốn ngoại | `Đầu tư trực tiếp từ nước ngoài` | VN |
| tín dụng, cung tiền | `Tăng trưởng tín dụng` · `Cung tiền M2 & Huy động` | VN |
| sản xuất công nghiệp | `IIP` · `Sản xuất công nghiệp` | cả bốn |
| PMI | `PMI` | cả bốn |
| bán lẻ, tiêu dùng | `Bán lẻ hàng hóa và dịch vụ` · `Bán lẻ` | VN, US, EU |
| thất nghiệp, lao động | `Lao động việc làm` · `Thất nghiệp` · `Tỷ lệ thất nghiệp` | VN, US, EU, CN |
| ngân sách nhà nước | `Thu ngân sách` · `Chi ngân sách` | VN |
| nợ công | `Vay nợ chính phủ` · `Nợ công` | VN, US |
| bất động sản | `Tổng quan thị trường bất động sản` · `Giá nhà` | VN, US, EU, CN |
| chứng khoán | `Thị trường chứng khoán` | VN |
| giá vàng, xăng dầu | `Giá vàng` · `Giá xăng dầu` | VN |
| nông sản, thực phẩm | `Giá nông sản` · `Giá heo hơi` · `Giá gạo xuất khẩu` | VN |
| cán cân thanh toán | `Cán cân thanh toán` | cả bốn |
| trái phiếu | `Lợi suất Trái phiếu Chính phủ` · `Thị trường Trái phiếu` | VN |
| du lịch, khách quốc tế | `Khách quốc tế theo quốc gia` · `Du lịch` | VN, EU |

Hai đường tìm khác khi `/search` không ra:

- **`GET /datasets?economy=VN&q=<từ khoá>`** — tìm rộng hơn `/search` vì quét cả
  mô tả và **tên nhóm chuyên đề**, không chỉ tên bộ.
- **Phụ lục mục 16** của tài liệu này liệt kê **toàn bộ 299 bộ số liệu kèm mã**.
  Khi bí, hãy dò trong đó thay vì đoán.

---

## 4. Toàn bộ endpoint

Tất cả đều là `GET`, tất cả đều tiền tố `https://api.dulieukinhte.com/v1`.
Cột "Quyền" là nhóm quyền (scope) mà gói phải có — xem mục 10.

Mỗi dòng dưới đây có **một URL ví dụ dùng giá trị thật** (`272` = bộ "Chỉ số giá
tiêu dùng (CPI)", `18692` = dòng CPI chung của bộ đó, `FPT` = mã cổ phiếu), để bạn
thấy ngay hình dạng lệnh gọi thay vì phải tự ghép từ danh sách tham số.

| Ví dụ | Quyền | Trả về gì |
|---|---|---|
| `GET /health` | *công khai* | `{ ok, version, database, time }`. Không cần API key, không tính hạn mức. |
| `GET /me` | — | Gói, hạn mức tháng, lượt/phút, giới hạn lịch sử, đã dùng bao nhiêu. Tính 1 lượt. |
| `GET /search?q=chỉ số giá tiêu dùng&type=dataset` | `macro` | Các bộ/chuỗi khớp tên, kèm `id` để dùng tiếp. **Lệnh gọi đầu tiên của bạn.** |
| `GET /economies` | `macro` | 4 nền kinh tế (VN, US, EU, CN) kèm số bộ số liệu mỗi nền. |
| `GET /datasets?economy=VN&perPage=50` | `macro` | Danh mục bộ số liệu kèm tần suất, đơn vị, nguồn. **Không kèm giá trị.** |
| `GET /datasets/272` | `macro` | Một bộ + **toàn bộ** cây chuỗi con. Chỗ lấy được `seriesId`. |
| `GET /datasets/272/series?perPage=100` | `macro` | Cùng danh sách đó nhưng có phân trang. |
| `GET /series/18692` | `macro` | Hồ sơ một chuỗi + `firstDate` / `lastDate` / `count` theo gói. |
| `GET /series/18692/observations?from=2015-01-01&transform=yoy` | `macro` | **Số liệu.** Mảng `{ date, period, value }`. |
| `GET /series/observations?ids=18692,18693,18694` | `macro` | Tối đa 20 chuỗi, vẫn chỉ **1 lượt** hạn mức. |
| `GET /series/18692/observations?format=csv` | `csv` | Cùng dữ liệu ở dạng CSV có BOM UTF-8. |
| `GET /updates?since=2026-08-28T00:00:00Z` | `updates` | Chuỗi nào vừa có số mới. Xương sống của đồng bộ tăng dần. |
| `GET /companies?exchange=HOSE` | `company` | Danh mục mã niêm yết HOSE / HNX / UPCOM. |
| `GET /companies/FPT` | `company` | Sàn, ngành, có sẵn báo cáo nào, dải giá đến đâu. |
| `GET /companies/FPT/financials?statementType=2&freq=quarter` | `company` | Ba mảng `lines` / `periods` / `values`. |
| `GET /companies/FPT/prices?from=2024-01-01` | `company` | `bars[]` với `date, open, high, low, close, volume`. |

Tiếng Việt trong `q=` phải được URL-encode; xem ví dụ `curl` ở mục 4.1.

### 4.1 `GET /search` — luôn bắt đầu từ đây

| Tham số | Kiểu | Mặc định | Ghi chú |
|---|---|---|---|
| `q` | chuỗi | **bắt buộc** | Tối thiểu 2 ký tự. Khớp chuỗi ký tự, **không** phải tìm ngữ nghĩa. |
| `type` | enum | `all` | `all` \| `dataset` \| `series` \| `company` |
| `economy` | enum | — | `VN` \| `US` \| `EU` \| `CN` |
| `limit` | số | 20 | Trần 100. |

`type=company` cần quyền `company` (gói Pro trở lên).

Phản hồi: `{"data":[…]}`, mỗi mục có `type`, `id`, `name`, `economy`,
`frequency`, `webUrl`; mục `series` có thêm `datasetId`, `dataset`; mục
`company` có `exchange` và `id` là mã cổ phiếu.

```bash
# Tiếng Việt có dấu: PHẢI dùng -G + --data-urlencode, đừng gõ thẳng vào URL
curl -s -H "Authorization: Bearer $DLKT_API_KEY" \
  --data-urlencode "q=chỉ số giá tiêu dùng" \
  --data-urlencode "type=series" \
  -G "https://api.dulieukinhte.com/v1/search"
```

> **Vì đây là tìm khớp chuỗi ký tự**, hãy khuyên người dùng nhập đúng cụm từ
> tiếng Việt như trên website ("chỉ số giá tiêu dùng" chứ không phải "lạm phát").
> Nếu không ra kết quả, gợi ý họ tìm bằng mắt trên https://dulieukinhte.com rồi lấy `id`
> từ URL: `/du-lieu/<slug>-<id>` (bộ số liệu) hoặc mở bảng và bấm vào dòng.

### 4.2 `GET /series/{id}/observations` — endpoint chính

| Tham số | Kiểu | Mặc định | Ghi chú |
|---|---|---|---|
| `from` | `YYYY-MM-DD` | — | Hiểu theo **giờ Việt Nam (UTC+7)**. |
| `to` | `YYYY-MM-DD` | — | Bao gồm cả mốc này. |
| `limit` | số | 1000 | Trần theo gói: 1.000 (Free) · 10.000 (Pro) · 50.000 (Business) · 200.000 (Enterprise). |
| `cursor` | chuỗi | — | Nguyên văn `meta.nextCursor` của lượt trước. Chuỗi mờ, **đừng giải mã hay tự chế**. |
| `order` | enum | `asc` | `asc` cũ→mới, `desc` mới→cũ. |
| `transform` | enum | `none` | Xem mục 6. |
| `format` | enum | `json` | `json` \| `csv`. CSV cần quyền `csv`. |

Phản hồi JSON:

```json
{
  "data": {
    "series": {
      "id": 8241,
      "name": "Lương thực",
      "path": ["Chỉ số giá tiêu dùng", "CPI chung", "Hàng ăn…", "Lương thực"],
      "datasetId": 152,
      "dataset": "Chỉ số giá tiêu dùng",
      "group": "Giá cả",
      "economy": "VN",
      "frequency": "monthly",
      "unit": "%",
      "source": "Cục Thống kê (NSO)",
      "sourceUrl": "https://…",
      "webUrl": "https://…",
      "lastUpdated": "2026-07-06T02:11:00.000Z",
      "transform": "none"
    },
    "observations": [
      { "date": "2026-06-01", "period": "2026-06", "value": 3.57 }
    ]
  },
  "meta": { "count": 1000, "hasMore": true, "nextCursor": "MTc0…", "limit": 1000 }
}
```

- `series.unit` là **đơn vị SAU khi biến đổi** (dùng `transform=yoy` thì thành `"%"`).
- `frequency` nhận một trong: `daily` `monthly` `quarterly` `annual`.
- **Không có `meta.total`** — cố ý. Dừng vòng lặp bằng `meta.hasMore`.

### 4.3 `GET /series/observations` — nhiều chuỗi, 1 lượt hạn mức

| Tham số | Kiểu | Mặc định | Ghi chú |
|---|---|---|---|
| `ids` | `1,2,3` | **bắt buộc** | **Tối đa 20 mã.** Quá 20 trả `bad_request`. |
| `from` `to` | `YYYY-MM-DD` | — | |
| `limit` | số | 500 | Trần mỗi chuỗi = `maxPointsPerRequest ÷ số chuỗi` (tối thiểu 50). |
| `transform` | enum | `none` | |
| `format` | enum | `json` | CSV ở đây là **dạng dài**: `series_id,series_name,unit,date,period,value`. |

Không nhận `cursor` và không nhận `order`. Cần đi trang thì thu hẹp `from`/`to`.

Phản hồi: `data` là **mảng chuỗi**, mỗi phần tử có metadata + `observations`.
Hai trường phải xử lý:

```json
{
  "data": [
    { "id": 8241, "name": "…", "unit": "%", "count": 120, "hasMore": false,
      "observations": [ … ] },
    { "id": 9001, "name": "…", "skipped": true,
      "reason": "Chuỗi có tần suất \"Day\" không hỗ trợ transform=\"yoy\"…" }
  ],
  "meta": { "requested": 3, "returned": 2, "missing": [7777], "limit": 500 }
}
```

- `meta.missing` — mã không tồn tại. **Không** làm hỏng cả lượt gọi.
- `skipped: true` — phép biến đổi không áp được cho tần suất của riêng chuỗi đó.
  19 chuỗi còn lại vẫn về bình thường. Code của bạn **phải** bỏ qua phần tử này
  trước khi đọc `observations`, nếu không sẽ lỗi "undefined".

> **Đây là kỹ thuật tiết kiệm hạn mức mạnh nhất:** gộp 20 chuỗi vẫn chỉ tính
> **1 lượt**. Khi người dùng cần nhiều hơn một chuỗi, hãy mặc định dùng endpoint
> này thay vì gọi lặp `/series/{id}/observations`.

### 4.4 `GET /series/{id}` — xác nhận trước khi kéo

Không có tham số. Trả metadata như `series` ở mục 4.2, cộng thêm:

| Trường | Nghĩa |
|---|---|
| `firstDate` `lastDate` | Điểm đầu/cuối **bạn thật sự lấy được**, đã trừ giới hạn lịch sử của gói. |
| `count` | Số điểm trong phạm vi đó. |
| `historyLimited` | `true` = kho còn dữ liệu cũ hơn nhưng gói không với tới. |
| `historyYears` | Số năm gói cho phép (chỉ có khi `historyLimited: true`). |

> Khi người dùng thắc mắc "sao chỉ có dữ liệu từ 2021 mà website có từ 1995",
> đây là endpoint để chẩn đoán. Xem `historyLimited`.

### 4.5 `GET /datasets` và `/datasets/{id}`

`GET /datasets` — tham số `economy`, `q`, `page` (1), `perPage` (50, trần 200).
Trả mảng bộ số liệu; **không kèm giá trị**. Mỗi bộ có `id`, `name`, `title`,
`group`, `economy`, `detail`, `description`, `frequency`, `valueType`, `unit`,
`source`, `sourceUrl`, `webUrl`, `lastUpdated`. `meta` có `page`, `perPage`,
`total`, `totalPages`, `hasMore`.

`GET /datasets/{id}` — trả bộ đó cộng `seriesCount` và `series[]` (**toàn bộ
cây**, không phân trang, trần 20.000 dòng). Mỗi chuỗi con có `id`, `name`,
`rawName`, `level`, `parentId`, `unit`, `webUrl`. Dựng lại cây bằng `parentId`
(`null` = gốc).

`breaks[]` — **đứt gãy của chuỗi**, có thì phải đọc. Cơ quan thống kê đổi chuẩn
theo chu kỳ (đổi năm gốc giá so sánh, đổi đơn vị, đổi cách tính); phần lịch sử
trước mốc đó đã được quy đổi về chuẩn mới bằng hệ số, nên là **số phái sinh**,
không phải số công bố nguyên trạng. Mỗi mục có `seriesId` (`null` = cả bộ),
`breakAt` (kỳ ĐẦU TIÊN theo chuẩn mới), `kind` (`rebase`…), `factor` (hệ số đã
nhân cho các kỳ TRƯỚC `breakAt`), `from`, `to`, `note`, `appliedAt`. Chia lại
`factor` là về đúng số gốc. Ví dụ: bộ 269 (GDP theo giá so sánh, theo quý) đổi
gốc 2010 → 2020 từ quý I/2026.

`GET /datasets/{id}/series` — cùng dữ liệu nhưng **có phân trang**
(`page`, `perPage` mặc định 100, trần 500) và thêm `frequency`. Dùng cái này
khi `seriesCount` lớn.

### 4.6 `GET /updates` — đồng bộ tăng dần

| Tham số | Kiểu | Mặc định | Ghi chú |
|---|---|---|---|
| `since` | ISO 8601 | **bắt buộc** | **Lùi tối đa 90 ngày.** Xa hơn trả `bad_request`. |
| `page` `perPage` | số | 1 / 100 | Trần `perPage` 500. |

Mỗi mục: `seriesId`, `name`, `datasetId`, `dataset`, `economy`, `frequency`,
`changedAt`, `pointsChanged`, `latestPeriod`. `meta` có phân trang + `since`.

Cần quyền `updates` (gói Pro trở lên). Ở gói Free, cách thay thế là lưu
`lastUpdated` của từng bộ trong `/datasets` rồi so sánh mỗi ngày.

### 4.7 Doanh nghiệp (cần quyền `company`)

`GET /companies` — `exchange` (`HOSE` \| `HNX` \| `UPCOM`), `q`, `page`,
`perPage` (50, trần 200). Mục: `symbol`, `name`, `exchange`, `industry`,
`updatedAt`, `webUrl`.

`GET /companies/{symbol}` — thêm `financials.statementTypes`,
`financials.lastYear`, và `prices` (`firstDate`, `lastDate`, `count`) hoặc `null`.

`GET /companies/{symbol}/financials`:

| Tham số | Mặc định | Giá trị |
|---|---|---|
| `statementType` | `2` | `1` cân đối kế toán · `2` kết quả kinh doanh · `3` lưu chuyển tiền tệ · `4` chỉ số · `5` báo cáo tháng (chỉ vài mã) |
| `freq` | `year` | `year` \| `quarter` |
| `limit` | 12 | Số **kỳ**, trần 60 |
| `format` | `json` | `json` \| `csv` |

Phản hồi tách **ba mảng** — nối bằng `lineId` × `period`:

```json
{ "data": {
  "symbol": "FPT", "statementType": 2, "frequency": "quarterly",
  "periods": ["2026-Q2", "2026-Q1", "…"],
  "lines":   [ { "id": 91, "name": "Doanh thu thuần", "level": 1,
                 "parentId": null, "field": "…", "unit": "Tỷ đồng" } ],
  "values":  [ { "lineId": 91, "period": "2026-Q2", "value": 15234.5 } ]
} }
```

`period` là `"2026"` khi `freq=year`, `"2026-Q2"` khi `freq=quarter`.
Mã không có báo cáo loại đó trả `not_found`.

`GET /companies/{symbol}/prices` — `from`, `to` (`YYYY-MM-DD`), `limit`
(trần theo gói), `order`, `format`. Trả `data.symbol` và `data.bars[]` với
`date`, `open`, `high`, `low`, `close`, `volume`.

> **Bẫy:** endpoint này trả `meta.nextCursor` nhưng **không nhận tham số
> `cursor`**. Đi trang bằng cách đặt `from` = ngày cuối trang trước + 1 ngày.

---

## 5. Hình dạng phản hồi và phân trang

Thành công: `{"data": …}` hoặc `{"data": …, "meta": …}`. Lỗi: `{"error": {…}}`.
Không có trường `success`, không có `status` trong thân phản hồi.

**Hai kiểu phân trang, dùng nhầm là lỗi phổ biến nhất:**

| Kiểu | Dùng ở | Tham số | `meta` |
|---|---|---|---|
| Trang | `/datasets`, `/datasets/{id}/series`, `/companies`, `/updates` | `page`, `perPage` | `page`, `perPage`, `total`, `totalPages`, `hasMore` |
| Con trỏ | `/series/{id}/observations` | `cursor` | `count`, `hasMore`, `nextCursor`, `limit` — **không có `total`** |

Vòng lặp con trỏ đúng:

```python
rows, cursor = [], None
while True:
    params = {"limit": 10000, **({"cursor": cursor} if cursor else {})}
    j = get(f"/series/{sid}/observations", **params)
    rows += j["data"]["observations"]
    if not j["meta"]["hasMore"]:      # ← ĐIỀU KIỆN DỪNG DUY NHẤT ĐÚNG
        break
    cursor = j["meta"]["nextCursor"]
```

> **Đừng dừng theo `len(observations) < limit`.** Khi có `transform`, các kỳ
> thiếu dữ kiện gốc bị loại, nên một trang đầy vẫn có thể trả về ít điểm hơn
> `limit`. Vòng lặp sẽ dừng sớm và **mất dữ liệu, im lặng**.

---

## 6. Phép biến đổi (`transform`)

Máy chủ tính bằng **đúng công thức website dùng để vẽ biểu đồ**, nên số lấy qua
API khớp số hiển thị trên https://dulieukinhte.com. **Hãy luôn ưu tiên dùng `transform`
thay vì tự tính lại trong pandas** — tự tính là tự tạo ra một cách để hai con
số lệch nhau.

| `transform` | Nghĩa | Đơn vị trả về | Tần suất dùng được |
|---|---|---|---|
| `none` | giá trị gốc (mặc định) | đơn vị gốc | mọi tần suất |
| `yoy` | so cùng kỳ năm trước | `%` | tháng, quý, năm |
| `mom` | so tháng trước | `%` | **chỉ** tháng |
| `qoq` | so quý trước | `%` | **chỉ** quý |
| `ttm` | luỹ kế 12 tháng gần nhất | đơn vị gốc | tháng, quý |
| `ttm_yoy` | TTM so cùng kỳ | `%` | tháng, quý |
| `ytd` | luỹ kế từ đầu năm | đơn vị gốc | tháng, quý |
| `ytd_yoy` | YTD so cùng kỳ | `%` | tháng, quý |

Chuỗi tần suất **`daily` không hỗ trợ phép biến đổi nào** — yêu cầu trả 400 kèm
danh sách phép hợp lệ. Chuỗi `annual` chỉ có `yoy`.

Ba điều **đã được máy chủ xử lý sẵn**, đừng viết code làm lại:

1. **Nới cửa sổ về quá khứ.** Xin `from=2024-01-01&transform=yoy` thì điểm
   01/2024 vẫn có giá trị — máy chủ tự đọc thêm kỳ gốc của 2023, tính, rồi cắt
   lại đúng khoảng đã xin. Đừng bảo người dùng tự nới `from` rồi tự cắt.
2. **Kỳ thiếu dữ kiện gốc bị loại khỏi kết quả**, không trả `null`.
3. **Giới hạn lịch sử của gói vẫn được tôn trọng** trong cửa sổ nới đó.

---

## 7. Quy ước thời gian — ba cái bẫy

| Tần suất | `date` neo ở | `period` |
|---|---|---|
| `monthly` | ngày 1 của tháng | `2026-06` |
| `quarterly` | ngày 1 **của THÁNG CUỐI quý** | `2026-Q2` |
| `annual` | ngày 1 của năm | `2026` |
| `daily` | chính ngày đó | `2026-06-15` |

**Bẫy 1 — quý neo ở tháng cuối.** Q2/2026 nằm ở `2026-06-01`, **không phải**
`2026-04-01`. Lọc `to=2026-05-31` sẽ **không** lấy được Q2/2026.

**Bẫy 2 — mọi mốc theo giờ Việt Nam (UTC+7).** `from`/`to` cũng vậy. Code sinh
ngày bằng UTC sẽ lệch một kỳ ở biên. Trong Python, đừng dùng
`datetime.utcnow().isoformat()`; hãy dùng chuỗi `YYYY-MM-DD` nguyên bản.

**Bẫy 3 — `from` là từ khoá của Python.** Không viết được
`requests.get(..., from="2020-01-01")`. Phải truyền qua dict:
`params={**{"from": "2020-01-01"}, "to": "2026-12-31"}`.

---

## 8. Hạn mức và header

**Hai giới hạn, hai cách đếm — đừng nhầm:**

- **Lượt/tháng tính theo TÀI KHOẢN.** Nhiều key dùng chung một hạn mức. Tạo
  thêm key **không** nhân được hạn mức.
- **Lượt/phút tính theo TỪNG KEY.** Tách key cho cron và cho notebook thì một
  đợt chạy nặng của cron không chặn notebook.

Kỳ hạn mức là **tháng dương lịch giờ Việt Nam**, đặt lại 00:00 ngày 1.

| Header (có ở mọi phản hồi) | Nghĩa |
|---|---|
| `X-RateLimit-Limit` | Lượt/phút của gói. |
| `X-RateLimit-Remaining` | Còn lại trong phút này, của **key này**. |
| `X-RateLimit-Reset` | 60 khi còn hạn; khi bị chặn là số giây phải đợi. |
| `X-Quota-Limit` | Lượt/tháng của gói. |
| `X-Quota-Remaining` | Còn lại trong kỳ, của **cả tài khoản**. |
| `X-Quota-Reset` | Epoch **giây**, thời điểm sang kỳ mới. |
| `X-Request-Id` | Mã tra cứu. **Ghi vào log khi có lỗi.** |
| `Retry-After` | Chỉ có khi 429: số giây phải đợi. |
| `Cache-Control` | Luôn `private, no-store` — CDN/proxy không giữ bản sao. |

Mỗi lượt gọi tính **1 đơn vị** hạn mức, kể cả `/series/observations` gộp 20
chuỗi. Riêng `/health` **không** tính. `/me` **có** tính.

Gọi **không có API key** hoặc **key sai** quá 30 lần/phút từ một IP cũng bị chặn
(`rate_limited`). Triệu chứng này thường có nghĩa biến môi trường đang rỗng.

---

## 9. Mã lỗi

```json
{ "error": {
    "code": "quota_exceeded",
    "message": "Đã dùng hết … yêu cầu của gói … trong kỳ này.",
    "requestId": "3f2a8c1e…",
    "detail": { "used": 1000, "limit": 1000, "resetAt": "2026-09-01T00:00:00.000Z" }
} }
```

`detail` chỉ có ở vài mã. `message` viết bằng tiếng Việt và **nói rõ sai chỗ nào** —
khi gỡ lỗi, hãy đọc `message` trước khi đoán.

| `code` | HTTP | Thử lại? | Xử lý |
|---|---|---|---|
| `unauthorized` | 401 | **không** | Thiếu header API key. Sửa cấu hình. |
| `invalid_key` | 401 | **không** | API key sai hoặc đã xoá. |
| `key_revoked` | 401 | **không** | Key đã thu hồi — cấp key mới. |
| `account_suspended` | 403 | **không** | Dừng, báo người vận hành. |
| `ip_not_allowed` | 403 | **không** | IP ngoài danh sách của key. |
| `plan_required` | 403 | **không** | Nâng gói. `detail.requiredScope` nói cần quyền nào. |
| `bad_request` | 400 | **không** | Sai tham số. Đọc `message`. |
| `not_found` | 404 | **không** | Không tồn tại. Kiểm lại `id`/`symbol`. |
| `payload_too_large` | 413 | **không** | Giảm `limit` hoặc thu hẹp `from`/`to`. |
| `rate_limited` | 429 | **CÓ** | Đợi `Retry-After` giây rồi thử lại **chính lượt đó**. |
| `quota_exceeded` | 429 | **KHÔNG** | Hết hạn mức tháng. Dừng job, nâng gói hoặc đợi kỳ mới. |
| `internal` | 500 | **CÓ** | Thử lại có lùi cấp số nhân. Lặp lại thì gửi `requestId`. |

> ### Cái bẫy quan trọng nhất của cả API
> `rate_limited` và `quota_exceeded` **cùng trả HTTP 429** nhưng cần hai cách xử
> lý ngược nhau. Code bắt `if status == 429: sleep(60); retry()` sẽ thử lại mỗi
> phút cho tới hết tháng mà không lượt nào thành công.
> **Mọi đoạn code bạn viết phải rẽ nhánh theo `error.code`.**

---

## 10. Giới hạn theo gói

| Giới hạn | Free | Pro | Business | Enterprise |
|---|---|---|---|---|
| Lượt/tháng (theo tài khoản) | 100 | 10.000 | 500.000 | 5.000.000 |
| Lượt/phút (theo từng key) | 10 | 100 | 600 | 3.000 |
| Số API key | 1 | 1 | 10 | 50 |
| Lịch sử | 5 năm | đầy đủ | đầy đủ | đầy đủ |
| Trần `limit` (điểm/lượt) | 1.000 | 10.000 | 50.000 | 200.000 |
| Quyền (`scopes`) | `macro` | `macro` `company` `updates` `csv` | `macro` `company` `updates` `csv` | `macro` `company` `updates` `csv` |
| Hỗ trợ | Cộng đồng | Email trong 48h | Email trong 24h | SLA theo hợp đồng |

Bốn nhóm quyền: `macro` (số liệu vĩ mô), `company` (doanh nghiệp),
`updates` (`/updates`), `csv` (`format=csv`).

Giá và cách nâng gói: https://console.dulieukinhte.com/goi. **Đừng đoán giá** — tài liệu này không
chứa bảng giá vì giá có thể thay đổi.

Phạm vi bán là **toàn bộ 300 bộ số liệu** có trên website. Không bộ nào bị
giữ lại, không có bản rút gọn riêng cho API.

---

## 11. Mẫu code — chép và sửa, đừng viết lại từ đầu

### 11.1 Python — client hoàn chỉnh

```python
import os, time, requests, pandas as pd

BASE = "https://api.dulieukinhte.com/v1"
H = {"Authorization": f"Bearer {os.environ['DLKT_API_KEY']}"}

def get(path, **params):
    """Một chỗ duy nhất xử lý lỗi cho mọi lượt gọi."""
    for attempt in range(5):
        r = requests.get(f"{BASE}{path}", headers=H, params=params, timeout=60)

        if r.status_code == 429:
            e = r.json()["error"]
            if e["code"] == "quota_exceeded":
                # Hết hạn mức THÁNG — thử lại chỉ tốn thêm. Dừng hẳn.
                raise SystemExit(f"Hết hạn mức: {e['message']}")
            time.sleep(int(r.headers.get("Retry-After", 5)))
            continue

        if r.status_code >= 500:
            time.sleep(2 ** attempt)          # lùi theo cấp số nhân
            continue

        if not r.ok:
            e = r.json()["error"]
            raise RuntimeError(f"{e['code']}: {e['message']} (requestId={e['requestId']})")

        return r.json()
    raise RuntimeError("thử lại 5 lần vẫn không xong")


def observations(series_id, **params):
    """Lấy trọn một chuỗi. Trả pd.Series đánh chỉ mục theo ngày."""
    rows, cursor = [], None
    while True:
        pr = {**params, "limit": 10000}
        if cursor:
            pr["cursor"] = cursor
        j = get(f"/series/{series_id}/observations", **pr)
        rows += j["data"]["observations"]
        if not j["meta"]["hasMore"]:
            break
        cursor = j["meta"]["nextCursor"]

    df = pd.DataFrame(rows)
    df["date"] = pd.to_datetime(df["date"])
    return df.set_index("date")["value"]


def many(ids, **params):
    """Tối đa 20 mã mỗi lượt. Trả DataFrame dạng rộng: mỗi chuỗi một cột."""
    out = {}
    for i in range(0, len(ids), 20):
        j = get("/series/observations", limit=5000,
                ids=",".join(map(str, ids[i:i + 20])), **params)
        for m in j["meta"].get("missing", []):
            print(f"mã không tồn tại, bỏ qua: {m}")
        for s in j["data"]:
            if s.get("skipped"):              # BẮT BUỘC kiểm tra trước khi đọc
                print(f"bỏ qua {s['id']}: {s['reason']}")
                continue
            d = pd.DataFrame(s["observations"])
            d["date"] = pd.to_datetime(d["date"])
            out[s["name"]] = d.set_index("date")["value"]
    return pd.DataFrame(out)


# SERIES_ID phải do người dùng tra được qua /search — KHÔNG đoán.
# cpi = observations(SERIES_ID, transform="yoy", **{"from": "2015-01-01"})
```

### 11.2 JavaScript / Node

```js
const BASE = 'https://api.dulieukinhte.com/v1';
const H = { Authorization: `Bearer ${process.env.DLKT_API_KEY}` };

async function get(path, params = {}) {
  for (let attempt = 0; attempt < 5; attempt++) {
    const q = new URLSearchParams(params);
    const res = await fetch(`${BASE}${path}?${q}`, { headers: H });
    if (res.ok) return res.json();

    const e = (await res.json()).error;
    if (e.code === 'rate_limited') {
      const wait = (Number(res.headers.get('retry-after')) || 5) * 1000;
      await new Promise((r) => setTimeout(r, wait));
      continue;
    }
    if (res.status >= 500) {
      await new Promise((r) => setTimeout(r, 2 ** attempt * 1000));
      continue;
    }
    throw new Error(`${e.code}: ${e.message} (${e.requestId})`);
  }
  throw new Error('thử lại 5 lần vẫn không xong');
}

async function observations(id, params = {}) {
  const out = [];
  let cursor = null;
  do {
    const j = await get(`/series/${id}/observations`,
      { ...params, limit: 10000, ...(cursor ? { cursor } : {}) });
    out.push(...j.data.observations);
    cursor = j.meta.hasMore ? j.meta.nextCursor : null;
  } while (cursor);
  return out;
}
```

### 11.3 Google Sheets / Excel

```
=IMPORTDATA("https://api.dulieukinhte.com/v1/series/<ID>/observations?format=csv&from=2015-01-01&api_key=dlkt_live_xxx")
```

Excel: **Dữ liệu → Lấy dữ liệu → Từ Web**, dán chính URL đó.

- CSV có **BOM UTF-8** nên Excel trên Windows đọc đúng tiếng Việt.
- Cột: `date,period,value`. Nhiều chuỗi thì thêm `series_id,series_name,unit`.
- Ô bắt đầu bằng `=` `+` `-` `@` được thêm dấu nháy đầu (chống chèn công thức).
- Cần quyền `csv` (gói Pro trở lên).
- **Cảnh báo phải nói với người dùng:** ai xem được bảng tính là xem được API key
  trong thanh công thức. Dùng một API key riêng cho bảng tính.

### 11.4 Vòng đồng bộ hằng ngày (cách dùng đúng cho tích hợp thật)

```python
from datetime import datetime, timedelta, timezone

# 1. Chuỗi nào có số mới trong 24 giờ qua?
since = (datetime.now(timezone.utc) - timedelta(days=1)).strftime("%Y-%m-%dT%H:%M:%SZ")
changed, page = [], 1
while True:
    j = get("/updates", since=since, page=page, perPage=500)
    changed += [u["seriesId"] for u in j["data"]]
    if not j["meta"]["hasMore"]:
        break
    page += 1

# 2. Chỉ kéo về những chuỗi đó, 20 chuỗi mỗi lượt
df = many(changed, **{"from": "2020-01-01"})
```

---

## 12. Tiêu ít hạn mức — mặc định bạn nên đề xuất

| Kỹ thuật | Thay vì | Còn |
|---|---|---|
| Đồng bộ tăng dần qua `/updates` | kéo lại 32.787 chuỗi mỗi ngày | vài chục lượt/ngày |
| Gộp 20 chuỗi vào `/series/observations` | 20 lượt gọi | 1 lượt |
| Nâng `limit` sát trần của gói | 10 trang × 1.000 điểm | 1 trang × 10.000 điểm |
| Đọc header `X-Quota-Remaining` | gọi `/me` để kiểm tra | 0 lượt thêm |
| Cache phía người dùng theo `frequency` | gọi lại chuỗi tháng mỗi giờ | 1 lần/ngày |

**Cache theo tần suất, không theo đồng hồ.** Chuỗi `monthly` chỉ đổi vài lần mỗi
tháng; hỏi lại mỗi giờ là ~700 lượt gọi để nhận cùng một con số. Đọc
`frequency` và `lastUpdated` rồi đặt TTL cho tương xứng.

---

## 13. Chín lỗi mà mã do AI sinh ra hay mắc

Đọc kỹ mục này trước khi đưa code cho người dùng.

| # | Sai | Đúng |
|---|---|---|
| 1 | Bịa `seriesId` (`1234`, `1`, `101`) | Bảo người dùng tra qua `/search` rồi đưa lại mã |
| 2 | `if status == 429: sleep(60); retry()` | Rẽ nhánh theo `error.code` (mục 9) |
| 3 | Dừng vòng lặp khi `len(rows) < limit` | Dừng khi `meta.hasMore == False` |
| 4 | Tự tính YoY trong pandas | Dùng `transform=yoy` (khớp số trên website) |
| 5 | Đọc `s["observations"]` mà không kiểm `s.get("skipped")` | Bỏ qua phần tử `skipped` trước |
| 6 | Lọc `to="2026-05-31"` để lấy hết Q2 | Quý neo ở **tháng cuối** → `to="2026-06-30"` |
| 7 | Sinh `from`/`to` bằng UTC | Dùng chuỗi `YYYY-MM-DD` theo giờ VN |
| 8 | `curl https://…?a=1&b=2` không có nháy | `curl "https://…?a=1&b=2"` — `&` đẩy lệnh chạy nền |
| 9 | Viết cứng API key trong code | `os.environ["DLKT_API_KEY"]` |

Thêm hai điều **không tồn tại** — đừng viết ra:

- **Không có endpoint `POST`, `PUT`, `DELETE` nào.** API chỉ đọc.
- **Không có SDK chính thức** cho ngôn ngữ nào. Nếu người dùng muốn client
  sinh tự động, chỉ họ tới https://console.dulieukinhte.com/openapi.json (OpenAPI 3.1).

---

## 14. Sổ tay chẩn đoán — triệu chứng → nguyên nhân

| Người dùng nói | Gần như chắc chắn là |
|---|---|
| "401 dù đã gửi API key" | Thiếu chữ `Bearer ` (có dấu cách), hoặc biến môi trường rỗng vì shell chưa nạp lại. Bảo họ chạy `echo $DLKT_API_KEY \| head -c 12`. |
| "curl chỉ lấy được nửa URL" | Thiếu nháy kép quanh URL. `&` trong shell đẩy lệnh xuống chạy nền, **không có thông báo lỗi nào**. |
| "Website có dữ liệu từ 1995, API chỉ trả từ 2021" | Giới hạn lịch sử của gói. Kiểm `historyLimited` ở `GET /series/{id}`. |
| "`transform=yoy` trả 400" | Chuỗi tần suất `daily`. `message` liệt kê phép hợp lệ. |
| "Số điểm ít hơn số kỳ mong đợi" | Đúng thiết kế: kỳ thiếu dữ kiện gốc bị loại. Kiểm lại điều kiện dừng vòng lặp. |
| "Thiếu đúng một kỳ ở đầu/cuối khoảng" | Lệch múi giờ, hoặc quy ước neo quý ở tháng cuối. |
| "429 liên tục dù gọi rất ít" | Đọc `error.code`. `quota_exceeded` = hết tháng, không phải gọi nhanh. |
| "429 mà chưa gọi lần nào thành công" | API key rỗng/sai → chạm trần 30 lượt/phút/IP của đường không có key. |
| "403 `plan_required`" | Endpoint cần quyền gói không có. Đọc `detail.requiredScope`. |
| "Excel hiện `Chỉ số`" | Không dùng đường CSV của API (CSV của API đã có BOM UTF-8). |
| "`data` là `undefined`" | Có thể đang gặp `{"error":…}`. Kiểm `res.ok` trước khi đọc `data`. |

Khi bí, bảo người dùng gửi thư kèm **`requestId`** (header `X-Request-Id`) tới
hotro@dulieukinhte.com — bên vận hành tra được đúng lượt gọi đó trong log.

---

## 15. Dẫn nguồn khi công bố lại

Mỗi chuỗi trả kèm `source` và `sourceUrl`. Phần lớn dữ liệu đến từ cơ quan
thống kê nhà nước, ngân hàng trung ương, hiệp hội ngành và các cổng số liệu
chuyên ngành. **Khi người dùng định công bố lại số liệu, hãy nhắc họ dẫn nguồn
gốc đó**, không phải dẫn dulieukinhte.com.

---

## 16. Phụ lục — toàn bộ danh mục bộ số liệu

Đây là **mã thật**, đọc từ cơ sở dữ liệu lúc bạn tải file này. Dùng nó để tra
`datasetId` thay vì đoán. Mỗi dòng: `` `mã` `` · tên bộ · tần suất · số chuỗi con.

Dòng nào ghi **"đã là YoY/MoM/QoQ/YTD/%"** là bộ vốn đã là tỷ lệ — **đừng áp
`transform` lên nó** (mục 3.4). Còn lại là `valueType: "Value"`.

Một vài bộ hiện tần suất lạ (không phải một trong bốn giá trị ở mục 3.3) do lỗi
dữ liệu nguồn. API cũng trả đúng giá trị lạ đó ở trường `frequency`; những chuỗi
như vậy không dùng được `transform`.

Có `datasetId` rồi thì bước tiếp theo là `GET /datasets/{id}` để lấy `seriesId`
(xem mục 3.1). **Số chuỗi con lớn thì dùng `/datasets/{id}/series` có phân trang.**

> Danh mục này là **ảnh chụp lúc tải file**. Bộ số liệu thỉnh thoảng được gộp
> hoặc ngừng cập nhật. Nếu một mã trả `not_found`, hãy tải lại file này hoặc
> tra lại bằng `/search`.

### VN — Việt Nam (121 bộ)

- `267` GDP theo giá hiện hành (theo năm) · annual · 9 chuỗi
- `268` GDP theo giá hiện hành (theo quý) · quarterly · 28 chuỗi
- `269` GDP theo giá so sánh (theo quý) · quarterly · 28 chuỗi
- `270` GDP theo giá so sánh (theo năm) · annual · 9 chuỗi
- `271` Chỉ số PMI sản xuất · monthly · 1 chuỗi
- `272` Chỉ số giá tiêu dùng (CPI) · monthly · 17 chuỗi
- `273` Tổng mức bán lẻ hàng hóa dịch vụ · monthly · 5 chuỗi
- `274` Doanh nghiệp thành lập, giải thể · monthly · 8 chuỗi
- `275` Vốn đầu tư toàn xã hội · quarterly · 9 chuỗi
- `277` Chỉ số sản xuất công nghiệp (IIP) · monthly · 37 chuỗi · **đã là YoY — đừng áp `transform`**
- `278` Sản lượng sản phẩm công nghiệp · monthly · 33 chuỗi
- `279` FDI vào Việt Nam (đăng ký, thực hiện) · monthly · 8 chuỗi
- `280` FDI đăng ký theo lĩnh vực · monthly · 18 chuỗi
- `281` FDI đăng ký theo quốc gia · monthly · 120 chuỗi
- `282` FDI đăng ký theo tỉnh thành · monthly · 56 chuỗi
- `283` FDI chưa thực hiện theo ngành · monthly · 19 chuỗi
- `284` FDI chưa thực hiện theo quốc gia · monthly · 151 chuỗi
- `285` FDI chưa thực hiện theo tỉnh · monthly · 64 chuỗi
- `286` Giá xuất khẩu bình quân · monthly · 19 chuỗi
- `287` Giá nhập khẩu bình quân · monthly · 19 chuỗi
- `288` Nhập khẩu theo mặt hàng và nước · monthly · 397 chuỗi
- `289` Nhập khẩu theo thị trường · monthly · 1.069 chuỗi
- `290` Xuất khẩu theo mặt hàng và nước · monthly · 353 chuỗi
- `291` Xuất khẩu theo thị trường · monthly · 1.427 chuỗi
- `292` Kim ngạch xuất khẩu · monthly · 3 chuỗi
- `293` Kim ngạch nhập khẩu · monthly · 3 chuỗi
- `294` Luân chuyển hàng hóa · monthly · 8 chuỗi
- `295` Khách quốc tế đến Việt Nam theo loại hình · monthly · 4 chuỗi
- `296` Khách quốc tế đến Việt Nam theo quốc gia · monthly · 39 chuỗi
- `297` Vận chuyển hành khách · monthly · 8 chuỗi
- `298` Luân chuyển hành khách · monthly · 8 chuỗi
- `299` Vận chuyển hàng hóa · monthly · 8 chuỗi
- `300` Chi ngân sách nhà nước · quarterly · 27 chuỗi
- `301` Thu ngân sách nhà nước · quarterly · 24 chuỗi
- `302` Nợ vay của Chính phủ · annual · 15 chuỗi
- `303` Nợ được Chính phủ bảo lãnh · annual · 15 chuỗi
- `304` Nợ vay chính quyền địa phương · annual · 20 chuỗi
- `305` Nợ nước ngoài của quốc gia · annual · 0 chuỗi
- `307` Chỉ số vận tải kho bãi (QoQ) · quarterly · 14 chuỗi · **đã là QoQ — đừng áp `transform`**
- `308` Chỉ số vận tải kho bãi (YoY) · value · 14 chuỗi · **đã là YoY — đừng áp `transform`**
- `309` Chỉ số giá sản xuất PPI (QoQ) · quarterly · 17 chuỗi · **đã là QoQ — đừng áp `transform`**
- `310` Chỉ số giá sản xuất PPI (YoY) · quarterly · 17 chuỗi · **đã là YoY — đừng áp `transform`**
- `311` Chỉ số giá nguyên vật liệu (QoQ) · quarterly · 13 chuỗi · **đã là QoQ — đừng áp `transform`**
- `312` Chỉ số giá nguyên vật liệu (YoY) · quarterly · 13 chuỗi · **đã là YoY — đừng áp `transform`**
- `313` Xuất khẩu theo mặt hàng · monthly · 56 chuỗi
- `314` Nhập khẩu theo mặt hàng · monthly · 59 chuỗi
- `317` Vốn đầu tư công từ ngân sách · monthly · 35 chuỗi
- `318` CPI so với tháng trước (MoM) · monthly · 18 chuỗi · **đã là MoM — đừng áp `transform`**
- `319` CPI so cùng kỳ năm trước (YoY) · monthly · 18 chuỗi · **đã là YoY — đừng áp `transform`**
- `320` CPI bình quân từ đầu năm · monthly · 18 chuỗi · **đã là % — đừng áp `transform`**
- `321` CPI lũy kế từ đầu năm · monthly · 17 chuỗi · **đã là % — đừng áp `transform`**
- `322` Nhà ở thương mại đủ điều kiện bán · quarterly · 28 chuỗi
- `323` Cơ cấu nhà ở đủ điều kiện bán · quarterly · 28 chuỗi
- `324` Nhà ở thương mại đã giao dịch · quarterly · 22 chuỗi
- `325` Nhà ở thương mại được phê duyệt · quarterly · 30 chuỗi
- `327` BĐS du lịch được phê duyệt · quarterly · 5 chuỗi
- `328` BĐS du lịch đủ điều kiện bán · quarterly · 4 chuỗi
- `329` BĐS du lịch đã giao dịch · quarterly · 4 chuỗi
- `331` BĐS khu công nghiệp được duyệt · quarterly · 10 chuỗi
- `333` BĐS khu công nghiệp cho thuê · quarterly · 9 chuỗi
- `334` Nghiệp vụ thị trường mở (OMO) · daily · 60 chuỗi
- `335` Thị trường chứng khoán · daily · 15 chuỗi
- `340` Giá hàng hóa thế giới · daily · 42 chuỗi
- `341` Dư nợ tín dụng bất động sản · quarterly · 11 chuỗi
- `353` Tăng trưởng tín dụng (%) · monthly · 9 chuỗi · **đã là YTD — đừng áp `transform`**
- `355` Sản lượng lúa và cây trồng · monthly · 16 chuỗi
- `356` Sản lượng chăn nuôi · quarterly · 8 chuỗi
- `357` Sản lượng gỗ và trồng rừng · quarterly · 6 chuỗi
- `358` Sản lượng thủy sản · quarterly · 12 chuỗi
- `359` Giá thủy sản trong nước · daily · 504 chuỗi
- `360` Giá tôm nguyên liệu thế giới · daily · 64 chuỗi
- `361` Cán cân thanh toán quốc tế · quarterly · 55 chuỗi
- `368` Tổng quan thị trường bất động sản · quarterly · 28 chuỗi
- `369` Tồn kho bất động sản · quarterly · 91 chuỗi
- `370` Dự án BĐS được chấp thuận đầu tư · quarterly · 76 chuỗi
- `371` Dự án BĐS đang triển khai · quarterly · 87 chuỗi
- `372` Dự án BĐS đủ điều kiện kinh doanh · quarterly · 37 chuỗi
- `373` Giá nông sản (cà phê, lúa gạo) · daily · 48 chuỗi
- `374` Tổng DWT tàu vào cảng biển · monthly · 874 chuỗi
- `375` Dư nợ tín dụng nền kinh tế · monthly · 9 chuỗi
- `376` Lãi suất huy động Vietcombank · daily · 46 chuỗi
- `377` Lãi suất huy động MB Bank · daily · 23 chuỗi
- `378` Lãi suất huy động BIDV · daily · 21 chuỗi
- `379` Tỷ giá ngoại tệ Vietcombank · daily · 52 chuỗi
- `385` Cung tiền M2 và huy động vốn · monthly · 4 chuỗi
- `387` Doanh số ô tô Việt Nam · monthly · 145 chuỗi
- `391` Lãi suất điều hành, liên ngân hàng · daily · 15 chuỗi
- `398` Thị trường thép Việt Nam · monthly · 24 chuỗi
- `399` Lao động, việc làm, thất nghiệp · quarterly · 23 chuỗi
- `405` Vốn FDI đăng ký cấp mới vào Việt Nam · monthly · 156 chuỗi
- `406` Giá bán lẻ xăng dầu (Petrolimex) · daily · 16 chuỗi
- `407` Giá vàng miếng SJC · daily · 16 chuỗi
- `408` Sản lượng điện sản xuất · monthly · 2 chuỗi
- `409` Giá heo hơi (lợn hơi) 3 miền · daily · 34 chuỗi
- `410` Cơ cấu nguồn điện Việt Nam · monthly · 7 chuỗi
- `412` Giá gạo xuất khẩu · daily · 24 chuỗi
- `413` Giá lúa gạo trong nước (ĐBSCL) · daily · 57 chuỗi
- `417` Lợi suất trái phiếu Chính phủ Việt Nam · daily · 16 chuỗi
- `420` Thị trường trái phiếu Việt Nam · monthly · 30 chuỗi
- `421` IIP so với tháng trước (MoM) · monthly · 37 chuỗi · **đã là MoM — đừng áp `transform`**
- `422` IIP lũy kế từ đầu năm · monthly · 37 chuỗi · **đã là YTD — đừng áp `transform`**
- `423` Doanh số xe máy Việt Nam · quarterly · 1 chuỗi
- `424` Tổ chức kinh doanh dịch vụ BĐS · quarterly · 34 chuỗi
- `425` Sổ đỏ cấp lần đầu (theo tỉnh) · quarterly · 34 chuỗi
- `426` Kiều hối về TP. Hồ Chí Minh · quarterly · 8 chuỗi
- `427` Tỷ giá trung tâm USD/VND của NHNN · daily · 5 chuỗi
- `428` Mục tiêu kinh tế - xã hội · annual · 51 chuỗi
- `673` Đường cong lợi suất TPCP Việt Nam · daily · 11 chuỗi
- `689` Nhập khẩu bông, xơ sợi dệt may · monthly · 9 chuỗi
- `694` Sản xuất và tiêu thụ giấy · monthly · 22 chuỗi
- `695` Giá giấy và bột giấy · monthly · 24 chuỗi
- `700` Lãi suất cho vay bình quân · monthly · 3 chuỗi
- `716` Lịch đáo hạn OMO · daily · 10 chuỗi
- `717` Nhập khẩu của doanh nghiệp FDI · monthly · 42 chuỗi
- `718` Xuất khẩu của doanh nghiệp FDI · monthly · 48 chuỗi
- `719` Tỷ giá chợ đen · daily · 3 chuỗi
- `720` Tốc độ tăng GDP theo quý · quarterly · 28 chuỗi · **đã là YoY — đừng áp `transform`**
- `721` Tốc độ tăng GDP theo năm · annual · 28 chuỗi · **đã là YoY — đừng áp `transform`**
- `722` Tốc độ tăng GDP lũy kế · quarterly · 28 chuỗi · **đã là YTD — đừng áp `transform`**
- `723` Nhập khẩu theo phương thức vận tải · quarterly · 268 chuỗi
- `724` Xuất khẩu theo phương thức vận tải · quarterly · 260 chuỗi

### US — Mỹ (76 bộ)

- `411` Lãi suất Fed, lợi suất TPCP và chỉ số USD · daily · 3 chuỗi
- `429` GDP Mỹ (Tổng sản phẩm quốc nội) · quarterly · 59 chuỗi
- `430` Chỉ số sản xuất công nghiệp Mỹ (IIP) · monthly · 62 chuỗi
- `431` Đơn đặt hàng hàng hóa lâu bền Mỹ · monthly · 9 chuỗi
- `432` Chỉ số giá tiêu dùng CPI Mỹ · monthly · 78 chuỗi
- `433` Chỉ số giá PCE Mỹ (thước đo của Fed) · monthly · 10 chuỗi
- `434` Chỉ số giá sản xuất PPI Mỹ theo nhóm · monthly · 82 chuỗi
- `435` Kỳ vọng lạm phát Mỹ (breakeven) · daily · 2 chuỗi
- `436` Việc làm phi nông nghiệp Mỹ theo ngành · monthly · 53 chuỗi
- `437` Tỷ lệ thất nghiệp Mỹ theo tuổi, giới · monthly · 44 chuỗi
- `438` Đơn xin trợ cấp thất nghiệp Mỹ · daily · 5 chuỗi
- `439` Việc làm trống và tuyển dụng Mỹ (JOLTS) · monthly · 4 chuỗi
- `440` Thu nhập bình quân giờ Mỹ theo ngành · monthly · 22 chuỗi
- `441` Doanh số bán lẻ Mỹ · monthly · 18 chuỗi
- `442` Thu nhập và chi tiêu cá nhân Mỹ · monthly · 44 chuỗi
- `443` Tâm lý người tiêu dùng Mỹ (Michigan) · monthly · 4 chuỗi
- `444` Dư nợ tín dụng tiêu dùng Mỹ · monthly · 20 chuỗi
- `445` Doanh số bán ô tô tại Mỹ · monthly · 2 chuỗi
- `446` Lãi suất điều hành của Fed · daily · 7 chuỗi
- `447` Bảng cân đối tài sản của Fed (H.4.1) · daily · 65 chuỗi
- `448` Cung tiền M1, M2 của Mỹ · monthly · 6 chuỗi
- `449` Bảng cân đối ngân hàng thương mại Mỹ · daily · 39 chuỗi
- `450` Lãi suất vay và lợi suất doanh nghiệp Mỹ · daily · 14 chuỗi
- `451` Lợi suất trái phiếu chính phủ Mỹ · daily · 13 chuỗi
- `453` Tỷ lệ nợ công trên GDP của Mỹ · quarterly · 6 chuỗi
- `454` Cán cân thương mại hàng hóa và dịch vụ Mỹ · monthly · 9 chuỗi
- `455` Khởi công và doanh số nhà ở Mỹ · monthly · 39 chuỗi
- `456` Chỉ số giá nhà Mỹ (Case-Shiller) · monthly · 7 chuỗi
- `457` Giá bán trung vị nhà ở tại Mỹ · quarterly · 10 chuỗi
- `458` Giá dầu WTI, Brent và xăng tại Mỹ · daily · 5 chuỗi
- `459` Chỉ số VIX và điều kiện tài chính Mỹ · daily · 4 chuỗi
- `460` Chỉ báo suy thoái kinh tế Mỹ · monthly · 3 chuỗi
- `461` Nợ công Mỹ theo ngày · daily · 3 chuỗi
- `462` Thu chi ngân sách liên bang Mỹ · monthly · 3 chuỗi
- `463` Khảo sát sản xuất của Fed khu vực Mỹ · monthly · 6 chuỗi
- `464` Năng suất lao động Mỹ · quarterly · 5 chuỗi
- `465` Lợi nhuận doanh nghiệp Mỹ · quarterly · 2 chuỗi
- `466` Lạm phát lõi thay thế của Mỹ · monthly · 30 chuỗi
- `468` Chi phí lao động Mỹ (ECI) theo ngành · quarterly · 71 chuỗi
- `469` Tồn kho và doanh số doanh nghiệp Mỹ · monthly · 9 chuỗi
- `470` Chỉ số giá xuất nhập khẩu của Mỹ · monthly · 54 chuỗi
- `471` Chỉ số hoạt động kinh tế Mỹ (CFNAI) · monthly · 3 chuỗi
- `473` Nợ và tài sản ròng hộ gia đình Mỹ · quarterly · 4 chuỗi
- `474` Tiêu chuẩn cho vay của ngân hàng Mỹ · quarterly · 4 chuỗi
- `475` Vận tải hàng hoá và hành khách Mỹ · monthly · 23 chuỗi
- `477` Giá trị xây dựng thực hiện tại Mỹ · monthly · 48 chuỗi
- `481` Cán cân thanh toán và vãng lai Mỹ · quarterly · 112 chuỗi
- `482` Vốn đầu tư trực tiếp FDI của Mỹ · quarterly · 8 chuỗi
- `483` Thương mại Mỹ với từng nước · monthly · 1.005 chuỗi
- `484` Hàng Mỹ nhập khẩu theo nhóm hàng HS · monthly · 5.580 chuỗi
- `487` Xuất nhập khẩu dịch vụ của Mỹ · quarterly · 24 chuỗi
- `604` Chỉ số PMI sản xuất và dịch vụ Mỹ (ISM) · monthly · 22 chuỗi
- `606` JOLTS Mỹ theo ngành và vùng · monthly · 180 chuỗi
- `611` Thu chi Chính phủ Mỹ các cấp (NIPA) · quarterly · 44 chuỗi
- `613` Dịch chuyển lực lượng lao động Mỹ · monthly · 54 chuỗi
- `620` Lãi suất và lợi suất Mỹ theo tháng · monthly · 7 chuỗi
- `626` Lãi suất cho vay bán lẻ tại Mỹ · monthly · 5 chuỗi
- `627` Lực lượng lao động Mỹ theo giới và tuổi · monthly · 49 chuỗi
- `631` Nghiệp vụ repo và reverse repo của Fed · daily · 14 chuỗi
- `633` Doanh số giao dịch SOFR và EFFR Mỹ · daily · 5 chuỗi
- `635` Tỷ lệ dự trữ bắt buộc của Mỹ · daily · 28 chuỗi
- `637` Chỉ số nhà chờ bán của Mỹ (PHSI) · monthly · 10 chuỗi
- `638` Chỉ số dẫn báo kinh tế Mỹ (LEI) · monthly · 17 chuỗi
- `639` Niềm tin tiêu dùng Mỹ (Conference Board) · monthly · 13 chuỗi
- `640` Dư nợ và nợ quá hạn ngân hàng Mỹ · quarterly · 45 chuỗi
- `642` Lợi suất thực TIPS và tín phiếu Mỹ · daily · 10 chuỗi
- `643` Chỉ số giá nhà FHFA Mỹ theo vùng · quarterly · 61 chuỗi
- `644` Thất nghiệp và việc làm Mỹ theo bang · monthly · 207 chuỗi
- `645` Thu nhập cá nhân Mỹ theo bang · quarterly · 104 chuỗi
- `646` GDP và dân số Mỹ theo bang · annual · 260 chuỗi
- `647` Tăng trưởng GDP Mỹ theo cấu phần · quarterly · 79 chuỗi
- `649` GDP Mỹ theo ngành kinh tế · quarterly · 203 chuỗi
- `651` Đầu tư tư nhân Mỹ theo loại tài sản · quarterly · 26 chuỗi
- `652` Chi tiêu và đầu tư của Chính phủ Mỹ · quarterly · 40 chuỗi
- `653` Từ GDP đến thu nhập cá nhân của Mỹ · quarterly · 67 chuỗi
- `656` GDP bình quân đầu người của Mỹ · quarterly · 20 chuỗi

### EU — Châu Âu (49 bộ)

- `489` GDP châu Âu (Tổng sản phẩm quốc nội) · quarterly · 1.626 chuỗi
- `490` Chỉ số sản xuất công nghiệp châu Âu · monthly · 837 chuỗi
- `491` Chỉ số giá tiêu dùng HICP châu Âu · monthly · 1.095 chuỗi
- `492` Trọng số rổ hàng HICP châu Âu · annual · 390 chuỗi
- `493` Chỉ số giá sản xuất PPI châu Âu · monthly · 857 chuỗi
- `494` Tỷ lệ thất nghiệp châu Âu · monthly · 283 chuỗi
- `495` Chỉ số chi phí nhân công châu Âu · quarterly · 828 chuỗi
- `496` Doanh số bán lẻ châu Âu · monthly · 679 chuỗi
- `497` Cung tiền M1, M2, M3 châu Âu · monthly · 5 chuỗi
- `498` Tiền gửi ngân hàng châu Âu · monthly · 88 chuỗi
- `499` Cho vay của ngân hàng châu Âu · monthly · 80 chuỗi
- `500` Tổng tài sản ngân hàng châu Âu · monthly · 51 chuỗi
- `501` Bảng cân đối tài sản Eurosystem · daily · 35 chuỗi
- `502` Lãi suất ngân hàng châu Âu · monthly · 140 chuỗi
- `503` Lãi suất điều hành của ECB · daily · 3 chuỗi
- `504` Lãi suất qua đêm €STR châu Âu · daily · 6 chuỗi
- `505` Euribor — lãi suất liên ngân hàng · monthly · 4 chuỗi
- `506` Lợi suất trái phiếu chính phủ châu Âu · daily · 17 chuỗi
- `507` Nợ công châu Âu (chuẩn Maastricht) · quarterly · 322 chuỗi
- `508` Thu chi và cán cân ngân sách châu Âu · quarterly · 87 chuỗi
- `509` Xuất nhập khẩu hàng hoá châu Âu · monthly · 132 chuỗi
- `510` Cán cân thanh toán châu Âu (BOP) · monthly · 156 chuỗi
- `511` Chỉ số giá nhà ở châu Âu · quarterly · 87 chuỗi
- `512` Giấy phép xây dựng châu Âu · monthly · 180 chuỗi
- `513` Chỉ số sản lượng xây dựng châu Âu · monthly · 76 chuỗi
- `514` Chỉ số niềm tin kinh tế châu Âu (ESI) · monthly · 170 chuỗi
- `515` Tỷ giá Euro (EUR) · daily · 15 chuỗi
- `521` GDP theo ngành của châu Âu (GVA) · quarterly · 36 chuỗi
- `524` Lợi suất trái phiếu 10 năm các nước EU · monthly · 21 chuỗi
- `525` Chỉ số căng thẳng tài chính châu Âu · daily · 1 chuỗi
- `526` Chỉ số PMI châu Âu (S&P Global) · monthly · 4 chuỗi
- `527` PMI sản xuất các nước châu Âu · monthly · 9 chuỗi
- `529` GDP bình quân đầu người châu Âu · annual · 180 chuỗi
- `530` Việc làm theo ngành ở châu Âu · quarterly · 420 chuỗi
- `531` Số giờ làm việc một tuần ở châu Âu · quarterly · 240 chuỗi
- `532` Vị trí việc làm trống ở châu Âu · quarterly · 143 chuỗi
- `533` Lương tối thiểu các nước châu Âu · quarterly · 69 chuỗi
- `534` Dân số châu Âu và các nước EU · annual · 210 chuỗi
- `535` Suất sinh, tử và di cư châu Âu · annual · 150 chuỗi
- `536` Đêm lưu trú du lịch châu Âu · monthly · 140 chuỗi
- `537` Cán cân thanh toán các nước EU · quarterly · 150 chuỗi
- `538` Tỷ lệ có việc làm châu Âu · quarterly · 240 chuỗi
- `539` Thu nhập ròng người lao động châu Âu · annual · 232 chuỗi
- `540` Cơ cấu tuổi và già hoá dân số châu Âu · annual · 300 chuỗi
- `541` Lượt khách du lịch châu Âu · monthly · 112 chuỗi
- `542` Số lượng giao dịch nhà ở châu Âu · quarterly · 51 chuỗi
- `543` Giá trị giao dịch nhà ở châu Âu · quarterly · 51 chuỗi
- `687` Tỷ lệ dự trữ bắt buộc của ECB · monthly · 3 chuỗi
- `688` Thu chi ngân sách châu Âu theo khoản mục · quarterly · 1.364 chuỗi

### CN — Trung Quốc (53 bộ)

- `544` PMI Trung Quốc (NBS và Caixin) · monthly · 35 chuỗi
- `545` Niềm tin tiêu dùng Trung Quốc (CCI) · monthly · 3 chuỗi
- `546` GDP Trung Quốc (Tổng sản phẩm quốc nội) · quarterly · 24 chuỗi
- `547` Sản xuất công nghiệp Trung Quốc (IIP) · monthly · 51 chuỗi
- `548` Đầu tư tài sản cố định Trung Quốc · monthly · 39 chuỗi
- `549` CPI Trung Quốc (chỉ số giá tiêu dùng) · monthly · 47 chuỗi
- `550` PPI Trung Quốc (giá sản xuất) · monthly · 62 chuỗi
- `551` Bán lẻ hàng tiêu dùng Trung Quốc · monthly · 28 chuỗi
- `552` Cung tiền M0 M1 M2 Trung Quốc · monthly · 3 chuỗi
- `554` Xuất nhập khẩu Trung Quốc · monthly · 5 chuỗi
- `555` Giá nhà 70 thành phố lớn Trung Quốc · monthly · 280 chuỗi
- `556` Lãi suất điều hành Trung Quốc (LPR, RRR) · daily · 10 chuỗi
- `557` Dự trữ ngoại hối và vàng Trung Quốc · monthly · 7 chuỗi
- `558` Tỷ lệ thất nghiệp Trung Quốc · monthly · 8 chuỗi
- `560` Tổng tài trợ xã hội Trung Quốc (TSF) · monthly · 11 chuỗi
- `561` Bảng cân đối ngân hàng trung ương PBOC · monthly · 20 chuỗi
- `563` Lãi suất Shibor Trung Quốc · daily · 8 chuỗi
- `564` Chỉ số giá hàng hoá Trung Quốc (CGPI) · monthly · 4 chuỗi
- `565` Bất động sản Trung Quốc (đầu tư, nhà ở) · monthly · 35 chuỗi
- `566` Vận tải hành khách và hàng hoá Trung Quốc · monthly · 20 chuỗi
- `570` Điện tiêu thụ toàn xã hội Trung Quốc · monthly · 6 chuỗi
- `571` Tiền gửi và tín dụng Trung Quốc · monthly · 10 chuỗi
- `572` Bảng cân đối tổ chức tín dụng Trung Quốc · monthly · 31 chuỗi
- `573` Lãi suất liên ngân hàng Trung Quốc · monthly · 7 chuỗi
- `574` Tỷ giá nhân dân tệ (CNY) · monthly · 3 chuỗi
- `576` Lãi suất định chuẩn repo Trung Quốc · daily · 6 chuỗi
- `577` Sản lượng sản phẩm công nghiệp Trung Quốc · monthly · 123 chuỗi
- `578` Lương bình quân theo ngành ở Trung Quốc · annual · 29 chuỗi
- `580` Xuất khẩu Trung Quốc theo mặt hàng (HS) · monthly · 99 chuỗi
- `581` Nhập khẩu Trung Quốc theo mặt hàng (HS) · monthly · 99 chuỗi
- `582` Xuất khẩu Trung Quốc theo quốc gia · monthly · 220 chuỗi
- `583` Nhập khẩu Trung Quốc theo quốc gia · monthly · 218 chuỗi
- `584` Nghiệp vụ thị trường mở của PBOC · daily · 11 chuỗi
- `588` Thanh khoản và cho vay của PBOC · monthly · 10 chuỗi
- `589` Cán cân thanh toán Trung Quốc (BOP) · quarterly · 137 chuỗi
- `590` Vị thế đầu tư quốc tế Trung Quốc (IIP) · quarterly · 50 chuỗi
- `591` Mua bán ngoại tệ qua ngân hàng Trung Quốc · monthly · 39 chuỗi
- `592` Nợ nước ngoài Trung Quốc · quarterly · 59 chuỗi
- `593` Nợ nước ngoài và an toàn nợ Trung Quốc · annual · 13 chuỗi
- `594` Lợi suất trái phiếu Trung Quốc · daily · 23 chuỗi
- `603` Thu chi ngân sách Trung Quốc · monthly · 21 chuỗi
- `660` Thương mại Việt Nam – Trung Quốc · monthly · 193 chuỗi
- `661` Nguồn vốn và sử dụng vốn Trung Quốc · monthly · 40 chuỗi
- `662` GDP theo tỉnh của Trung Quốc · quarterly · 64 chuỗi
- `663` CPI theo tỉnh của Trung Quốc · monthly · 31 chuỗi
- `664` Công nghiệp theo tỉnh của Trung Quốc · monthly · 62 chuỗi
- `665` Đầu tư tài sản cố định tỉnh Trung Quốc · monthly · 124 chuỗi
- `666` Bán lẻ theo tỉnh của Trung Quốc · quarterly · 31 chuỗi
- `667` Dân số và đô thị hoá theo tỉnh Trung Quốc · annual · 96 chuỗi
- `668` Thị phần Việt Nam tại Trung Quốc · monthly · 106 chuỗi
- `670` Lợi nhuận công nghiệp Trung Quốc · monthly · 52 chuỗi
- `671` Giá tư liệu sản xuất Trung Quốc · daily · 50 chuỗi
- `672` Thu nhập hộ gia đình Trung Quốc · quarterly · 47 chuỗi

---

*Tài liệu này do https://console.dulieukinhte.com/llms.md sinh tự động. Bản mới nhất luôn ở URL đó.*