Tài liệu API APIBox

APIBox gồm nhiều REST endpoint độc lập, dùng chung base URL, cách xác thực, hạn mức và định dạng lỗi.

Base URL

https://apibox.io.vn/v1/<endpoint>

GET /v1 liệt kê mọi endpoint (không cần key).

Xác thực

Tạo tài khoản miễn phí trong bảng điều khiển để nhận API key (bắt đầu bằng abx_). Gửi key trong mỗi request, tốt nhất qua header:

Authorization: Bearer abx_your_key
# hoặc
X-API-Key: abx_your_key

Với URL nhúng thẳng vào HTML (mã QR, mã vạch, ảnh placeholder) bạn có thể dùng ?api_key=abx_your_key. Key đặt trong trang web công khai có thể bị người xem nhìn thấy: hãy dùng một key riêng và thu hồi khi bị lộ.

Cách gửi tham số

• GET: query string, ví dụ /v1/uuid?type=v7&count=5.
• POST JSON: Content-Type: application/json với body là object. Tham số trên query string được gộp với body.
• POST form / multipart: các trường và tệp (file) cho endpoint xử lý ảnh và PDF.
• Body thô: một số endpoint nhận trực tiếp nội dung, ví dụ text/html cho HTML sang Markdown, text/csv cho CSV sang JSON, hoặc dữ liệu nhị phân của ảnh/PDF.

Kích thước body mặc định tối đa 1 MB (5–6 MB cho các API chuyển đổi văn bản). Endpoint xử lý tệp: 5 MB với gói Free, 20 MB với Starter, 50 MB với Pro. Thêm ?pretty=true để nhận JSON có thụt dòng.

Hạn mức và giới hạn tốc độ

Mỗi response thành công đều kèm thông tin hạn mức tháng:

X-Quota-Limit: 50000
X-Quota-Remaining: 48211
X-Quota-Reset: 1798761600   (unix time, ngày 1 tháng sau, giờ UTC)
X-Request-Id: 7Hq2...

Hạn mức được làm mới vào ngày 1 mỗi tháng (UTC). Mỗi lần gọi tính là một request, với mọi endpoint.

Mã lỗi

Lỗi được trả về bằng mã HTTP và body JSON:

{ "error": { "code": "missing_parameter", "message": "Parameter \"url\" is required" } }

Tải URL

Các endpoint nhận url sẽ tải trang với user agent APIBoxBot, theo tối đa 8 lần chuyển hướng, hết thời gian chờ sau 10–20 giây và từ chối địa chỉ nội bộ/riêng tư.

Dữ liệu tham chiếu và dữ liệu nhạy cảm

Các endpoint dựa trên dữ liệu tham chiếu luôn cho biết phiên bản đang dùng. Tỉnh thành & phường xã Việt Nam trả về version, decree (nghị quyết mới nhất đã áp dụng) và updated trong mọi phản hồi; dữ liệu theo danh mục chính thức sau sắp xếp ngày 1/7/2025 và được dựng lại khi có nghị quyết mới. Kết quả WHOIS được cache 1 giờ, còn lịch âm được tính theo múi giờ Việt Nam (UTC+7).

Số định danh và mã số thuế gửi tới Kiểm tra CCCD & mã số thuế chỉ được kiểm tra trong bộ nhớ, không lưu và không ghi log. Hãy gửi bằng POST để số không nằm trong URL.

Các quy định thay đổi theo văn bản pháp luật được lưu kèm ngày hiệu lực. Tính lương Gross ↔ Net và Ngày lễ & ngày làm việc nhận kỳ tính là tham số và trả về căn cứ pháp lý đã áp dụng; lịch nghỉ lễ được đánh dấu official khi đã có thông báo chính thức và estimated (tính theo Bộ luật Lao động) trước đó. Tỷ giá lấy từ Vietcombank (bảng hôm nay cache 15 phút, các ngày cũ 7 ngày) và tỷ giá trung bình thị trường trong ngày cho các cặp khác; chỉ mang tính tham khảo.

Dữ liệu giả không chứa người thật: email dùng tên miền example và CCCD / mã số thuế sinh ra chỉ đúng cấu trúc. Kiểm tra SEO và Kiểm tra SPF / DKIM / DMARC đọc trực tiếp trang công khai và bản ghi DNS (cache 10 và 5 phút), tương tự Kiểm tra header bảo mật, Kiểm tra sitemap và RSS sang JSON (10 phút).

Chuẩn hoá địa chỉ chuyển địa chỉ trước 2025 bằng cùng dữ liệu với API tỉnh thành. Secret TOTP và văn bản gửi tới Lọc từ ngữ thô tục chỉ được xử lý trong bộ nhớ, không bao giờ cache; hãy tự lưu secret TOTP ở dạng mã hoá. Mật khẩu gửi tới Kiểm tra mật khẩu và số thẻ gửi tới Kiểm tra số thẻ không bao giờ được lưu, ghi log hay cache; chỉ 5 ký tự đầu của mã băm rời máy chủ để kiểm tra rò rỉ.

Các bộ dữ liệu lấy từ nguồn khác (tỉnh thành, phường xã, mã ngành VSIC, mã SWIFT / BIC, tiền tố mã vạch GS1, tên miền email tạm, từ điển tách từ) được một tác vụ tự động đọc lại hằng tuần, có kiểm tra trước khi thay thế dữ liệu. Dự báo thời tiết lấy từ MET Norway (CC BY 4.0, cần giữ dòng ghi nguồn) và được cache theo vị trí đến khi nguồn cập nhật.

Secret gửi tới Kiểm tra chữ ký webhook và tệp gửi tới Đọc mã QR hay Làm sạch CSV chỉ được xử lý trong bộ nhớ. PDF từ Tạo PDF báo giá, phiếu thu là chứng từ thương mại, không phải hoá đơn điện tử theo Nghị định 123/2020/NĐ-CP. Ảnh gửi tới các API xử lý ảnh tối đa 25 megapixel; Kiểm tra liên kết hỏng chỉ kiểm tra một trang mỗi lần, số liên kết giới hạn theo gói. Tóm tắt và nhận diện ngôn ngữ chạy không dùng mô hình AI.

Mã HS & biểu thuế lấy từ file biểu thuế do Trung tâm WTO và Hội nhập – VCCI công bố (dựng lại hằng tuần khi có thay đổi, nghị định ban hành sau được bổ sung thủ công); dữ liệu chỉ để tra cứu, hãy đối chiếu văn bản gốc trước khi khai báo hải quan. Xem ngày tốt xấu áp dụng quy tắc lịch vạn niên truyền thống, chỉ mang tính tham khảo văn hoá. Kiểm tra chính tả và thêm dấu tiếng Việt dùng từ điển, không dùng AI. Tệp gửi tới công cụ Excel, Word và PDF chỉ được xử lý trong bộ nhớ, không lưu lại. Tạo sitemap crawl một website mỗi lần gọi, tuân thủ robots.txt và dừng ở giới hạn số trang của gói. Giám sát uptime gắn với tài khoản của bạn: URL được kiểm tra mỗi 5–15 phút, lịch sử sự cố giữ 90 ngày, cảnh báo chỉ gửi tới email đã xác nhận của bạn hoặc webhook của bạn.

Các công cụ tính theo pháp luật Việt Nam (tiền điện, thuế hộ kinh doanh, lệ phí trước bạ, lịch thuế, lương tối thiểu vùng, trợ cấp BHXH, tuổi nghỉ hưu) dùng bảng số liệu nhập từ văn bản đang có hiệu lực, luôn trả về căn cứ pháp lý và ngày rà soát, không lưu dữ liệu bạn gửi, và chỉ mang tính ước tính, không thay thế tư vấn pháp lý hay thuế. Các API đọc giấy tờ Việt Nam (XML hóa đơn điện tử, QR căn cước, mã thẻ BHYT) chỉ xử lý dữ liệu bạn gửi: không tra cứu cổng nhà nước, không lưu, không ghi log, chữ ký số chỉ được liệt kê chứ không xác thực, các bảng pháp lý (ký hiệu hóa đơn theo TT 91/2026/TT-BTC, mã đối tượng BHYT theo Công văn 1804/BHXH-QLT ngày 04/08/2025) được rà soát 6 tháng một lần; dự đoán giới tính theo tên dùng danh sách duyet/vietnamese-namedb (MIT) cập nhật hằng tuần. Các API tra cứu Việt Nam (tài khoản kế toán, mức phạt giao thông, mã bưu chính, danh mục dùng chung, điểm xét tuyển, phí sàn TMĐT) dùng bảng số hoá thủ công từ văn bản chính thức và trang biểu phí công khai của các sàn, mọi kết quả đều ghi căn cứ pháp lý và ngày rà soát; kết quả chỉ để tham khảo, không phải tư vấn pháp lý hay thuế, và dữ liệu gửi lên không được lưu. Các công cụ XML, nhận diện loại file, JSON sang kiểu dữ liệu và tính biểu thức chạy hoàn toàn trong bộ nhớ, không lưu dữ liệu (nhận diện file chỉ tải tối đa 64 KB đầu của URL); quy tắc ngày lễ lấy từ dự án mở date-holidays (CC BY-SA 4.0, mọi phản hồi đều kèm ghi công), dữ liệu quốc gia từ countries-list, i18n-iso-countries và cơ sở dữ liệu múi giờ IANA, cập nhật hằng tuần. vn-geo dùng ranh giới xã đã đơn giản hoá từ bộ dữ liệu mở của ThangLeQuoc (MIT, nguồn sapnhap.bando.com.vn), kết quả gần đúng ở sát ranh giới; pdf-sign-verify kiểm tra toàn vẹn, người ký và chuỗi chứng thư theo danh sách CA do NEAC và Ban Cơ yếu Chính phủ công bố, không kiểm tra thu hồi; file PDF và ảnh tải lên (barcode-read, pdf-sign-verify) chỉ xử lý trong bộ nhớ, không lưu lại. Các bảng số liệu pháp lý và biểu phí nhập tay đều ghi ngày rà soát gần nhất và được kiểm tra lại theo lịch cố định.

Các công cụ tính thuế và tiền lương (VAT 8%/10%, quyết toán TNCN, thuế TNDN, thuế nhà thầu, tiền chậm nộp, khấu hao, mã chương tiểu mục, làm thêm giờ, phép năm) dùng bảng quy định nhập tay có ghi rõ văn bản và ngày hiệu lực; dữ liệu gửi lên chỉ xử lý trong bộ nhớ, không lưu lại, và kết quả chỉ để ước tính, không thay thế tư vấn thuế. Các API phí, tọa độ, điểm học sinh và mã ngành tính từ bảng pháp lý tích hợp sẵn (mỗi kết quả ghi văn bản và ngày rà soát); dữ liệu gửi lên không được lưu, kết quả chỉ để ước tính, không thay tư vấn pháp lý hay đo đạc. Các công cụ thương mại và ngôn ngữ tiếng Việt (biến động số dư, sao kê, đơn hàng, che dữ liệu cá nhân, teencode, từ ngữ quảng cáo, sắp xếp, mã vận đơn) xử lý trong bộ nhớ và không lưu văn bản hay file bạn gửi; vn-hanviet dùng dữ liệu Unihan của Unicode, Wiktionary và CC-CEDICT (mỗi kết quả đều ghi nguồn), còn vn-ad-check / vn-pii-redact là công cụ hỗ trợ phát hiện rủi ro, không phải tư vấn pháp lý. Các công cụ đề thi và tài liệu (đọc đề, trộn đề, mẫu Word, form PDF, e-mail, bảng công) xử lý file trong bộ nhớ và không lưu lại; danh mục ICD-10 là phần tiếng Việt của Thông tư 06/2026/TT-BYT, cập nhật hằng tuần, còn quay số có thể kiểm chứng bằng mã băm seed công bố trước. Các công cụ JSON, OpenAPI, so khớp mờ, CIDR, tên miền và địa lý chỉ tính toán trong bộ nhớ, không lưu dữ liệu của bạn; hãng sản xuất MAC (danh sách IEEE), dải IP cloud / Tor / crawler (file do chính nhà cung cấp công bố, cập nhật hằng ngày) và UN/LOCODE (UNECE, CC BY 4.0) lấy từ nguồn công khai chính thức, và ip-intel không phát hiện được VPN thương mại hay proxy dân cư. Các công cụ ảnh (tối ưu / làm sạch / chuyển SVG, bảng màu và BlurHash / ThumbHash, bộ favicon, công thức LaTeX và ảnh code) chạy hoàn toàn trong Worker bằng bộ vẽ JavaScript và phông OFL nhúng sẵn; file được xử lý trong bộ nhớ, không lưu lại, ảnh xuất ra tối đa 5 megapixel. ssl-check và x509 chỉ xử lý trong bộ nhớ (không lưu chứng chỉ, khoá); website đứng sau Cloudflare được kiểm tra qua nhật ký Certificate Transparency kèm một request HTTPS thực tế, và kết quả ghi rõ điều đó. Dữ liệu form và tài liệu JSON được lưu trong cơ sở dữ liệu cho tài khoản của bạn, theo giới hạn của gói, cho tới khi bạn xoá (dữ liệu form: giữ 100 / 2.000 / 10.000 bản mới nhất mỗi form; tài liệu JSON: tới khi xoá hoặc hết TTL). tech-detect chỉ đọc một trang công khai, không chạy JavaScript; vn-streets dùng dữ liệu OpenStreetMap (© OpenStreetMap contributors, ODbL), dựng lại hằng tháng.

CORS

Mọi endpoint /v1 đều trả về Access-Control-Allow-Origin: * nên gọi được từ trình duyệt. Đừng để lộ key có hạn mức lớn trong code front-end công khai.

Tất cả API