Kết nối API với Cổng thông tin truy xuất nguồn gốc quốc gia: yêu cầu kỹ thuật doanh nghiệp cần biết

Theo Nghị định 37/2026/NĐ-CP, dữ liệu truy xuất phải chia sẻ lên Cổng thông tin truy xuất nguồn gốc quốc gia khi hàng hóa thuộc danh mục rủi ro cao do bộ quản lý ngành công bố; còn lại là tự nguyện. Muốn kết nối API, doanh nghiệp cần mã truy vết theo TCVN 13274:2020, đủ dữ liệu tối thiểu và ghi nhận sự kiện chuỗi cung ứng.

Vì sao câu chuyện "kết nối API" trở nên cấp thiết

Nhiều doanh nghiệp sản xuất đang gặp cùng một câu hỏi từ cơ quan quản lý hoặc đối tác: "hệ thống của công ty đã kết nối, chia sẻ dữ liệu với Cổng thông tin truy xuất nguồn gốc sản phẩm, hàng hóa quốc gia chưa?".

Lý do không khó hiểu. Nghị định 37/2026/NĐ-CP quy định chi tiết thi hành Luật Chất lượng sản phẩm, hàng hóa, ban hành và có hiệu lực từ 23/1/2026, dành Điều 23 cho hệ thống truy xuất nguồn gốc. Điều này nêu các nguyên tắc chia sẻ dữ liệu và quy định hai trường hợp dữ liệu được chia sẻ với Cổng thông tin quốc gia: sản phẩm, hàng hóa có mức độ rủi ro cao thuộc danh mục và lộ trình truy xuất bắt buộc do bộ quản lý ngành, lĩnh vực công bố; và tổ chức, cá nhân đăng ký kết nối tự nguyện. Nói cách khác, không phải mọi hệ thống truy xuất đều bắt buộc phải kết nối — nhưng nhóm hàng rủi ro cao thì có.

Song song đó, Bộ Công Thương đưa hệ thống truy xuất nguồn gốc hàng hóa VeriGoods (verigoods.vn) vào vận hành chính thức từ 23/12/2025. Khi ra mắt, Bộ công bố các nhóm hàng rủi ro cao được ưu tiên gồm hóa chất và sản phẩm chứa hóa chất, tiền chất công nghiệp, vật liệu nổ công nghiệp và tiền chất thuốc nổ, nguyên liệu và sản phẩm thuốc lá. Sau đó, Thông tư 31/2026/TT-BCT (ban hành 11/6/2026, hiệu lực 1/7/2026) chính thức hóa lộ trình: từ 1/7/2026 thương nhân đăng ký tài khoản, định danh sản phẩm; từ 1/1/2027 hàng hóa rủi ro cao thuộc phạm vi Bộ Công Thương phải được truy xuất đầy đủ trước khi lưu thông, qua VeriGoods hoặc hệ thống nội bộ có kết nối với VeriGoods. Danh mục cụ thể nằm trong văn bản của Bộ, doanh nghiệp nên đối chiếu trực tiếp. Các ngành hàng khác chưa bắt buộc ngay, và lộ trình do từng bộ quản lý chuyên ngành công bố.

Vấn đề là khi một kỹ sư IT hoặc quản lý chuỗi cung ứng tìm cách thực sự kết nối, thứ họ nhận được phần lớn là tin tức hành chính, chứ không phải thứ họ cần: kết nối bằng cách nào, dữ liệu định dạng ra sao, ai cấp tài khoản. Bài này viết để lấp đúng khoảng trống đó.

Cổng thông tin truy xuất nguồn gốc quốc gia là gì, và nó không phải hệ thống bạn tự cài

Điều đầu tiên cần làm rõ: Cổng thông tin truy xuất nguồn gốc sản phẩm, hàng hóa quốc gia không phải là một phần mềm để doanh nghiệp cài đặt và tự nhập liệu hàng ngày. Nó là một hạ tầng trung gian — hình thành theo Đề án triển khai, áp dụng và quản lý hệ thống truy xuất nguồn gốc được phê duyệt tại Quyết định 100/QĐ-TTg ngày 19/01/2019 — đóng vai trò cầu nối giữa hệ thống truy xuất của các bộ ngành, địa phương và doanh nghiệp.

Nói cách khác: bạn không "dùng" cổng quốc gia như một phần mềm quản lý sản xuất. Bạn vận hành hệ thống truy xuất của riêng mình (tự xây, mua giải pháp, hoặc dùng nền tảng như VNCX), rồi hệ thống đó chia sẻ dữ liệu lên cổng quốc gia — trực tiếp, hoặc qua hệ thống của bộ quản lý ngành như VeriGoods với hàng hóa thuộc phạm vi Bộ Công Thương. Cổng đóng vai trò tổng hợp, đối chiếu và công khai thông tin cho người tiêu dùng cũng như cơ quan quản lý tra cứu.

Bốn nguyên tắc mà Điều 23 Nghị định 37/2026/NĐ-CP đặt ra là: chia sẻ dữ liệu giữa các bên (có thể tổ chức theo mô hình tập trung, tích lũy, mạng lưới hoặc phân tán, với logic phổ biến là mỗi mắt xích nắm được công đoạn liền trước và liền sau mình); sẵn có phần tử dữ liệu chính; minh bạch; và sự tham gia đầy đủ của các bên trong chuỗi cung ứng. Đây là khung để đánh giá một hệ thống có đủ điều kiện chia sẻ dữ liệu hay không.

Ba lớp yêu cầu kỹ thuật phải xong trước khi "bấm kết nối"

Lớp 1 — chuẩn hóa mã theo TCVN 13274:2020

Đây là điểm nhiều doanh nghiệp vấp phải đầu tiên. Tiêu chuẩn quốc gia TCVN 13274:2020 (Truy xuất nguồn gốc — Hướng dẫn định dạng các mã dùng cho truy vết) hướng dẫn cách định dạng mã truy vết sản phẩm và mã truy vết địa điểm; Nghị định 37/2026/NĐ-CP dẫn chiếu tiêu chuẩn này cho hai loại mã đó, và dẫn chiếu TCVN 13275:2020 cho vật mang dữ liệu (mã vạch, QR...). Câu hỏi thực tế hay gặp là: "Tôi đã có mã vạch GS1 (GTIN) cho sản phẩm rồi, có phải làm lại mã khác không?". Thường là không cần làm lại từ đầu, vì mã GS1 vẫn là nền tảng — nhưng cần bảo đảm mã truy vết gắn thêm các thành phần như số lô/sê-ri, và địa điểm có mã định danh (như GLN). Nếu hệ thống nội bộ đang dùng mã tự đặt không theo chuẩn, đây là việc cần làm trước tiên, vì mã không đúng cấu trúc sẽ gây khó khăn ở mọi bước chia sẻ dữ liệu sau đó.

Lớp 2 — bộ dữ liệu tối thiểu phải có trong từng bản ghi

Theo Điều 23 Nghị định 37/2026/NĐ-CP, dữ liệu truy xuất nguồn gốc bao gồm: tên và hình ảnh sản phẩm, hàng hóa; tên và địa chỉ đơn vị sản xuất, kinh doanh; xuất xứ; các sự kiện theo dõi trọng yếu và thời gian diễn ra sự kiện trong chuỗi cung ứng (theo TCVN 12850 hoặc tiêu chuẩn truy xuất toàn cầu của GS1); thương hiệu, nhãn hiệu, số lô/mẻ hoặc số sê-ri (nếu có); hạn sử dụng (nếu có); và các tiêu chuẩn, quy chuẩn được áp dụng. Nghe thì giống một bảng thông tin sản phẩm tĩnh, nhưng điểm dễ bị bỏ sót là yêu cầu về sự kiện và thời gian — dữ liệu không chỉ trả lời sản phẩm là gì, mà còn phải cho biết nó đã đi qua những công đoạn nào, ở đâu, vào lúc nào. Nếu hệ thống chỉ lưu thông tin tĩnh mà không ghi nhận sự kiện (xuất kho, đóng gói, vận chuyển), bạn sẽ không đáp ứng được nguyên tắc "sẵn có phần tử dữ liệu chính" nói ở trên.

Lớp 3 — hạ tầng kết nối thực tế, phần ít được nói tới

Hầu hết bài viết trên mạng chỉ dừng ở câu "hệ thống phải có khả năng kết nối, chia sẻ dữ liệu với Cổng thông tin quốc gia" rồi dừng lại. Trên thực tế, tài liệu kỹ thuật chi tiết (điểm cuối API, cấu trúc dữ liệu, cơ chế xác thực) không được phổ biến rộng như các nền tảng thương mại; doanh nghiệp nên làm việc với đơn vị vận hành cổng hoặc với bộ quản lý ngành của mình để được hướng dẫn đăng ký kết nối và kiểm thử. Không có cơ chế tự phục vụ kiểu đăng ký xong lấy khóa API ngay.

Vì dữ liệu đã chia sẻ có thể hiển thị công khai cho người tiêu dùng quét mã tra cứu, mọi kết nối nên được thử nghiệm kỹ trước khi đưa vào vận hành chính thức. Nếu công ty bạn chưa từng làm việc với một hệ thống của cơ quan nhà nước theo mô hình xin cấp quyền như vậy, hãy chuẩn bị tinh thần rằng bước này tốn thời gian hành chính hơn là thời gian viết mã.

Hai con đường kết nối: tự làm hay đi qua nền tảng trung gian

Đây là quyết định thực tế nhất mà một doanh nghiệp vừa và nhỏ phải cân nhắc.

Con đường thứ nhất là tự xây dựng: doanh nghiệp có đội ngũ IT riêng, tự chuẩn hóa dữ liệu theo TCVN 13274:2020, xin tài khoản kết nối, tự phát triển module đẩy dữ liệu và duy trì đồng bộ liên tục. Con đường này phù hợp với doanh nghiệp lớn, đã có hệ thống ERP hoặc MES nội bộ và đủ nguồn lực kỹ thuật để theo đuổi một tích hợp có thể mất nhiều tháng.

Con đường thứ hai là đi qua một nền tảng truy xuất nguồn gốc đã chuẩn hóa dữ liệu và có sẵn kênh kết nối. Với hàng hóa thuộc phạm vi Bộ Công Thương, Thông tư 31/2026/TT-BCT cho phép dùng trực tiếp VeriGoods hoặc hệ thống nội bộ có kết nối với VeriGoods, nên câu hỏi kỹ thuật thực chất là hệ thống của bạn có kết nối được với VeriGoods hay không.

Với VNCX, dữ liệu được tổ chức theo chuẩn GS1 (EPCIS, Digital Link) ngay từ đầu: mã sản phẩm, mã lô, mã địa điểm và sự kiện chuỗi cung ứng được ghi nhận trong quá trình vận hành, nên việc ánh xạ sang cấu trúc mà cổng quốc gia hoặc hệ thống của bộ ngành yêu cầu là bước chuyển đổi, không phải nhập liệu lại.

Quy trình đăng ký và kết nối, theo thứ tự hợp lý

Trình tự thường diễn ra như sau. Trước tiên là chuẩn hóa nội bộ: rà soát toàn bộ mã sản phẩm, mã lô, mã địa điểm hiện có, đối chiếu với TCVN 13274:2020 và bổ sung những gì còn thiếu — bước này thường mất nhiều thời gian nhất vì liên quan đến dữ liệu lịch sử. Tiếp theo là đăng ký tài khoản kết nối với cơ quan có thẩm quyền: với nhóm hàng thuộc phạm vi Bộ Công Thương, thương nhân đăng ký tài khoản trên VeriGoods theo Thông tư 31/2026/TT-BCT; với các trường hợp khác, liên hệ đơn vị vận hành cổng quốc gia hoặc bộ quản lý ngành. Sau khi được cấp quyền, doanh nghiệp thử nghiệm kết nối, gửi thử một số bản ghi mẫu để xác nhận dữ liệu đúng cấu trúc và đủ trường bắt buộc, rồi mới đưa vào vận hành chính thức. Bước cuối, thường bị đánh giá thấp nhất nhưng lại quan trọng nhất về lâu dài, là duy trì đồng bộ dữ liệu liên tục — bản chất của hệ thống là dữ liệu sự kiện chuỗi cung ứng phải được cập nhật theo từng lô, từng công đoạn, không phải "kết nối một lần rồi thôi".

Những lỗi thường gặp khi doanh nghiệp tự kết nối

Ba lỗi hay gặp nhất. Thứ nhất, nhầm giữa cổng truy xuất nguồn gốc cấp tỉnh, hệ thống của bộ ngành và cổng quốc gia — đăng ký ở một tầng chưa chắc đồng nghĩa với việc dữ liệu tự động chảy lên tầng khác, doanh nghiệp cần xác nhận rõ luồng kết nối với cơ quan quản lý. Thứ hai, dùng mã sản phẩm tự đặt không theo GS1/TCVN 13274:2020, khiến dữ liệu phải chuyển đổi lại khi kiểm thử. Thứ ba, đánh giá thấp yêu cầu dữ liệu sự kiện — nhiều doanh nghiệp chỉ chuẩn bị được hồ sơ sản phẩm tĩnh mà không có cơ chế ghi nhận sự kiện xuất kho, đóng gói, vận chuyển, nên không duy trì được việc chia sẻ dữ liệu lâu dài.

Nên bắt đầu từ đâu nếu doanh nghiệp chưa có hệ thống truy xuất nào

Nếu công ty bạn thuộc nhóm hàng rủi ro cao của Bộ Công Thương thì không còn nhiều thời gian: giai đoạn đăng ký tài khoản, định danh sản phẩm đã bắt đầu từ 1/7/2026, và từ 1/1/2027 hàng hóa phải được truy xuất đầy đủ trước khi lưu thông. Nếu ngành hàng của bạn chưa nằm trong danh mục bắt buộc, đây vẫn là thời điểm hợp lý để chuẩn bị, vì lộ trình do từng bộ ngành công bố dần, và việc chuẩn hóa mã theo GS1/TCVN 13274:2020 sớm sẽ giúp doanh nghiệp không bị động khi đến lượt ngành mình.

Lời khuyên thực tế nhất: đừng bắt đầu bằng câu hỏi "làm sao gọi được API của cổng quốc gia", vì đó là bước cuối cùng, không phải bước đầu. Hãy bắt đầu bằng việc kiểm tra xem hệ thống mã hóa sản phẩm, lô hàng hiện tại có tuân theo chuẩn GS1 hay không, và dữ liệu sự kiện chuỗi cung ứng có được ghi nhận theo thời gian hay chỉ là bảng thông tin tĩnh. Trả lời được hai câu đó rồi, việc kết nối API — dù tự làm hay qua một nền tảng trung gian — chỉ còn là bước kỹ thuật cuối cùng.

Câu hỏi thường gặp

Doanh nghiệp nào bắt buộc phải chia sẻ dữ liệu với Cổng thông tin truy xuất nguồn gốc quốc gia?

Theo Điều 23 Nghị định 37/2026/NĐ-CP, bắt buộc với sản phẩm, hàng hóa có mức độ rủi ro cao thuộc danh mục và lộ trình truy xuất bắt buộc do bộ quản lý ngành công bố. Các tổ chức, cá nhân khác có thể đăng ký kết nối tự nguyện.

Mã truy vết sản phẩm phải theo tiêu chuẩn nào?

Nghị định 37/2026/NĐ-CP dẫn chiếu TCVN 13274:2020 cho mã truy vết sản phẩm và mã truy vết địa điểm, và TCVN 13275:2020 cho vật mang dữ liệu. Mã GS1 sẵn có (GTIN, GLN) vẫn là nền tảng để xây mã truy vết.

Hàng hóa thuộc Bộ Công Thương có mốc thời gian nào?

Theo Thông tư 31/2026/TT-BCT, từ 1/7/2026 thương nhân đăng ký tài khoản và định danh sản phẩm trên VeriGoods; từ 1/1/2027 hàng hóa rủi ro cao phải được truy xuất đầy đủ trước khi lưu thông.

Dữ liệu truy xuất tối thiểu gồm những gì?

Tên, hình ảnh sản phẩm; tên, địa chỉ đơn vị sản xuất, kinh doanh; xuất xứ; các sự kiện trọng yếu và thời gian diễn ra trong chuỗi cung ứng; thương hiệu, số lô hoặc sê-ri, hạn sử dụng (nếu có); và các tiêu chuẩn, quy chuẩn áp dụng.

Nguồn tham khảo

• Nghị định 37/2026/NĐ-CP, Điều 23 — Hệ thống truy xuất nguồn gốc (Hệ thống Pháp luật)
• Thông tư 31/2026/TT-BCT quy định về truy xuất nguồn gốc sản phẩm, hàng hóa thuộc phạm vi quản lý của Bộ Công Thương (Bộ Công Thương)
• Bộ Công Thương ban hành Thông tư quy định về truy xuất nguồn gốc sản phẩm, hàng hóa (Tạp chí Công Thương)
• Vận hành hệ thống truy xuất nguồn gốc hàng hóa từ 23/12 (Báo Lào Cai)
• Truy xuất nguồn gốc: Trụ cột của quản lý, kinh doanh hiện đại — về Quyết định 100/QĐ-TTg (Báo Nhân Dân)
• Danh mục Tiêu chuẩn quốc gia TCVN 2022 — TCVN 13274:2020, TCVN 13275:2020 (Ủy ban Tiêu chuẩn Đo lường Chất lượng Quốc gia)