Frankfurter API tỷ giá lịch sử: ngày hiệu lực và ngày không có số

Chuyên viên Kỹ thuật ProxyVN 04-29-2026 Đang tính... phút đọc

Frankfurter API tỷ giá lịch sử là cách lấy tỷ giá tham chiếu theo ngày mà không cần khóa. Bài này viết cho người dựng bảng quy đổi cần biết con số thuộc ngày nào. ProxyVN gọi API thật ngày 05/11/2026, thấy hỏi Chủ nhật được trả tỷ giá thứ Sáu, thấy v1 lặng lẽ bỏ VND, và thấy v2 cho số khác v1 ở cùng một ngày.

Frankfurter API tỷ giá lịch sử: mục tiêu và phạm vi không lặp

Phần này chốt bài toán, đầu ra và những gì bài không làm, vì tỷ giá là chủ đề dễ bị hiểu thành lời khuyên tài chính.

Bài toán cần giải

Một nhóm kế toán nội bộ muốn đổi doanh thu USD và EUR về VND theo ngày phát sinh. Họ gọi API cho từng ngày trong tháng và ghi vào bảng. Một số ngày là cuối tuần, API vẫn trả số, nên bảng trông đầy đủ. Tới lúc đối chiếu, họ không giải thích được con số ngày Chủ nhật đến từ đâu.

Đầu ra nghiệm thu

Đầu ra là bảng gồm base, quote, ngày yêu cầu, ngày hiệu lực, rate, nguồn và cách lấp ngày trống. Mỗi dòng phải trả lời được: số này công bố ngày nào, bởi ai, dùng cho ngày nào. Một bảng thiếu cột ngày hiệu lực sẽ không kiểm chứng được.

Ranh giới với bài ECB và realtime

Bài ECB Data API SDMX trong cùng cụm đi sâu vào dataflow, dimension và trạng thái quan sát. Bài này chỉ tra tỷ giá theo ngày qua một API gọn. Bài cũng không nói về giá giao dịch thời gian thực, vì Frankfurter không phải nguồn đó và tài liệu của họ nói rõ không dành cho giao dịch trực tiếp.

Không phải lời khuyên tài chính

Bài không tư vấn đầu tư, không dự đoán tỷ giá, không gợi ý thời điểm đổi tiền. Mọi con số chỉ để minh họa cách xử lý dữ liệu. Tỷ giá dùng cho kế toán và thuế phải theo quy định áp dụng cho doanh nghiệp, anh em hỏi người phụ trách chuyên môn.

Giới hạn của lab

Lab gọi API công khai không khóa, khoảng 40 lượt, nghỉ 1.5 giây. Dữ liệu là tháng 10 và đầu tháng 11/2026, cùng vài mốc lịch sử. Lab không so với tỷ giá ngân hàng thương mại Việt Nam nào. Số trong v2 là số pha trộn của API tại lần gọi, có thể đổi nếu nguồn cập nhật.

Ai nên đọc

Bài hợp với kế toán nội bộ, người dựng dashboard đa tiền tệ, kỹ sư dữ liệu cần cột quy đổi tham khảo. Người đang dùng đường dẫn cũ trong các bài hướng dẫn trên mạng nên đọc kỹ phần v1 và v2.

Thuật ngữ dùng trong bài

Base là đồng gốc, quote là đồng đích. Rate là số đơn vị quote cho một đơn vị base. Ngày yêu cầu là ngày anh em gửi lên. Ngày hiệu lực là trường date API trả về. Tỷ giá tham chiếu là con số do ngân hàng trung ương công bố để tham khảo, không phải giá anh em mua bán được.

Thu tỷ giá tham chiếu theo ngày, base currency và ghi ngày nguồn với Frankfurter API tỷ giá lịch sử

Phần này đi qua hai phiên bản API, vì hầu hết bài hướng dẫn cũ chỉ nói về một bản.

Nguồn tài liệu đã đọc

Lab đọc trang chủ và tài liệu Frankfurter. Trang ghi API miễn phí, không cần khóa, mã nguồn mở, có 239 tiền tệ từ 108 ngân hàng trung ương và nguồn chính thức, lịch sử tới 1948. Trang cũng ghi v1 đã được thay bằng v2 nhưng vẫn giữ lâu dài, và lưu tỷ giá vào cơ sở dữ liệu riêng là việc được khuyến khích.

Hai bản API khác nhau về bản chất

Bảng: Hai bản API khác nhau về bản chất
Đặc điểm	v1	v2
Đường dẫn	/v1/2026-10-30	/v2/rates?date=2026-10-30
Nguồn mặc định	ECB	Pha trộn nhiều nguồn
Dạng response	Object có rates	Mảng các dòng
Số tiền tệ lab đếm	30 ở /currencies	Có VND
EUR sang USD ngày 30/10	1.1172	1.1175
Chỉ lấy ECB	Mặc định	/v2/providers/ecb/rates

Cùng ngày, hai con số

Lab gọi hai bản cho EUR sang USD ngày 30/10/2026. V1 trả 1.1172, v2 trả 1.1175. Đối chiếu với ECB Data API cho đúng ngày đó ra 1.1172. Vậy v1 là số ECB, v2 mặc định là số pha trộn. Hai số đều đúng theo định nghĩa của nó, nhưng không được trộn trong một cột.

import requests
 
s = requests.Session()
s.headers["User-Agent"] = "ProxyVN-docs-lab/1.0 (+https://proxy.vn/)"
 
a = s.get("https://api.frankfurter.dev/v1/2026-10-30", params={"symbols": "USD"}, timeout=60).json()
b = s.get("https://api.frankfurter.dev/v2/rates",
          params={"date": "2026-10-30", "quotes": "USD"}, timeout=60).json()
c = s.get("https://api.frankfurter.dev/v2/providers/ecb/rates",
          params={"date": "2026-10-30", "quotes": "USD"}, timeout=60).json()
print(a["rates"]["USD"], b[0]["rate"], c[0]["rate"])
# 1.1172 1.1175 1.1172

Ba giá trị trong dòng chú thích là output thật. Dòng thứ ba cho thấy v2 vẫn lấy được đúng số ECB khi gọi qua provider.

Xem ai góp vào số pha trộn

Tham số expand=providers thêm mảng nguồn vào mỗi dòng. Với EUR sang USD ngày 30/10, các nguồn đầu tiên lab đọc có AMCM 1.1198, BAM 1.1192, BANXICO 1.1195, BCB 1.1164, BCBO 1.1169, BCC 1.1162, BCCCD 1.114. Các ngân hàng trung ương công bố vào thời điểm và theo cách khác nhau, nên số lệch nhau tới vài phần nghìn. Số 1.1175 là phép tính của Frankfurter trên các số đó.

Chọn v1, v2 hay provider

Nếu quy định nội bộ gọi tên ECB, dùng provider ecb, vì số đó trùng nguồn gốc. Nếu cần đồng tiền ECB không công bố, như VND, phải dùng v2. Khi đó ghi rõ là số pha trộn hoặc chỉ định một provider cụ thể. Tài liệu ghi số pha trộn là phép tính của chính Frankfurter, còn truy vấn từng provider thì theo điều khoản của provider đó.

Tỷ giá ECB đọc thế nào

Số ECB là tỷ giá tham chiếu theo một đơn vị euro. Cả v1 và ECB đều trả USD trên EUR. Với base USD, v1 tính ngược: EUR 0.89509 và JPY 157.25, đúng bằng 1 chia 1.1172 và 175.68 chia 1.1172 khi làm tròn. Tỷ giá chéo này do Frankfurter tính, không phải số ECB công bố.

Tham số amount

V1 nhận amount để nhân sẵn: amount=100 cho USD 111.72. Tiện cho màn hình quy đổi, nhưng bảng dữ liệu nên lưu rate gốc. Nhân ở lớp hiển thị để không mất độ chính xác và không phải lưu nhiều lần.

Chọn base currency và ngày tỷ giá tham chiếu trong Frankfurter API tỷ giá lịch sử

Chọn sai ngày hay sai đồng là lỗi không báo. Phần này chỉ ra các ca lab gặp.

Ngày lịch sử sớm nhất

Đồng tiền biến mất

Đồng tiền biến mất

V1 trả 404 cho 31/12/1998 và 200 cho 04/01/1999 với USD 1.1789. Mốc này là ngày đầu tiên của chuỗi euro ECB trong API này. Trang chủ nói lịch sử tới 1948, nhưng đó là của toàn hệ thống v2 và tùy đồng tiền. Với VND, /v2/currency/vnd ghi start_date 1998-07-07.

VND trong v1 và v2

Lab gọi v1 với symbols=VND và nhận HTTP 404 message not found. Trong danh sách 30 tiền tệ của v1 không có VND. Với v2, EUR sang VND ngày 30/10 là 28782, USD sang VND là 25756. Tên lỗi 404 không nói rằng đồng tiền không được hỗ trợ, nên người mới dễ nghĩ sai đường dẫn.

Lỗi im lặng khi trộn đồng tiền

Đây là ca nguy hiểm nhất của v1. Lab gọi base=USD, symbols=VND,EUR. API trả 200 với rates chỉ có EUR, VND biến mất mà không báo. Script chỉ kiểm mã 200 sẽ cho rằng bảng đầy đủ, rồi lỗi KeyError ở nơi khác hoặc tệ hơn là để trống cột. Sau mỗi lời gọi phải so tập đồng trả về với tập đã xin.

def rate_v1(date, base, quotes):
    r = s.get(f"https://api.frankfurter.dev/v1/{date}",
              params={"base": base, "symbols": ",".join(quotes)}, timeout=60)
    if r.status_code == 404:
        return None, "khong_co"
    r.raise_for_status()
    j = r.json()
    miss = set(quotes) - set(j["rates"])
    if miss:
        raise ValueError(f"thieu dong tien: {sorted(miss)}")
    return j, "ok"

Với base USD, quotes VND và EUR, hàm báo ValueError thiếu VND, đúng hành vi mong muốn. Thà dừng sớm còn hơn ghi bảng thiếu.

Nguồn của VND

V2 liệt kê các nguồn có VND như BCRA, BDI, BI, BIS, BNA, BNM, BOC, BOM, CBC và nhiều ngân hàng trung ương khác. Lab gọi /v2/providers/sbv và nhận 404, tức trong danh sách không có Ngân hàng Nhà nước Việt Nam dưới khóa đó. Số USD sang VND trong Frankfurter là số do các ngân hàng trung ương nước ngoài công bố rồi pha trộn, không phải tỷ giá trung tâm của Việt Nam.

Mức chênh giữa các nguồn VND

Ngày 30/10, số pha trộn USD sang VND là 25756. Các nguồn lab đọc gồm BCRA 25803, BDI 25809, BI 25713, BNA 25798, BNM 25768, BOM 25709. Chênh từ thấp tới cao trong mẫu này khoảng 100 đồng. Với kế toán tại Việt Nam, đây là lý do không dùng số này thay tỷ giá theo quy định.

Base không tồn tại

Base=XXX trả 404. Ngày tương lai trên v1 cũng 404. Ba loại lỗi khác nhau, gồm ngày trước mốc đầu, đồng không hỗ trợ và ngày tương lai, đều ra cùng thông điệp not found. Script cần tự phân biệt bằng cách kiểm danh sách /currencies và so ngày với hôm nay trước khi gọi.

Danh sách tiền tệ nên cache

Endpoint /v1/currencies trả 30 mã, /v2/currency/vnd trả chi tiết một đồng. Danh sách này đổi chậm, nên tải một lần mỗi tuần là đủ. Kiểm trước khi gọi giúp tránh lượt gọi thừa và làm log rõ hơn.

Giữ ngày hiệu lực response cùng base, quote trong Frankfurter API tỷ giá lịch sử

Trường date trong response là trường quan trọng nhất của bài này.

Ngày yêu cầu khác ngày trả về

Ngày yêu cầu khác ngày hiệu lực

Ngày yêu cầu khác ngày hiệu lực

Ngày 01/11/2026 là Chủ nhật. Lab gọi /v1/2026-11-01 và nhận date 2026-10-30 với USD 1.1172. API không báo lỗi, nó trả ngày làm việc gần nhất trước đó. Gọi 31/10 cũng ra 30/10. Lab thử lễ Giáng sinh: 25/12/2025 và 26/12/2025 đều trả date 2025-12-24 với 1.1787, vì ECB không công bố hai ngày đó.

Lưu cả hai ngày

Bảng phải có cột requested_date và effective_date. Nếu chỉ lưu ngày yêu cầu, người đọc tưởng ngày Chủ nhật có tỷ giá riêng. Nếu chỉ lưu ngày hiệu lực, bảng mất dấu ý định ban đầu. Cột chênh số ngày giữa hai ngày là tín hiệu kiểm tra rất đơn giản.

import datetime as D
 
def row_v1(req, base, quote):
    j, st = rate_v1(req, base, [quote])
    if st != "ok":
        return {"requested": req, "effective": None, "rate": None, "state": st}
    eff = j["date"]
    gap = (D.date.fromisoformat(req) - D.date.fromisoformat(eff)).days
    return {"requested": req, "effective": eff, "base": j["base"], "quote": quote,
            "rate": j["rates"][quote], "gap_days": gap, "source": "frankfurter_v1_ecb",
            "state": "dung_ngay" if gap == 0 else "lay_ngay_truoc"}
 
print(row_v1("2026-11-01", "EUR", "USD"))

Với đầu vào đó, gap_days là 2 và state là lay_ngay_truoc. Cột này giúp lọc các dòng không có số công bố đúng ngày.

Khoảng ngày bỏ qua cuối tuần

Lab gọi khoảng 19/10 tới 04/11 trên v1 và nhận 13 ngày có số trong 17 ngày lịch. Bốn ngày thiếu là 24, 25, 31/10 và 01/11. Đây là hành vi trái với gọi từng ngày: gọi đơn lẻ thì nhận ngày trước, gọi khoảng thì ngày đó vắng mặt. Một pipeline trộn hai kiểu gọi sẽ có hai kiểu dữ liệu.

Bảng: Khoảng ngày bỏ qua cuối tuần
Ngày	Thứ	Gọi đơn lẻ v1	Trong khoảng v1	v2 mặc định
30/10	Sáu	1.1172	1.1172	1.1175
31/10	Bảy	1.1172, date 30/10	không có	1.1179
01/11	Chủ nhật	1.1172, date 30/10	không có	1.1181
02/11	Hai	không gọi	1.1216	1.1191
03/11	Ba	không gọi	1.1179	1.1192

V2 có số cả cuối tuần

Bảng trên cho thấy v2 trả dòng cho 31/10 và 01/11 với giá trị riêng. Lý do hợp lý là pha trộn có các nguồn công bố ngày khác, hoặc phép làm mượt. Khi lab xem nguồn của ngày 01/11 cho VND, các provider đầu danh sách mang date 2026-10-30. Vì vậy một dòng v2 có date Chủ nhật không có nghĩa là ngày đó có công bố mới. Lab không có tài liệu về thuật toán pha trộn chi tiết.

V2 với ngày tương lai

Lab gọi v2 với date 2026-11-07 vào ngày 05/11 và nhận 200 với date 2026-11-05. V1 trả 404 cho ngày tương lai. Hai bản xử lý khác nhau, nên code chuyển từ v1 sang v2 có thể mất một lớp bảo vệ. Script phải tự chặn ngày chưa tới.

V2 khi chỉ định provider

Lab gọi v2 với date 2026-11-01, providers=ecb và nhận date 2026-10-30, rate 1.1172, đúng như v1. Như vậy chọn provider ecb cho hành vi giống v1. Một lựa chọn rõ ràng như thế dễ giải thích hơn số pha trộn.

Khoảng ngày bị dời điểm đầu

Lab gọi v1 từ 2020-01-01 tới 2026-11-04 và nhận start_date 2019-12-31, 1755 dòng. Ngày 01/01/2020 là ngày nghỉ, nên API dời điểm đầu về ngày có số trước đó, và bảng có thêm một dòng ngoài khoảng yêu cầu. Phép lọc theo ngày sau khi nạp sẽ loại đúng dòng này. Phép đếm số dòng kỳ vọng cũng phải tính tới điều đó.

Trường amount và base trong response

Luôn đọc lại base và amount từ response, không dựa vào giá trị đã gửi. Một lỗi tham số bị bỏ qua sẽ lộ ra ở đây. Với v2, mỗi dòng đã có date, base, quote, rate, nên ghép bảng dễ hơn object lồng của v1.

Xử lý ngày nghỉ hoặc khoảng ngày không có record trong Frankfurter API tỷ giá lịch sử

Ngày không có số là một sự thật của dữ liệu. Phần này chốt cách xử lý có ghi rõ.

Ba cách và hệ quả

Ba cách xử lý ngày trống

Ba cách xử lý ngày trống

Bảng: Ba cách và hệ quả
Cách	Ngày nghỉ hiện gì	Dùng khi	Cần ghi
Để trống	Không có rate	Phân tích chuỗi thời gian	Lý do trống
Lấy ngày trước	Rate của ngày làm việc trước	Quy đổi giao dịch	effective_date
Nội suy	Số tính ra	Không khuyến nghị cho kế toán	Công thức

Không ghi 0

Ngày không có tỷ giá không phải tỷ giá bằng 0. Một số script dùng fillna(0) theo thói quen. Khi nhân doanh thu với 0, dòng đó biến mất khỏi tổng mà không ai biết. Bảng tỷ giá không được chứa số 0.

Lấp bằng ngày trước có kiểm soát

Cách phổ biến là forward fill có giới hạn, ví dụ tối đa bốn ngày cho kỳ nghỉ dài. Nếu khoảng trống vượt ngưỡng, nên báo lỗi vì có thể dữ liệu nguồn bị thiếu. Ngưỡng bốn ngày là gợi ý, anh em chỉnh theo lịch nghỉ.

import pandas as pd
 
j = s.get("https://api.frankfurter.dev/v1/2026-10-19..2026-11-04",
          params={"symbols": "USD"}, timeout=60).json()
a = pd.Series({k: v["USD"] for k, v in j["rates"].items()})
a.index = pd.to_datetime(a.index)
full = a.reindex(pd.date_range("2026-10-19", "2026-11-04"))
out = pd.DataFrame({"rate": full.ffill(limit=4)})
out["effective"] = pd.Series(a.index, index=a.index).reindex(full.index).ffill(limit=4)
print(out.loc["2026-10-30":"2026-11-02"])

Đoạn này tạo 17 dòng từ 13 số thật, và mỗi dòng giữ ngày hiệu lực của con số. Bốn dòng cuối tuần có effective là ngày thứ Sáu trước đó.

Ngày chưa công bố

Trong ngày, số của hôm đó có thể chưa có. Lab gọi /latest vào ngày 05/11 và nhận date 2026-11-04. Tài liệu ECB ghi mốc giờ tham chiếu trong tiêu đề chuỗi là 2.15 pm C.E.T., công bố sau đó. Job chạy buổi sáng giờ Việt Nam sẽ nhận số hôm trước. Đây là hành vi đúng, chỉ cần ghi effective_date.

Giao dịch cuối tuần

Một đơn hàng ngày Chủ nhật dùng tỷ giá thứ Sáu theo cách lấy ngày trước. Có doanh nghiệp quy định dùng tỷ giá ngày làm việc sau. Đây là chính sách kế toán, không phải quyết định của lập trình viên. Bảng chỉ cần thể hiện đúng chính sách đã chọn.

Kiểm khoảng trống bất thường

Sau khi nạp, anh em liệt kê các ngày làm việc không có số. Ngày lễ ECB như 01/05 hay 26/12 sẽ xuất hiện, phần còn lại đáng xem. Lịch công bố của nguồn là tài liệu đối chiếu. Một danh sách ngắn các ngày nghỉ đã biết giúp phép kiểm chạy tự động.

Múi giờ của ngày

Ngày trong Frankfurter là ngày lịch của bản công bố, không có giờ. Đơn hàng lúc 23:00 giờ Việt Nam thuộc ngày nào là quyết định riêng. Bảng giao dịch nên chốt theo giờ Việt Nam rồi tra rate, và ghi quy ước vào tài liệu dự án. Nội dung liên quan tới múi giờ có ở bài đồng bộ múi giờ với IP proxy.

Đối soát conversion với tỷ giá nguồn, không coi là quote giao dịch trong Frankfurter API tỷ giá lịch sử

Phần này giữ cho con số không bị hiểu sai.

Đối soát với ECB

Lab đối chiếu Frankfurter v1 với ECB Data API cho các ngày 29/10 tới 04/11. Hai bên cùng 1.113, 1.1172, 1.1216, 1.1179, 1.1267. Năm trên năm ngày khớp. Phép đối chiếu này nên chạy theo tháng cho vài cặp tiền. Nếu lệch, kiểm base và phiên bản trước khi nghi nguồn.

Tỷ giá tham chiếu khác giá thực trả

Tỷ giá ngân hàng trung ương không có phí, không có chênh lệch mua bán. Giá anh em trả tại ngân hàng hay cổng thanh toán luôn khác. Vì vậy cột trong bảng nên đặt tên reference_rate, không đặt exchange_rate chung chung. Tên cột đúng tránh được nhiều cuộc họp.

Tài liệu nói gì về giới hạn

Trang Frankfurter ghi API dành cho các nhu cầu như hệ thống, báo cáo và nghiên cứu qua chuỗi lịch sử, và không xây cho giao dịch trực tiếp hay tiền tệ biến động mạnh trong ngày. Một ứng dụng hiện giá đổi tiền theo thời gian thực cần nguồn khác. Câu cảnh báo này nên được đặt gần con số khi hiển thị cho người dùng.

Quy đổi chéo

Với hai đồng không có cặp trực tiếp, anh em đi qua đồng trung gian hoặc để API tính bằng base. Phép chéo tạo sai số làm tròn nhỏ. Lab thấy 1 chia 1.1172 ra 0.895095, API trả 0.89509, tức API làm tròn năm chữ số. Bảng nên lưu rate nguyên văn, không tính lại ở nhiều nơi.

Lưu độ chính xác

Rate là số thập phân. Tính tiền bằng float có thể lệch ở chữ số cuối. Với số tiền thật, nên dùng Decimal và làm tròn theo quy định. Lab đọc JSON thành float vì chỉ minh họa, code kế toán nên đọc bằng parse_float=Decimal.

import json, decimal
 
r = s.get("https://api.frankfurter.dev/v1/2026-10-30", params={"symbols": "USD"}, timeout=60)
j = json.loads(r.text, parse_float=decimal.Decimal)
print(j["rates"]["USD"], type(j["rates"]["USD"]).__name__)

Với cách này giá trị giữ nguyên 1.1172 dạng Decimal. Phép nhân với số tiền sau đó không phát sinh sai số nhị phân.

Ví dụ quy đổi một đơn hàng cuối tuần

Giả sử có đơn 500 USD phát sinh Chủ nhật 01/11/2026, và dự án chọn chính sách lấy ngày trước. Với v2 chỉ định số pha trộn, USD sang VND ngày 01/11 là 25759, cho 12879500 đồng. Với ngày 30/10, số đó là 25756, cho 12878000 đồng. Hai cách cùng hợp lý trên giấy và chênh 1500 đồng. Khoản chênh nhỏ này chính là lý do chính sách phải được ghi ra, để hai người tính không ra hai số.

Một nguồn cho một báo cáo

Báo cáo tháng nên dùng một nguồn duy nhất từ đầu tới cuối. Đổi nguồn giữa chừng tạo ra bước nhảy không liên quan gì tới thị trường. Nếu buộc phải đổi, anh em đánh dấu ngày đổi trên biểu đồ và ghi chú trong báo cáo. Dữ liệu đã chốt kỳ không nên tính lại bằng nguồn mới.

Kiểm tính hợp lý tự động

Một phép kiểm đơn giản là so rate hôm nay với hôm trước. Mức đổi vượt vài phần trăm trong một ngày với các đồng lớn là dấu hiệu lỗi dữ liệu hoặc nhầm chiều base và quote. Nhầm chiều là lỗi hay gặp nhất: 0.89509 và 1.1172 cùng một cặp tiền nhưng ngược hướng. Cờ cảnh báo chỉ để người xem lại, không tự sửa số.

Ghi chiều tỷ giá vào tên

Cách tránh nhầm chiều là luôn đọc theo mẫu "1 base bằng rate quote". Bảng dùng hai cột base và quote riêng, không đặt tên kiểu usd_eur. Tên ghép như vậy không cho biết đồng nào đứng trước theo quy ước nào. Hai cột riêng cũng giúp lọc dễ hơn khi có nhiều cặp tiền.

Giữ lại response gốc

Mỗi lần tải nên lưu JSON thô kèm thời điểm gọi, cạnh bảng đã chuẩn hóa. Khi có người hỏi về một con số, anh em mở đúng response cũ thay vì gọi lại, vì số pha trộn có thể đã đổi. Tệp JSON rất nhỏ nên lưu lâu dài gần như không tốn chỗ.

Quy định tại Việt Nam

Doanh nghiệp tại Việt Nam thường phải dùng tỷ giá theo quy định kế toán và thuế áp dụng. Bài không nêu quy định cụ thể vì không phải phạm vi lab đã kiểm. Frankfurter phù hợp cho báo cáo quản trị, phân tích xu hướng, dashboard nội bộ. Việc dùng cho sổ sách chính thức cần người có chuyên môn xác nhận.

Đường tải và vai trò proxy với Frankfurter API tỷ giá lịch sử

Phần này giữ phần mạng đơn giản, vì API này không tạo ra nhu cầu phức tạp.

Tải theo khoảng và lưu cục bộ

Một lời gọi khoảng 2020 tới nay chỉ trả 1755 dòng cho một cặp tiền. Tải một lần rồi mỗi ngày tải thêm phần mới là đủ. Trang tài liệu khuyến khích lưu cục bộ để giảm tải. Tài liệu cũng có định dạng CSV và NDJSON ở v2 cho khoảng dài, lab chưa thử.

Tải lại cửa sổ gần

Số v2 pha trộn có thể đổi khi nguồn công bố muộn. Pipeline nên tải lại khoảng bảy ngày gần nhất và ghi đè có kiểm soát. Với provider ecb thì số ít đổi hơn. Lab chưa quan sát thay đổi vì chỉ chạy một ngày.

Proxy có cần không

Không cần. API công khai, không khóa, gọi thẳng là cách đúng. Tài liệu cho biết máy chủ không lưu IP theo phần bảo mật họ công bố. Script chỉ cần gọi tuần tự và nghỉ vài giây, xem thêm bài rate limit API khi dùng proxy. Nếu mạng công ty bắt buộc qua cổng ra, anh em khai báo chuỗi theo định dạng proxy.

Tự vận hành

Mã nguồn mở nên có thể tự chạy một instance khi cần kiểm soát hoặc chạy nội bộ. Khi đó dữ liệu cập nhật do anh em chịu trách nhiệm. Lab chưa tự vận hành.

Các tác vụ thu thập khác cần IP trong nước thì anh em có thể mua proxy Việt Nam tại trang chủ ProxyVN.

Khóa phiên bản

Lab chạy Python 3.12.10, requests 2.34.2, pandas 3.1.1. Base URL có v1 hoặc v2. Vì cấu trúc response hai bản khác nhau, hàm đọc nên tách riêng theo bản, kèm test JSON mẫu.

Đầu ra nghiệm thu bảng base, quote, effective date, rate và ngày không có dữ liệu của Frankfurter API tỷ giá lịch sử

Mục này chốt bảng và danh sách kiểm.

Schema của bảng

Nghiệm thu bảng tỷ giá

Nghiệm thu bảng tỷ giá

Bảng: Schema của bảng
Cột	Ví dụ thật	Ghi chú
requested_date	2026-11-01	Ngày cần số
effective_date	2026-10-30	Trường date
base	EUR	Đọc từ response
quote	USD	Đọc từ response
reference_rate	1.1172	Nguyên văn
source	frankfurter_v1_ecb	Có cả bản và nguồn
fill_method	lay_ngay_truoc	Theo chính sách
fetched_at	2026-11-05	Ngày tải

Danh sách kiểm

Ngày: có cả ngày yêu cầu và ngày hiệu lực.
Nguồn: không trộn v1, v2 pha trộn và provider trong một cột.
Đồng tiền: tập trả về khớp tập đã xin.
Ngày trống: không ghi 0, có ghi cách lấp.
Tên cột: gọi là tỷ giá tham chiếu.
Đối soát: có kiểm mẫu với nguồn gốc.

Câu kết luận được phép viết

Từ lab có thể viết rằng hỏi ngày nghỉ được trả ngày làm việc trước. Trong v1, đồng không hỗ trợ có thể biến mất mà vẫn HTTP 200 khi đi cùng đồng khác. V2 mặc định khác ECB ở cùng ngày. Không nên viết số nào là "đúng" cho kế toán tại Việt Nam.

Những gì lab chưa chạy

Lab chưa thử CSV, NDJSON, group theo tuần hoặc tháng, chưa chạy instance riêng. Lab chưa theo dõi số v2 đổi theo thời gian, chưa đọc thuật toán pha trộn. Lab chưa so với tỷ giá trong nước.

Mỗi con số tỷ giá cần đi kèm ngày hiệu lực và nguồn. Không có hai cột đó thì không ai kiểm được con số ngày Chủ nhật đến từ đâu.

Frankfurter API tỷ giá lịch sử: câu hỏi thường gặp

Các câu dưới đây gom những điểm hay bị hỏi.

Có cần khóa API không?

Không. Tài liệu ghi API công khai miễn phí, kể cả cho dùng thương mại với số pha trộn.

Vì sao hỏi Chủ nhật lại trả thứ Sáu?

V1 trả ngày công bố gần nhất trước đó. Trường date cho biết đúng ngày.

Vì sao có tỷ giá VND trong v2 mà không có trong v1?

V1 dùng tiền tệ của ECB, không có VND. V2 lấy từ nhiều ngân hàng trung ương.

Có nên dùng số pha trộn cho kế toán?

Bài không khuyên. Hãy theo quy định áp dụng và hỏi người phụ trách kế toán.

Giá này mua được ở ngân hàng không?

Không. Đây là tỷ giá tham chiếu, không gồm chênh lệch và phí.

V1 có bị tắt không?

Tài liệu ghi v1 đã được thay nhưng vẫn giữ lâu dài. Dự án mới nên dùng v2.

Có cần gọi từng ngày không?

Không. Dùng khoảng ngày cho nhanh, rồi tự xử lý ngày trống.

Proxy có tác dụng gì ở đây?

Hầu như không. Chỉ dùng khi mạng công ty bắt buộc đi qua cổng ra.

Frankfurter API tỷ giá lịch sử và những điều cần nhớ

Frankfurter API tỷ giá lịch sử cho bảng tham chiếu gọn khi anh em lưu cả ngày hiệu lực, không trộn v1 với số pha trộn của v2 và kiểm đủ đồng tiền sau mỗi lời gọi. Proxy.vn - Nhà cung cấp dịch vụ proxy chất lượng hàng đầu Việt Nam khuyên anh em ghi rõ nguồn khi dùng Frankfurter API tỷ giá lịch sử.