/v1/apps/{app_id}Cập nhật ứng dụng
Sửa một phần hồ sơ ứng dụng: tên, mô tả, mã số thuế, tên đơn vị hoặc trạng thái. Trường không gửi giữ nguyên.
Giới thiệu
API này sửa hồ sơ ứng dụng: tên, mô tả, mã số thuế, tên đơn vị và trạng thái chạy hoặc tạm dừng. Hạn mức, API key, webhook và danh sách IP không đổi qua endpoint này.
Sandbox và Live là hai hệ thống tách biệt. Gọi trên Live sẽ sửa hồ sơ chính thức, và console hiển thị đúng hồ sơ này. Gọi trên Sandbox chỉ sửa bản dùng để thử. Lần tới khi bạn sửa ứng dụng trên console, bản Sandbox sẽ bị ghi đè theo hồ sơ chính thức.
Chỉ gửi những trường cần sửa. Trường bỏ qua giữ giá trị hiện tại. Xác thực bằng API key của ứng dụng đó, không dùng token hoá đơn và không trừ hạn mức phát hành.
Endpoint
Gửi PATCH tới cùng đường dẫn với API đọc thông tin ứng dụng. Host phải cùng môi trường với API key. Sandbox: https://sandbox.api.hddt.dev. Live: https://api.hddt.dev.
Body là JSON. Cần ít nhất một trường. API key phải thuộc đúng app_id trên đường dẫn.
Tạm dừng
Header
api_keystringBắt buộcAPI key của ứng dụng.
Content-TypestringBắt buộcapplication/json.
Param
Nằm trên đường dẫn.
app_idstringBắt buộcĐịnh danh ứng dụng (UUID) sao chép từ trang quản trị. Ví dụ f47ac10b-58cc-4372-a567-0e02b2c3d479.
Body
Mọi trường đều tuỳ chọn. Gửi ít nhất một trường.
namestringTuỳ chọnTên ứng dụng sau khi bỏ khoảng trắng hai đầu. Từ 3 đến 50 ký tự.
descriptionstringTuỳ chọnMô tả ngắn, tối đa 160 ký tự. Chuỗi rỗng để xoá mô tả.
tax_codestringTuỳ chọnMã số thuế 10 số, hoặc chi nhánh dạng 0302712571-999. 13 số liền cũng được chấp nhận và được lưu thành dạng có dấu gạch. Chuỗi rỗng hoặc null để xoá. Khi Live đã bật, không được để trống.
company_namestringTuỳ chọnTên đơn vị phát hành. Chuỗi rỗng hoặc null để xoá. Khi Live đã bật, không được để trống.
statusstringTuỳ chọnactive hoặc paused.
Ví dụ
Đổi tên đơn vị và mã số thuế, giữ nguyên các trường khác.
curl -X PATCH https://sandbox.api.hddt.dev/v1/apps/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
-H "api_key: $HDDT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"tax_code": "0312345678",
"company_name": "Công ty TNHH Thương mại ABC"
}'Phản hồi
Khi hợp lệ, API trả 200 OK với cùng dạng object app như API thông tin ứng dụng. Các trường vừa gửi đã được ghi; hạn mức vẫn là sổ của môi trường gắn với API key.
{
"id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"object": "app",
"name": "Shop ABC",
"description": "Website bán hàng, xuất hoá đơn tự động khi đơn hàng hoàn tất.",
"status": "active",
"tax_code": "0312345678",
"company_name": "Công ty TNHH Thương mại ABC",
"environment": "sandbox",
"base_url": "https://sandbox.api.hddt.dev/v1",
"rate_limit": 30,
"quota": {
"invoices_used": 342,
"invoices_remaining": 658
},
"created_at": "2026-03-12T09:00:00+07:00"
}Mã lỗi
Các trường hợp thường gặp khi cập nhật ứng dụng:
401 unauthorized—Tuỳ chọnThiếu header api_key, API key sai hoặc đã bị thu hồi.
403 forbidden—Tuỳ chọnAPI key không thuộc app_id này, hoặc gửi key của môi trường khác (key hddt_live_ tới host Sandbox, key hddt_test_ tới host Live).
404 not_found—Tuỳ chọnKhông có ứng dụng nào khớp app_id.
422 validation_error—Tuỳ chọnBody rỗng, app_id không phải UUID, tên ngoài 3–50 ký tự, mô tả dài hơn 160 ký tự, mã số thuế sai định dạng, status lạ, hoặc xoá mã số thuế / tên đơn vị khi Live đã bật.