{"openapi":"3.1.0","info":{"title":"Dữ Liệu Kinh Tế API","version":"1.0.0","description":"Truy cập chương trình vào kho dữ liệu kinh tế Việt Nam, Mỹ, châu Âu và Trung Quốc.\n\nHạn mức tính theo TÀI KHOẢN, không theo khoá. Hai mã 429 khác nhau: `rate_limited` nghĩa là chậm lại và thử lại; `quota_exceeded` nghĩa là hết hạn mức tháng, thử lại không có ích.\n\nTài liệu đầy đủ: https://console.dulieukinhte.com/huong-dan","contact":{"name":"Hỗ trợ","email":"hotro@dulieukinhte.com","url":"https://console.dulieukinhte.com/huong-dan"}},"servers":[{"url":"https://api.dulieukinhte.com/v1","description":"Bản chính thức"}],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"tags":[{"name":"Tài khoản"},{"name":"Danh mục"},{"name":"Số liệu"},{"name":"Doanh nghiệp"},{"name":"Hệ thống"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Authorization: Bearer dlkt_live_…"},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","invalid_key","key_revoked","account_suspended","ip_not_allowed","plan_required","bad_request","not_found","rate_limited","quota_exceeded","payload_too_large","internal"]},"message":{"type":"string"},"requestId":{"type":["string","null"],"description":"Gửi kèm khi báo lỗi."},"detail":{"type":"object"}},"required":["code","message"]}}},"Observation":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Neo 00:00 giờ VN. Quý neo ở ngày 1 THÁNG CUỐI quý."},"period":{"type":"string","examples":["2026-06","2026-Q2","2026"]},"value":{"type":["number","null"]}}},"Series":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"path":{"type":"array","items":{"type":"string"},"description":"Chuỗi tên từ bộ số liệu xuống chỉ tiêu."},"datasetId":{"type":"integer"},"economy":{"type":"string","enum":["VN","US","EU","CN"]},"frequency":{"type":"string","enum":["daily","monthly","quarterly","annual"]},"unit":{"type":["string","null"]},"source":{"type":["string","null"]},"sourceUrl":{"type":["string","null"]},"lastUpdated":{"type":["string","null"],"format":"date-time"}}},"Dataset":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"economy":{"type":"string"},"frequency":{"type":"string"},"unit":{"type":["string","null"]},"source":{"type":["string","null"]},"sourceUrl":{"type":["string","null"]},"lastUpdated":{"type":["string","null"],"format":"date-time"}}},"PageMeta":{"type":"object","properties":{"page":{"type":"integer"},"perPage":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"},"hasMore":{"type":"boolean"}}},"CursorMeta":{"type":"object","properties":{"count":{"type":"integer"},"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"],"description":"Truyền lại vào ?cursor= để lấy trang sau."},"limit":{"type":"integer"}}}},"responses":{"Error":{"description":"Lỗi","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":{"page":{"name":"page","in":"query","description":"Trang, từ 1.","schema":{"type":"integer","minimum":1,"default":1}},"perPage":{"name":"perPage","in":"query","description":"Số mục mỗi trang.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}}},"paths":{"/me":{"get":{"tags":["Tài khoản"],"summary":"Khoá này là của ai, gói gì, còn bao nhiêu hạn mức","responses":{"200":{"description":"OK"},"401":{"description":"Lỗi","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/health":{"get":{"tags":["Hệ thống"],"summary":"Kiểm tra sống","security":[],"description":"Không cần khoá, không tính vào hạn mức.","responses":{"200":{"description":"OK"}}}},"/economies":{"get":{"tags":["Danh mục"],"summary":"Bốn nền kinh tế","responses":{"200":{"description":"OK"},"401":{"description":"Lỗi","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/datasets":{"get":{"tags":["Danh mục"],"summary":"Danh mục bộ số liệu","description":"Toàn bộ kho số liệu (295 bộ).","parameters":[{"name":"economy","in":"query","description":"Lọc theo nền kinh tế.","schema":{"type":"string","enum":["VN","US","EU","CN"]}},{"name":"q","in":"query","description":"Tìm trong tên và mô tả.","schema":{"type":"string"}},{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/perPage"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Dataset"}},"meta":{"$ref":"#/components/schemas/PageMeta"}}}}}},"401":{"description":"Lỗi","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Lỗi","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/datasets/{id}":{"get":{"tags":["Danh mục"],"summary":"Một bộ số liệu + cây chuỗi con","parameters":[{"name":"id","in":"path","description":"ID bộ số liệu.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Lỗi","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Lỗi","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/datasets/{id}/series":{"get":{"tags":["Danh mục"],"summary":"Danh sách chuỗi của một bộ (phân trang)","parameters":[{"name":"id","in":"path","description":"ID bộ số liệu.","schema":{"type":"integer"}},{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/perPage"}],"responses":{"200":{"description":"OK"},"404":{"description":"Lỗi","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/series/{id}":{"get":{"tags":["Số liệu"],"summary":"Metadata + phạm vi thời gian của một chuỗi","description":"firstDate/lastDate đã tính theo giới hạn lịch sử của gói bạn đang dùng.","parameters":[{"name":"id","in":"path","description":"ID chuỗi.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Series"}}}}}},"404":{"description":"Lỗi","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/series/{id}/observations":{"get":{"tags":["Số liệu"],"summary":"Số liệu của một chuỗi","description":"Phân trang bằng CON TRỎ (không phải page/offset): dùng meta.nextCursor.\n\nKhi dùng transform, máy chủ TỰ nới cửa sổ về quá khứ để điểm đầu tiên trong khoảng bạn xin vẫn có giá trị, rồi cắt lại đúng khoảng đó.","parameters":[{"name":"id","in":"path","description":"ID chuỗi.","schema":{"type":"integer"}},{"name":"from","in":"query","description":"YYYY-MM-DD (giờ VN).","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","description":"YYYY-MM-DD (giờ VN).","schema":{"type":"string","format":"date"}},{"name":"limit","in":"query","description":"Trần theo gói.","schema":{"type":"integer","minimum":1,"default":1000}},{"name":"cursor","in":"query","description":"meta.nextCursor của lượt trước.","schema":{"type":"string"}},{"name":"order","in":"query","description":"","schema":{"type":"string","enum":["asc","desc"],"default":"asc"}},{"name":"transform","in":"query","description":"Phép biến đổi. Chuỗi theo ngày không hỗ trợ.","schema":{"type":"string","enum":["none","yoy","mom","qoq","ttm","ttm_yoy","ytd","ytd_yoy"],"default":"none"}},{"name":"format","in":"query","description":"csv cần gói Pro trở lên.","schema":{"type":"string","enum":["json","csv"],"default":"json"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"series":{"$ref":"#/components/schemas/Series"},"observations":{"type":"array","items":{"$ref":"#/components/schemas/Observation"}}}},"meta":{"$ref":"#/components/schemas/CursorMeta"}}}},"text/csv":{"schema":{"type":"string"}}}},"400":{"description":"Lỗi","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Lỗi","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Lỗi","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Lỗi","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/series/observations":{"get":{"tags":["Số liệu"],"summary":"Số liệu của nhiều chuỗi một lượt (tối đa 20)","parameters":[{"name":"ids","in":"query","description":"Danh sách id ngăn cách dấu phẩy, tối đa 20.","schema":{"type":"string"}},{"name":"from","in":"query","description":"","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","description":"","schema":{"type":"string","format":"date"}},{"name":"limit","in":"query","description":"Số điểm mỗi chuỗi.","schema":{"type":"integer"}},{"name":"transform","in":"query","description":"","schema":{"type":"string","enum":["none","yoy","mom","qoq","ttm","ttm_yoy","ytd","ytd_yoy"]}},{"name":"format","in":"query","description":"","schema":{"type":"string","enum":["json","csv"]}}],"responses":{"200":{"description":"OK"},"400":{"description":"Lỗi","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Lỗi","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/updates":{"get":{"tags":["Số liệu"],"summary":"Chuỗi nào vừa đổi số liệu (đồng bộ tăng dần)","description":"Gói Pro trở lên. `since` lùi tối đa 90 ngày.","parameters":[{"name":"since","in":"query","description":"ISO 8601. Bắt buộc.","schema":{"type":"string","format":"date-time"}},{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/perPage"}],"responses":{"200":{"description":"OK"},"400":{"description":"Lỗi","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Lỗi","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/search":{"get":{"tags":["Danh mục"],"summary":"Tìm bộ số liệu, chuỗi hoặc doanh nghiệp theo tên","parameters":[{"name":"q","in":"query","description":"Tối thiểu 2 ký tự.","schema":{"type":"string"}},{"name":"type","in":"query","description":"","schema":{"type":"string","enum":["all","dataset","series","company"],"default":"all"}},{"name":"economy","in":"query","description":"","schema":{"type":"string","enum":["VN","US","EU","CN"]}},{"name":"limit","in":"query","description":"","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"OK"},"400":{"description":"Lỗi","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/companies":{"get":{"tags":["Doanh nghiệp"],"summary":"Danh sách doanh nghiệp niêm yết","description":"Gói Pro trở lên.","parameters":[{"name":"exchange","in":"query","description":"","schema":{"type":"string","enum":["HOSE","HNX","UPCOM"]}},{"name":"q","in":"query","description":"Tìm theo mã hoặc tên.","schema":{"type":"string"}},{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/perPage"}],"responses":{"200":{"description":"OK"},"403":{"description":"Lỗi","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/companies/{symbol}":{"get":{"tags":["Doanh nghiệp"],"summary":"Hồ sơ một doanh nghiệp","parameters":[{"name":"symbol","in":"path","description":"Mã chứng khoán, vd VNM.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"403":{"description":"Lỗi","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Lỗi","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/companies/{symbol}/financials":{"get":{"tags":["Doanh nghiệp"],"summary":"Báo cáo tài chính","parameters":[{"name":"symbol","in":"path","description":"","schema":{"type":"string"}},{"name":"statementType","in":"query","description":"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.","schema":{"type":"integer","minimum":1,"maximum":5,"default":2}},{"name":"freq","in":"query","description":"","schema":{"type":"string","enum":["year","quarter"],"default":"year"}},{"name":"limit","in":"query","description":"Số kỳ.","schema":{"type":"integer","minimum":1,"maximum":60,"default":12}},{"name":"format","in":"query","description":"","schema":{"type":"string","enum":["json","csv"]}}],"responses":{"200":{"description":"OK"},"403":{"description":"Lỗi","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Lỗi","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/companies/{symbol}/prices":{"get":{"tags":["Doanh nghiệp"],"summary":"Giá OHLCV theo ngày","parameters":[{"name":"symbol","in":"path","description":"","schema":{"type":"string"}},{"name":"from","in":"query","description":"","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","description":"","schema":{"type":"string","format":"date"}},{"name":"limit","in":"query","description":"","schema":{"type":"integer"}},{"name":"order","in":"query","description":"","schema":{"type":"string","enum":["asc","desc"]}},{"name":"format","in":"query","description":"","schema":{"type":"string","enum":["json","csv"]}}],"responses":{"200":{"description":"OK"},"403":{"description":"Lỗi","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Lỗi","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}