Cho nhà phát triển
API salapp
nối phần mềm của bạn.
Mỗi doanh nghiệp dùng SAL có phần mềm riêng tại tên.salapp.vn, kèm API riêng: thêm, sửa, tìm, xóa bản ghi, gửi tệp, nhận webhook khi dữ liệu đổi. Website hay phần mềm của chính bạn dùng Khóa API; ứng dụng cho nhiều khách dùng thì gắn nút «Kết nối với salapp» (OAuth 2.0).
API có ở mọi gói, kể cả gói Miễn phí. Mỗi phần mềm còn có trang Tài liệu API riêng (Kết nối → Khóa API → Tài liệu API), dựng đúng mục, trường của phần mềm đó, kèm tệp OpenAPI. Cập nhật 17/11/2026.
Bắt đầu
Địa chỉ API của một phần mềm là https://tên.salapp.vn/api/v1 (tên miền riêng của phần mềm cũng dùng được). Gửi khóa ở tiêu đề Authorization.
- Trong phần mềm: Kết nối → Khóa API → Tạo khóa. Chọn quyền: «Chỉ thêm» (website gửi khách mới), «Đọc và thêm», hoặc «Toàn quyền» (thêm, sửa, xóa). Giới hạn được chỉ vài mục, chỉ vài địa chỉ IP, ngày hết hạn; khóa chỉ hiện một lần.
- Gọi thử: danh sách mục và trường của phần mềm (mã mục, mã trường, kiểu, bắt buộc, lựa chọn hợp lệ).
curl https://tencongty.salapp.vn/api/v1/khoi \
-H "Authorization: Bearer sal_KHOA_CUA_BAN"Mã mục (khach_hang, don_hang, lich_hen…) và mã trường (ten, dien_thoai, email…) lấy từ kết quả trên hoặc trang Tài liệu API trong phần mềm. Mỗi lần gọi được ghi ở Kết nối → Khóa API → Nhật ký (7 ngày), không ghi nội dung gửi lên.
Bản ghi
Thêm, sửa, xóa qua API đi đúng đường như làm trong phần mềm: kiểm dữ liệu, tự động hóa, webhook, nhật ký.
| Phương thức | Đường | Việc |
|---|---|---|
GET | /khoi | Các mục và trường của phần mềm |
GET | /khoi/{mục}/truong | Trường của một mục (form động); ?loai=ghi|khop|tim|tep |
POST | /khoi/{mục} | Thêm bản ghi {"du_lieu": {...}}; trùng số điện thoại / email với hồ sơ có sẵn thì tự gộp |
GET | /khoi/{mục} | Danh sách: trang, co (tối đa 200), tim, loc.{trường} (đúng giá trị), sap=moi_tao |
GET | /khoi/{mục}/{id} | Xem một bản ghi |
PATCH | /khoi/{mục}/{id} | Sửa các trường gửi lên, trường khác giữ nguyên |
DELETE | /khoi/{mục}/{id} | Xóa vào Thùng rác, khôi phục được 30 ngày |
POST | /khoi/{mục}/{id}/khoi-phuc | Khôi phục từ Thùng rác |
GET | /khoi/{mục}?sua_tu=0 | Đồng bộ: thay đổi cũ → mới, đọc tiếp bằng ?sau={tiep}; bản ghi đã xóa ở /khoi/{mục}/da-xoa?sau= |
GET | /toi | Kết nối này là gì: phần mềm nào, khóa / ứng dụng nào, quyền gì |
curl -X POST https://tencongty.salapp.vn/api/v1/khoi/khach_hang \
-H "Authorization: Bearer sal_KHOA_CUA_BAN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: don-web-1024" \
-d '{"du_lieu": {"ten": "Nguyễn Văn An", "dien_thoai": "0912345678", "email": "[email protected]"}}'- Tìm đúng giá trị:
loc.dien_thoai=+84912345678khớp cả 0912 345 678; chữ và email không phân biệt hoa thường. - Ngày giờ: ngày dạng
2026-11-20, ngày giờ2026-11-20T09:30(giờ Việt Nam); gửi ISO có múi giờ như2026-11-20T02:30:00Zthì phần mềm tự đổi về giờ Việt Nam. - Gửi lại không làm hai lần: kèm
Idempotency-Keyở POST, PATCH, DELETE; cùng mã trong 24 giờ trả lại đúng kết quả lần đầu.
Thêm, sửa hàng loạt
Một lần gọi thêm, sửa hoặc thêm-hoặc-cập-nhật tới 200 bản ghi; kết quả từng dòng theo đúng thứ tự gửi, dòng lỗi không làm hỏng dòng khác.
curl -X POST https://tencongty.salapp.vn/api/v1/khoi/khach_hang/hang-loat \
-H "Authorization: Bearer sal_KHOA_CUA_BAN" -H "Content-Type: application/json" \
-d '{
"ban_ghi": [
{"ten": "Nguyễn Văn An", "dien_thoai": "0912345678"},
{"ten": "Trần Thị Bình", "dien_thoai": "0987654321", "nguon": "Website"}
],
"khi_trung": "cap_nhat"
}'| Trường | Ý nghĩa |
|---|---|
ban_ghi | Mảng bản ghi (tối đa 200). Phần tử có "id" là sửa đúng bản ghi đó. |
khi_trung | them (mặc định), bo_qua bỏ dòng trùng, cap_nhat thêm hoặc cập nhật — so theo số điện thoại / email. |
khop_theo | So theo một trường khác: mã đơn, SKU, mã khách bên phần mềm của bạn… |
tu_dong | true: từng bản ghi chạy tự động hóa và webhook như thêm / sửa từng cái (tối đa 20 bản ghi mỗi lần). |
Kết quả: {"them", "cap_nhat", "gop", "bo_qua", "so_loi", "ket_qua": [{"vi_tri", "trang_thai", "id", "loi"}]}. Xóa nhiều bản ghi: POST /khoi/{mục}/hang-loat/xoa {"ids": [...]} (tối đa 200, vào Thùng rác). Không có tu_dong thì chạy như Nhập Excel: nhanh, không gửi webhook.
Tệp đính kèm
Gửi hợp đồng, ảnh, hóa đơn… tới 20 MB một tệp, 10 tệp một trường: gửi thẳng nội dung tệp (tên ở tiêu đề X-Ten-Tep) hoặc form multipart phần "tep".
# Tải lên và gắn luôn vào trường tệp của bản ghi
curl -X POST https://tencongty.salapp.vn/api/v1/khoi/khach_hang/bg_MA_BAN_GHI/tep/giay_to \
-H "Authorization: Bearer sal_KHOA_CUA_BAN" -F "[email protected]"
# Tải lên trước, dùng mã tp_… khi thêm / sửa bản ghi
curl -X POST "https://tencongty.salapp.vn/api/v1/tep?ten=hop-dong.pdf" \
-H "Authorization: Bearer sal_KHOA_CUA_BAN" -H "Content-Type: application/pdf" --data-binary @hop-dong.pdfTải tệp về: GET /tep/{mã}. Phần mềm chưa có trường kiểu Tệp thì thêm trước (ví dụ «Hợp đồng» ở mục Khách hàng) — nhờ trợ lý trong phần mềm là xong.
Webhook
Phần mềm báo ngay sang địa chỉ https của bạn khi bản ghi được thêm, sửa, đổi trạng thái, xóa hoặc khôi phục. Đặt trong phần mềm (Kết nối → Webhook ra) hoặc đăng ký bằng API.
| Sự kiện | Khi nào |
|---|---|
tao | Bản ghi mới |
sua | Bản ghi được sửa |
doi_trang_thai | Đổi trạng thái / bước (ưu tiên hơn sua) |
xoa | Vào Thùng rác — kèm khoi_phuc_truoc, và gop_vao khi bị gộp vào hồ sơ khác |
khoi_phuc | Được khôi phục |
# Đăng ký (Zapier, Make… làm khi bật Zap / kịch bản)
POST /api/v1/webhook {"url": "https://hooks.example.com/abc", "khoi": "khach_hang", "su_kien": ["tao", "xoa"]}
GET /api/v1/webhook
DELETE /api/v1/webhook/{id}
# Thân phần mềm gửi tới địa chỉ của bạn
{"su_kien": "tao", "khoi": "khach_hang", "luc": "2026-11-17T08:30:00.000Z", "ma_gui": "gui_…",
"ban_ghi": {"id": "bg_…", "ten": "Nguyễn Văn An", "dien_thoai": "0912345678"}}- Chữ ký: tiêu đề
X-SAL-Chu-Ky-2: t=<giây>,v1=<hex>với v1 = HMAC-SHA256 của chuỗi "t.thân" bằng khóa ký của webhook (whsec_…). So khớp và bỏ thông báo quá 5 phút để chặn gửi lại bản cũ. - Gửi chắc chắn: nơi nhận lỗi hoặc chậm thì tự gửi lại sau 1 phút, 5 phút, 30 phút, 2 giờ, 6 giờ, 12 giờ, giữ nguyên
X-SAL-Ma-Guiđể bạn bỏ trùng; lỗi liên tục 3 ngày thì webhook tự tạm dừng và báo chủ. - Thân không có trường nhạy cảm. Webhook đăng ký qua API: tối đa 20 cho mỗi khóa / ứng dụng, 50 cho mỗi phần mềm; thu hồi khóa hay ngắt ứng dụng là webhook của nó tự gỡ.
Kết nối với salapp (OAuth 2.0)
Cho phần mềm nhiều khách dùng: khách bấm «Kết nối với salapp», gõ địa chỉ phần mềm của họ, đăng nhập, xem rõ bạn xin quyền gì rồi bấm Đồng ý — không phải chép khóa.
- Trong phần mềm salapp của bạn: Kết nối → Nhà phát triển → Tạo ứng dụng (tên, trang web, địa chỉ chuyển về). Nhận
client_idvà khóa bí mật (hiện một lần). Mới tạo thì chỉ kết nối thử được với chính phần mềm của bạn; bấm «Gửi SAL xác minh» để mọi doanh nghiệp salapp kết nối được. - Đưa khách tới trang xin quyền (mã cấp quyền + PKCE S256; ứng dụng chạy trên điện thoại, trình duyệt thì bắt buộc PKCE, không dùng khóa bí mật).
- Đổi mã lấy mã truy cập; gọi API tại
api_basetrả về, như dùng Khóa API.
https://salapp.vn/oauth/authorize?response_type=code&client_id=ud_…
&redirect_uri=https%3A%2F%2Fungdung.vn%2Fcallback&scope=doc%20them%20webhook&state=…
&code_challenge=…&code_challenge_method=S256
curl -X POST https://salapp.vn/oauth/token -u "ud_…:salcs_…" \
-d grant_type=authorization_code -d code=… -d redirect_uri=https://ungdung.vn/callback -d code_verifier=…
{"access_token": "tencongty.a_…", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "tencongty.r_…",
"scope": "doc them webhook", "api_base": "https://tencongty.salapp.vn/api/v1", "phan_mem": {"ma": "tencongty", "ten": "…"}}| Phạm vi | Được làm |
|---|---|
doc | Xem bản ghi (không bao giờ thấy trường nhạy cảm) |
them | Thêm bản ghi, tải tệp lên |
sua | Sửa bản ghi, gắn tệp |
xoa | Xóa vào Thùng rác |
webhook | Đăng ký nhận thông báo ngay (cần kèm doc) |
- Mã truy cập sống 1 giờ; làm mới bằng
grant_type=refresh_token(mã làm mới giữ nguyên tới khi khách ngắt). Thu hồi:POST https://salapp.vn/oauth/revoke. Mô tả máy chủ:https://salapp.vn/.well-known/oauth-authorization-server. - Biết sẵn phần mềm của khách thì thêm
&phan_mem=tencongtyđể bỏ qua bước gõ địa chỉ. - Khách thấy và ngắt ứng dụng ở Kết nối → Ứng dụng đã kết nối (quyền, lần dùng gần nhất, nhật ký); người đồng ý thôi là chủ / quản lý thì kết nối tự ngừng.
Zapier và Make
Ứng dụng salapp trên Zapier và Make đã làm xong, đăng nhập bằng «Kết nối với salapp». Đang làm hồ sơ để Zapier, Make xét duyệt hiện công khai.
| Zapier | Make | |
|---|---|---|
| Báo ngay | New Record, Updated Record, Deleted Record | Watch Records (thêm, sửa, đổi trạng thái, xóa, khôi phục) |
| Việc | Create Record, Update Record, Create or Update Record, Upload File to Record, Delete Record | Create / Update / Create or Update / Get / Delete a Record, Upload a File to a Record, Make an API Call |
| Tìm | Find Record (tìm hoặc tạo) | Search Records |
Trong lúc chờ duyệt: mở Kết nối → Zapier (hoặc Make) trong phần mềm — có link mời thì bấm để thêm salapp vào tài khoản Zapier / Make của bạn và dùng ngay; hoặc nối bằng Webhook ra và Khóa API như trên. Bật Zap / kịch bản là ứng dụng tự đăng ký webhook, tắt là tự gỡ.
Lỗi và giới hạn
Lỗi luôn là JSON: {"loi": {"ma", "thongBao", "chiTiet"}}; chiTiet.truong chỉ ra từng trường sai.
| Mã HTTP | Mã lỗi thường gặp |
|---|---|
| 400 | json_hong thân không phải JSON |
| 401 | khoa_sai, khoa_het_han, token_het_han (OAuth: làm mới mã truy cập) |
| 403 | khong_du_quyen, khong_duoc_dung_muc, ip_khong_duoc_phep |
| 404 | khong_tim_thay, khong_co_khoi |
| 409 / 422 | Idempotency-Key đang chạy / khác thân; du_lieu_khong_hop_le, khi_trung_sai, khop_theo_sai |
| 413 | qua_lon (thân quá 1 MB), qua_nhieu_ban_ghi |
| 429 | qua_nhieu_yeu_cau — chờ đúng số giây ở Retry-After |
Giới hạn: 600 yêu cầu mỗi 15 phút cho mỗi IP (tiêu đề X-RateLimit-Limit, X-RateLimit-Remaining); thân tối đa 1 MB; danh sách tối đa 200 bản ghi một trang. Cần giúp: [email protected] hoặc Zalo OA SAL - AI.