Vì sao câu chuyện "kết nối API" đột nhiên trở nên khẩn cấp
Có một mẫu công văn tôi đã thấy lặp lại ở nhiều doanh nghiệp sản xuất trong nửa đầu năm 2026: Sở Khoa học và Công nghệ gửi thông báo yêu cầu rà soát hệ thống truy xuất nguồn gốc, kèm câu hỏi mà chủ doanh nghiệp nào cũng lúng túng — "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 đã có hiệu lực từ 23/1/2026, trong đó nêu rõ nguyên tắc chia sẻ dữ liệu truy xuất nguồn gốc và yêu cầu các hệ thống truy xuất phải kết nối với Cổng thông tin quốc gia. Song song đó, hệ thống truy xuất nguồn gốc riêng của Bộ Công Thương (theo Thông tư 31/2026/TT-BCT) đã chính thức vận hành từ 23/12/2025 và trở thành bắt buộc từ 1/1/2026 với các nhóm hàng rủi ro cao: hóa chất và sản phẩm chứa hóa chất, tiền chất công nghiệp, tiền chất thuốc nổ và vật liệu nổ công nghiệp, nguyên liệu và sản phẩm thuốc lá. Các ngành hàng khác chưa bắt buộc ngay, nhưng lộ trình đã được công bố theo từng bộ quản lý chuyên ngành, nên chỉ là vấn đề thời gian.
Vấn đề là khi một kỹ sư IT hoặc quản lý chuỗi cung ứng gõ cụm từ này lên Google để tìm cách thực sự kết nối, thứ họ nhận được toàn là tin tức hành chính — cổng vận hành từ bao giờ, tỉnh nào đã kết nối thử — chứ không phải thứ họ cần: kết nối bằng cách nào, dữ liệu format ra sao, ai cấp tài khoản, và mất bao lâu. Bài này viết để lấp đúng khoảng trống đó, dựa trên những gì tôi và đội kỹ thuật tại vncheck.vn đã trực tiếp làm việc khi tích hợp cho khách hà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 (truyxuatnguongoc.gov.vn) 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 — theo đúng tinh thần của Đề án 100 (Quyết định 100/QĐ-TTg năm 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, doanh nghiệp và cả hệ thống quốc tế. Mục tiêu ban đầu của đề án là 100% hệ thống truy xuất của các bộ, ngành kết nối được với cổng, và ít nhất 70% giải pháp truy xuất đang được các doanh nghiệp trong nước sử dụng có khả năng kết nối tương tự.
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ư vncheck), rồi hệ thống đó đẩy dữ liệu lên cổng quốc gia qua API theo chuẩn quy định. 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à Nghị định 37/2026/NĐ-CP đặt ra cho việc chia sẻ dữ liệu giữa các hệ thống là: dữ liệu được chia sẻ theo mô hình một bước trước – một bước sau (mỗi mắt xích chỉ cần biết công đoạn liền trước và liền sau mình, không cần thấy toàn bộ chuỗi), có thể tổ chức theo kiểu tập trung, tích lũy, mạng lưới hoặc phân tán; dữ liệu chính phải luôn sẵn có; toàn bộ quá trình phải minh bạch; và mọi bên tham gia chuỗi cung ứng phải có mặt trong hệ thống truy xuất, không được bỏ sót mắt xích nào. Đây chính là bốn tiêu chí mà bất kỳ hệ thống nào muốn xin kết nối API cũng sẽ bị đánh giá dựa trên đó.
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 mà rất 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), do Bộ Khoa học và Công nghệ công bố cuối năm 2020, quy định cách định dạng mã truy vết sản phẩm và mã truy vết địa điểm. Câu hỏi thực tế mà khách hàng của tôi hay hỏi 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?". Câu trả lời là không cần làm lại từ đầu — TCVN 13274:2020 được xây dựng tương thích với hệ thống mã số mã vạch GS1 mà Việt Nam đã áp dụng, nhưng bạn cần đảm bảo mã truy vết (traceability code) gắn thêm các thành phần bắt buộc như số lô/sê-ri, và với địa điểm phải có mã địa điểm toàn cầu (GLN) hoặc mã tương đương. Nếu hệ thống nội bộ của bạn đang dùng mã tự đặt không theo chuẩn GS1, đây là việc cần làm trước tiên, vì cổng quốc gia sẽ từ chối những bản ghi có mã không đúng cấu trúc.
Lớp 2 — bộ dữ liệu tối thiểu phải có trong từng bản ghi
Quy định hiện hành yêu cầu dữ liệu truy xuất tối thiểu phải bao gồm: tên và hình ảnh sản phẩm, tên và địa chỉ đơn vị sản xuất – kinh doanh, xuất xứ hàng hóa, thương hiệu/nhãn hiệu, mã truy xuất nguồn gốc và mã địa điểm, thời gian diễn ra sự kiện trong chuỗi cung ứng, số lô hoặc số sê-ri (nếu có), hạn sử dụng (nếu có), và tiêu chuẩn kỹ thuật quốc gia hoặc quốc tế được áp dụng cho sản phẩm đó. 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 "thời gian diễn ra sự kiện" — cổng quốc gia không chỉ muốn biết sản phẩm là gì, mà muốn 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 của bạn chỉ lưu thông tin tĩnh (tên sản phẩm, nhà sản xuất) mà không ghi nhận sự kiện theo thời gian thực (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ó của dữ liệu chính" nói ở trên.
Lớp 3 — hạ tầng kết nối thực tế, phần mà báo chí không nói cho bạn
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 thông qua giao diện lập trình ứng dụng (API)" rồi dừng lại đúng đó. Không ai nói bạn phải làm gì tiếp theo. Trên thực tế, tài liệu đặc tả API chi tiết (endpoint, cấu trúc payload, cơ chế xác thực) không được công khai rộng rãi — nó chỉ được cấp cho tổ chức, doanh nghiệp sau khi đăng ký tài khoản kết nối với cơ quan vận hành (thường thông qua Sở Khoa học và Công nghệ địa phương hoặc trực tiếp với đơn vị quản lý cổng). Đây là lý do các bài báo chỉ liệt kê được vài tỉnh đã "test thử kết nối thành công một số API" — Long An, Cà Mau, Cần Thơ hoàn tất trước, Trà Vinh, Cao Bằng, Đắk Nông theo sau — vì mỗi đơn vị phải trải qua một vòng xin cấp quyền và kiểm thử riêng, không có cổng self-service kiểu đăng ký xong lấy API key ngay như các nền tảng thương mại.
Môi trường sandbox để kiểm thử được đặt tại một địa chỉ con riêng của hệ thống, tách biệt hoàn toàn với môi trường production — điều này bắt buộc vì dữ liệu đẩy lên production sẽ hiển thị công khai cho người tiêu dùng quét mã tra cứu, nên mọi kết nối đều phải qua giai đoạn thử nghiệm và được phê duyệt trước khi go-live. Nếu công ty bạn chưa từng làm việc với một API chính phủ theo mô hình xin cấp quyền thủ công 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 code.
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, và cũng là phần các bài hướng dẫn chính thống hoàn toàn bỏ qua vì họ viết cho cơ quan quản lý, không viết cho doanh nghiệp.
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 vài tháng.
Con đường thứ hai là dùng qua một nền tảng truy xuất nguồn gốc đã kết nối sẵn với cổng quốc gia. Trên thực tế, đây là cách phần lớn doanh nghiệp vừa và nhỏ đang làm — báo chí đã ghi nhận một số nền tảng như CheckVN đã tích hợp vào cổng truy xuất nguồn gốc của nhiều địa phương (Hà Nội, Quảng Ninh, Hưng Yên, Hòa Bình, Cần Thơ) với hơn 3.000 doanh nghiệp và gần 10.500 sản phẩm đang vận hành qua nền tảng đó, hay Checkee công bố đã kết nối thành công với cổng truy xuất nguồn gốc quốc gia. Bộ Công Thương cũng thừa nhận điều này khi công bố sẽ hỗ trợ doanh nghiệp nhỏ theo hai hướng: hỗ trợ chuyển đổi dữ liệu từ hệ thống truy xuất hiện có sang hệ thống của Bộ, và hỗ trợ kết nối truy xuất với hệ thống hóa đơn điện tử, khai thuế nếu doanh nghiệp có nhu cầu.
Với vncheck.vn, chúng tôi đi theo đúng logic này khi xây dựng phần kết nối cho khách hàng: việc chuẩn hóa mã theo TCVN 13274:2020, ánh xạ dữ liệu GS1/EPCIS sẵn có sang cấu trúc mà cổng quốc gia yêu cầu, và duy trì đồng bộ sự kiện chuỗi cung ứng theo thời gian thực đã được xử lý ở tầng nền tảng — doanh nghiệp chỉ cần nhập liệu sản phẩm và vận hành quy trình sản xuất như bình thường, phần còn lại là việc của hệ thống.
Quy trình đăng ký và kết nối, theo đúng thứ tự thực tế
Dựa trên những lần làm việc trực tiếp với Sở Khoa học và Công nghệ và đơn vị vận hành cổng, 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, thường nộp qua Sở Khoa học và Công nghệ địa phương hoặc bộ quản lý chuyên ngành (với nhóm hàng thuộc phạm vi Bộ Công Thương thì làm việc trực tiếp theo hướng dẫn tại Thông tư 31/2026/TT-BCT). Sau khi được cấp quyền, doanh nghiệp thử nghiệm kết nối trên môi trường sandbox, gửi thử một số bản ghi mẫu để đơn vị vận hành xác nhận dữ liệu đúng cấu trúc và đủ trường bắt buộc. Chỉ sau khi vượt qua vòng kiểm thử này mới được cấp quyền kết nối sang môi trường production. 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 — cổng quốc gia không chấp nhận kiểu "kết nối một lần rồi thôi", vì bản chất của hệ thống là dữ liệu sự kiện chuỗi cung ứng phải cập nhật gần theo thời gian thực.
Những lỗi thường gặp khi doanh nghiệp tự kết nối
Ba lỗi tôi thấy lặp lại nhiều nhất. Thứ nhất, nhầm giữa cổng truy xuất nguồn gốc cấp tỉnh và cổng quốc gia — một số địa phương có cổng truy xuất riêng, đăng ký ở đó chưa chắc đã đồng nghĩa với việc dữ liệu tự động chảy lên cổng quốc gia, doanh nghiệp cần xác nhận rõ luồng kết nối giữa hai tầng này với Sở KH&CN của mình. Thứ hai, dùng mã sản phẩm tự đặt không theo GS1/TCVN 13274:2020 khiến dữ liệu bị từ chối ngay ở bước kiểm thử sandbox, phải làm lại từ đầu. Thứ ba, đánh giá thấp yêu cầu dữ liệu sự kiện thời gian thực — nhiều doanh nghiệp chỉ chuẩn bị được hồ sơ sản phẩm tĩnh (catalog) mà không có cơ chế ghi nhận sự kiện xuất kho, đóng gói, vận chuyển, nên dù vượt qua vòng thẩm định ban đầu vẫn không duy trì được kết nối 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 đã bắt buộc (hóa chất, tiền chất, thuốc lá) thì không còn nhiều thời gian để cân nhắc — nghĩa vụ đã có hiệu lực từ đầu năm 2026. 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 mở rộng theo từng bộ ngành đang được công bố dần, và việc chuẩn hóa dữ liệu mã hóa 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.
Điều thực tế nhất tôi có thể khuyên: đừ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 của bạn 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ủa bạn có được ghi nhận theo thời gian thực 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 đã kết nối sẵn — chỉ còn là bước kỹ thuật cuối cùng trong một chuỗi việc đã chuẩn bị kỹ từ trước.
