Trang chủ / Kết nối / API

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.

  1. 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.
  2. 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ĐườngViệc
GET/khoiCác mục và trường của phần mềm
GET/khoi/{mục}/truongTrườ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-phucKhô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/toiKế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=+84912345678 khớ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:00Z thì 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_ghiMảng bản ghi (tối đa 200). Phần tử có "id" là sửa đúng bản ghi đó.
khi_trungthem (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_theoSo theo một trường khác: mã đơn, SKU, mã khách bên phần mềm của bạn…
tu_dongtrue: 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.pdf

Tả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ệnKhi nào
taoBản ghi mới
suaBản ghi được sửa
doi_trang_thaiĐổi trạng thái / bước (ưu tiên hơn sua)
xoaVà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.

  1. 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_id và 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.
  2. Đư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).
  3. Đổi mã lấy mã truy cập; gọi API tại api_base trả 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
docXem bản ghi (không bao giờ thấy trường nhạy cảm)
themThêm bản ghi, tải tệp lên
suaSửa bản ghi, gắn tệp
xoaXó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.

ZapierMake
Báo ngayNew Record, Updated Record, Deleted RecordWatch Records (thêm, sửa, đổi trạng thái, xóa, khôi phục)
ViệcCreate Record, Update Record, Create or Update Record, Upload File to Record, Delete RecordCreate / Update / Create or Update / Get / Delete a Record, Upload a File to a Record, Make an API Call
TìmFind 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ã HTTPMã lỗi thường gặp
400json_hong thân không phải JSON
401khoa_sai, khoa_het_han, token_het_han (OAuth: làm mới mã truy cập)
403khong_du_quyen, khong_duoc_dung_muc, ip_khong_duoc_phep
404khong_tim_thay, khong_co_khoi
409 / 422Idempotency-Key đang chạy / khác thân; du_lieu_khong_hop_le, khi_trung_sai, khop_theo_sai
413qua_lon (thân quá 1 MB), qua_nhieu_ban_ghi
429qua_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.