API Kết nối ISale

External API cho phép hệ thống bên thứ ba (ERP, website, POS, chatbot…) đồng bộ dữ liệu với iSale qua API key, không dùng OAuth/Bearer nội bộ.

• Namespace: /ext/v1/* — tách khỏi API app (/data/*, Bearer token).
• Mỗi mã kết nối gắn với một shop (tenantUserId); quyền theo danh sách permission gán trên mã.
• Phase 1: quyền truy cập dữ liệu ở mức full shop (chưa áp OWD/row-scope CRM như staff).

1. Đăng nhập iSale với tài khoản chủ shop hoặc nhân viên có quyền quản trị đầy đủ.
2. Mở màn hình Kết nối phần mềm khác (#/external-api trong app).
3. Nhấn Tạo mã mới — publicKey chỉ hiển thị một lần; lưu ngay nơi an toàn.
4. Chọn quyền tối thiểu cần thiết (accordion theo nhóm CRM, Bán hàng, Danh mục…).
5. Gọi thử API với header Authorization: Apikey <publicKey>.

Header bắt buộc

Authorization: Apikey <publicKey>

Mọi request tới /ext/v1/* phải có header trên. Key và client phải ở trạng thái active (status=1).

HMAC (tùy chọn — khuyến nghị production cho request ghi)

Áp dụng khi gửi ít nhất một header X-Timestamp, X-Nonce hoặc X-Signature trên POST/PUT/PATCH/DELETE:

• X-Timestamp — unix ms, lệch tối đa ±5 phút
• X-Nonce — UUID, không được trùng trong cửa sổ
• X-Signature — HMAC-SHA256 hex (khóa hiện dùng publicKey)

Mã lỗi thường gặp

Response có thể kèm header X-Request-Id để tra audit log phía shop.

Base URL: https://api2.isale.online (cấu hình production; không có dấu / cuối).

Versioning: prefix /ext/v1. Breaking change sẽ tăng version (/ext/v2).

Định dạng lỗi

{
  "error": {
    "code": "invalid_request",
    "message": "Missing required field: fullName",
    "details": { "field": "fullName" }
  }
}

Phân trang

• limit — mặc định 50, tối đa 200 (áp dụng trên nhiều endpoint list).
• Một số API hỗ trợ id để lọc/lấy từ bản ghi cụ thể (xem từng module).

Ví dụ kiểm tra kết nối

curl -s -H "Authorization: Apikey YOUR_PUBLIC_KEY" \
  "https://api2.isale.online/ext/v1/crm/leads?limit=5"

Gán quyền trên app Kết nối phần mềm khác. Mỗi endpoint yêu cầu permission tương ứng; thiếu quyền trả 403.

Leads

curl -X POST "https://api2.isale.online/ext/v1/crm/leads" \
  -H "Authorization: Apikey YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fullName":"Lead từ website","mobile":"0901234567","source":"website"}'

Contacts

Query list: limit, q (tìm theo tên, SĐT, email, mã).

Flows (automation)

curl -s -H "Authorization: Apikey YOUR_KEY" \
  "https://api2.isale.online/ext/v1/sales/orders?dateFrom=2026-06-01&dateTo=2026-06-30"

API đọc/ghi các bảng standard_table trong whitelist. Không thay thế API chuyên biệt cho contact, product, order, calendar, lead, flow.

Query: limit, id. Mọi bản ghi lọc theo userId của shop.

Bảng đọc được (whitelist)

store, staff, note, debt, quote, trade, trade_category, sales_line, business_type, money_account, transfer_note, received_note, level_config, shift_log, product_attribute, product_type, product_attribute_quantity, custom_table, custom_table_data, crm_task, crm_deal, crm_deal_item, crm_deal_stage, crm_pipeline

Bảng ghi được

store, note, debt, quote, trade, sales_line, business_type, money_account, transfer_note, received_note, custom_table_data

Áp dụng cho mọi request /ext/*. Vượt ngưỡng trả 429 kèm Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining.

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "...",
    "retryAfterSeconds": 42
  }
}

Đếm theo từng instance API (memory). Môi trường dev thường tắt rate limit.

• Chỉ cấp quyền tối thiểu cho từng đối tác tích hợp.
• Thu hồi mã ngay khi nghi ngờ lộ — trên app Kết nối phần mềm khác.
• Không log publicKey trong log ứng dụng phía bạn.
• Production: khuyến nghị bật HMAC cho mọi request ghi.
• Dữ liệu luôn scoped theo shop của mã — không truy cập chéo tenant.

Chủ shop xem audit log qua API nội bộ (Bearer): GET /external-integration/audit-logs?limit= — không dùng External API key.

Trang này là tài liệu tham khảo nhanh. Nếu cần schema chi tiết (model, field), mở Swagger document ext-v1:

Mở Swagger External API

https://api2.isale.online/swagger/index.html?urls.primaryName=ISale%20External%20API%20ext-v1