Home / Integrations / API

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.

  1. 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.
  2. 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.

MethodPathAction
GET/khoiRecord types and fields of the software
GET/khoi/{type}/truongFields 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-phucRestore from the Trash
GET/khoi/{type}?sua_tu=0Sync: changes oldest → newest, continue with ?sau={tiep}; deleted records at /khoi/{type}/da-xoa?sau=
GET/toiWhat 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=+84912345678 also matches 0912 345 678; text and emails ignore upper / lower case.
  • Dates: dates as 2026-11-20, date-times as 2026-11-20T09:30 (Vietnam time); ISO values with a time zone such as 2026-11-20T02:30:00Z are converted to Vietnam time.
  • Safe retries: add Idempotency-Key to 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"
  }'
FieldMeaning
ban_ghiArray of records (up to 200). An item with "id" updates that record.
khi_trungthem (default) always add, bo_qua skip duplicates, cap_nhat create or update — matched by phone / email.
khop_theoMatch on another field instead: order code, SKU, the customer ID in your software…
tu_dongtrue: 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.pdf

Download: 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.

EventWhen
taoNew record
suaRecord updated
doi_trang_thaiStatus / stage changed (takes priority over sua)
xoaMoved to the Trash — with khoi_phuc_truoc (restorable until), and gop_vao when merged into another contact
khoi_phucRestored
# 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-Gui so 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.

  1. 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_id and 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.
  2. 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).
  3. 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": "…"}}
ScopeAllows
docRead records (sensitive fields are never visible)
themCreate records, upload files
suaUpdate records, attach files
xoaDelete to the Trash
webhookRegister 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=yourcompany to 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.

ZapierMake
InstantNew Record, Updated Record, Deleted RecordWatch Records (created, updated, status changed, deleted, restored)
ActionCreate 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
SearchFind 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 statusCommon error codes
400json_hong body is not JSON
401khoa_sai, khoa_het_han, token_het_han (OAuth: refresh the access token)
403khong_du_quyen, khong_duoc_dung_muc, ip_khong_duoc_phep
404khong_tim_thay, khong_co_khoi
409 / 422Idempotency-Key still running / different body; du_lieu_khong_hop_le, khi_trung_sai, khop_theo_sai
413qua_lon (body over 1 MB), qua_nhieu_ban_ghi
429qua_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.