For developers
salapp API
connect your software.
Every business on SAL has its own software at name.salapp.vn, with its own API: create, update, find and delete records, upload files, and get webhooks when data changes. Your own website or software uses an API key; apps used by many businesses add a «Connect with salapp» button (OAuth 2.0).
The API is included in every plan, including the Free plan. Each software also has its own API reference page (Kết nối → Khóa API → Tài liệu API) built from its own record types and fields, with an OpenAPI file. Updated 17/11/2026.
Get started
The API address of a software is https://name.salapp.vn/api/v1 (the software's own domain works too). Send the key in the Authorization header.
- In the software: Kết nối → Khóa API → Tạo khóa (Integrations → API keys → Create key). Pick a scope: "add only" (a website sending new leads), "read and add", or "full access" (add, update, delete). You can limit a key to some record types, some IP addresses and an expiry date; the key is shown once.
- Try it: the record types and fields of the software (type codes, field codes, kinds, required, allowed choices).
curl https://tencongty.salapp.vn/api/v1/khoi \
-H "Authorization: Bearer sal_KHOA_CUA_BAN"Record type codes (khach_hang, don_hang, lich_hen…) and field codes (ten, dien_thoai, email…) come from the result above or from the API reference page inside the software. Every call is logged under Kết nối → Khóa API → Nhật ký (7 days); request bodies are not stored.
Records
Creating, updating and deleting through the API goes through the same path as in the software: validation, automations, webhooks, activity log.
| Method | Path | Action |
|---|---|---|
GET | /khoi | Record types and fields of the software |
GET | /khoi/{type}/truong | Fields of a record type (dynamic forms); ?loai=ghi|khop|tim|tep |
POST | /khoi/{type} | Create a record {"du_lieu": {...}}; a phone / email matching an existing contact is merged automatically |
GET | /khoi/{type} | List: trang (page), co (size, up to 200), tim (search), loc.{field} (exact value), sap=moi_tao (newest first) |
GET | /khoi/{type}/{id} | Get one record |
PATCH | /khoi/{type}/{id} | Update the fields you send; other fields stay unchanged |
DELETE | /khoi/{type}/{id} | Move to the Trash, restorable for 30 days |
POST | /khoi/{type}/{id}/khoi-phuc | Restore from the Trash |
GET | /khoi/{type}?sua_tu=0 | Sync: changes oldest → newest, continue with ?sau={tiep}; deleted records at /khoi/{type}/da-xoa?sau= |
GET | /toi | What this connection is: which software, which key / app, which permissions |
curl -X POST https://yourcompany.salapp.vn/api/v1/khoi/khach_hang \
-H "Authorization: Bearer sal_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: web-order-1024" \
-d '{"du_lieu": {"ten": "Nguyễn Văn An", "dien_thoai": "0912345678", "email": "[email protected]"}}'- Exact match:
loc.dien_thoai=+84912345678also matches 0912 345 678; text and emails ignore upper / lower case. - Dates: dates as
2026-11-20, date-times as2026-11-20T09:30(Vietnam time); ISO values with a time zone such as2026-11-20T02:30:00Zare converted to Vietnam time. - Safe retries: add
Idempotency-Keyto POST, PATCH, DELETE; the same key within 24 hours returns the first result again.
Bulk create and update
One call creates, updates or upserts up to 200 records; each row gets its own result in the order sent, and a failing row does not affect the others.
curl -X POST https://yourcompany.salapp.vn/api/v1/khoi/khach_hang/hang-loat \
-H "Authorization: Bearer sal_YOUR_KEY" -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"
}'| Field | Meaning |
|---|---|
ban_ghi | Array of records (up to 200). An item with "id" updates that record. |
khi_trung | them (default) always add, bo_qua skip duplicates, cap_nhat create or update — matched by phone / email. |
khop_theo | Match on another field instead: order code, SKU, the customer ID in your software… |
tu_dong | true: each record runs automations and webhooks like a single create / update (up to 20 records per call). |
Result: {"them", "cap_nhat", "gop", "bo_qua", "so_loi", "ket_qua": [{"vi_tri", "trang_thai", "id", "loi"}]}. Delete many: POST /khoi/{type}/hang-loat/xoa {"ids": [...]} (up to 200, to the Trash). Without tu_dong it runs like an Excel import: fast, no webhooks.
File attachments
Send contracts, photos, invoices… up to 20 MB per file, 10 files per field: send the raw file (name in the X-Ten-Tep header) or a multipart form with a "tep" part.
# Upload and attach to a file field of a record
curl -X POST https://yourcompany.salapp.vn/api/v1/khoi/khach_hang/bg_RECORD_ID/tep/giay_to \
-H "Authorization: Bearer sal_YOUR_KEY" -F "[email protected]"
# Upload first, then use the tp_… ID when creating / updating a record
curl -X POST "https://yourcompany.salapp.vn/api/v1/tep?ten=contract.pdf" \
-H "Authorization: Bearer sal_YOUR_KEY" -H "Content-Type: application/pdf" --data-binary @contract.pdfDownload: GET /tep/{id}. If the software has no File field yet, add one first (for example "Contract" on Customers) — just ask the assistant inside the software.
Webhook
The software notifies your https address right away when a record is created, updated, changes status, is deleted or restored. Set it up in the software (Kết nối → Webhook ra) or register through the API.
| Event | When |
|---|---|
tao | New record |
sua | Record updated |
doi_trang_thai | Status / stage changed (takes priority over sua) |
xoa | Moved to the Trash — with khoi_phuc_truoc (restorable until), and gop_vao when merged into another contact |
khoi_phuc | Restored |
# Register (Zapier, Make… do this when a Zap / scenario is turned on)
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}
# Body sent to your address
{"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"}}- Signature: header
X-SAL-Chu-Ky-2: t=<seconds>,v1=<hex>where v1 = HMAC-SHA256 of "t.body" with the webhook signing key (whsec_…). Compare it and drop messages older than 5 minutes to block replays. - Reliable delivery: if your endpoint fails or is slow, it retries after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 12 hours, keeping the same
X-SAL-Ma-Guiso you can de-duplicate; after 3 days of continuous errors the webhook pauses itself and notifies the owner. - Bodies never include sensitive fields. Webhooks registered through the API: up to 20 per key / app and 50 per software; revoking a key or disconnecting an app removes its webhooks.
Connect with salapp (OAuth 2.0)
For software used by many businesses: the customer clicks «Connect with salapp», types their software address, signs in, sees exactly what you ask for and clicks Allow — no keys to copy.
- In your own salapp: Kết nối → Nhà phát triển → Tạo ứng dụng (Integrations → Developer → Create app: name, website, redirect URIs). You get a
client_idand a client secret (shown once). A new app can only connect to your own software; click «Gửi SAL xác minh» (ask SAL to verify) so every salapp business can connect. - Send the customer to the authorization page (authorization code + PKCE S256; apps running on phones or in the browser must use PKCE and no client secret).
- Exchange the code for an access token; call the API at the returned
api_base, just like with an API key.
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": "…"}}| Scope | Allows |
|---|---|
doc | Read records (sensitive fields are never visible) |
them | Create records, upload files |
sua | Update records, attach files |
xoa | Delete to the Trash |
webhook | Register instant notifications (requires doc) |
- Access tokens live 1 hour; refresh with
grant_type=refresh_token(the refresh token stays valid until the customer disconnects). Revoke:POST https://salapp.vn/oauth/revoke. Server metadata:https://salapp.vn/.well-known/oauth-authorization-server. - If you already know the customer's software, add
&phan_mem=yourcompanyto skip typing the address. - Customers see and disconnect apps under Kết nối → Ứng dụng đã kết nối (connected apps: permissions, last use, log); if the person who allowed it is no longer an owner / manager, the connection stops by itself.
Zapier and Make
The salapp apps for Zapier and Make are built and sign in with «Connect with salapp». We are preparing the submissions for Zapier and Make to review and list them publicly.
| Zapier | Make | |
|---|---|---|
| Instant | New Record, Updated Record, Deleted Record | Watch Records (created, updated, status changed, deleted, restored) |
| Action | 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 |
| Search | Find Record (find or create) | Search Records |
While the review is pending: open Kết nối → Zapier (or Make) in the software — if there is an invite link, click it to add salapp to your Zapier / Make account and use it right away; or connect with outgoing webhooks and an API key as above. Turning a Zap / scenario on registers its webhook automatically; turning it off removes it.
Errors and limits
Errors are always JSON: {"loi": {"ma", "thongBao", "chiTiet"}}; chiTiet.truong points to each invalid field.
| HTTP status | Common error codes |
|---|---|
| 400 | json_hong body is not JSON |
| 401 | khoa_sai, khoa_het_han, token_het_han (OAuth: refresh the access token) |
| 403 | khong_du_quyen, khong_duoc_dung_muc, ip_khong_duoc_phep |
| 404 | khong_tim_thay, khong_co_khoi |
| 409 / 422 | Idempotency-Key still running / different body; du_lieu_khong_hop_le, khi_trung_sai, khop_theo_sai |
| 413 | qua_lon (body over 1 MB), qua_nhieu_ban_ghi |
| 429 | qua_nhieu_yeu_cau — wait the number of seconds in Retry-After |
Limits: 600 requests per 15 minutes per IP (headers X-RateLimit-Limit, X-RateLimit-Remaining); body up to 1 MB; lists up to 200 records per page. Need help: [email protected] or the SAL - AI Zalo OA.