TaiLieu KhaoSat.docx

CÔNG TY TNHH AAA
TÀI LIỆU KHẢO SÁT PHÂN HỆ: KẾT NỐI FAST - CRM
Phiên bản: 1.0 ..........................................
Ngày viết tài liệu: ......................................
Ngày sửa lần cuối:....................................
Người viết: Hồ Vĩnh Khoa.........................

Mục lục
1. Kiểm soát tài liệu.....................................................................................................................................3
1.1 Mục đích tài liệu...................................................................................................................................3
1.2 Kiểm tra tài liệu....................................................................................................................................3
1.3 Tham gia thực hiện tài liệu ..................................................................................................................3
1.4 Xác nhận tài liệu khảo sát ...................................................................................................................4
2. Giới thiệu về Fast API.............................................................................................................................5
3. Quy ước ...................................................................................................................................................5
3.1 Bảo mật trên Fast API .........................................................................................................................5
3.2 Cách thức truyền dữ liệu.....................................................................................................................5
3.2.1 Cách tạo token..............................................................................................................................8
3.2.2 Cách tạo data................................................................................................................................9
3.2.3 Cách tạo {key} lúc gọi ApiQuery (Khác với lúc gọi ApiLogin).......................................................9
3.3 Thông số trả về..................................................................................................................................10
3.4 Thông báo khi có dữ liệu đầu vào cần chuyển qua đối tác...............................................................10
4. Kết nối FAST và CRM ...........................................................................................................................12
4.1.1 Quy trình tổng thể .......................................................................................................................12
4.2 Quy trình truyền dữ liệu chi tiết .........................................................................................................12
4.2.1 Dữ liệu mapping giữa FAST và CRM.........................................................................................12
4.2.2 Dữ liệu đồng bộ từ CRM sang FAST .........................................................................................12

1. Kiểm soát tài liệu
1.1 Mục đích tài liệu
- Đây là tài liệu mô tả yêu cầu về kết nối dữ liệu giữa hệ thống Fast Business Online triển khai tại
AAA và hệ thống CRM.
- Tài liệu này sẽ làm cơ sở để FAST chỉnh sửa các yêu cầu phục vụ cho việc kết nối dữ liệu với hệ
thống CRM.
1.2 Kiểm tra tài liệu
Ngày duyệt: Ngày duyệt:
Người duyệt: Khách hàng duyệt:
Chữ ký
Họ và tên: .……………………………………….
Chữ ký
Họ và tên:………………………………………….
1.3 Tham gia thực hiện tài liệu
Stt Họ tên người tham gia thực hiện tài liệu Chức danh Phòng
1 Hồ Vĩnh Khoa Trưởng dự án
2
3

1.4 Xác nhận tài liệu khảo sát
Hai bên cùng thống nhất xác nhận nội dung tài liệu khảo sát về các chức năng trong chương trình
Các yêu cầu bổ sung, cũng như các thay đổi sau này sẽ được hai bên xem xét và thống nhất bằng
văn bản.
Tài liệu có … trang được lập thành 02 (hai) bản, mỗi bên giữ 01 (một) bản có giá trị như nhau.
TP HCM, ngày ….. tháng ….. năm …..
Đại diện Công ty AAA Đại diện Công ty FAST

2. Giới thiệu về Fast API
- Fast API sử dụng công nghệ JSON dùng để truyền và nhận dữ liệu.
- Đối tác sử dụng Xcode(MacOS), .Net, Python, Java, … điều có thể kết nối với API và nhập –
xuất dữ liệu dễ dàng
3. Quy ước
3.1 Bảo mật trên Fast API
Hiện tại trên Fast API được tích hợp các phương thức bảo mật nhiều lớp, khi có điều kiện bất kỳ
không thỏa là chúng tôi sẽ reject dữ liệu và không cần phải Phân Giải JSON, khi đó khả năng chịu tải
của hệ thống sẽ tốt hơn
Các phương thức bảo mật của Fast API gồm có:
- Private key: Khóa được khai báo sẵn, không truyền đi trong suốt phiên làm việc
- Token: trong một thời gian làm việc, token sẽ thay đổi
- Public Key: Được mã hóa và bảo mật theo cơ chế riêng, kể cả ai đó biết về cơ chế này cũng
không thể can thiệp trong suốt phiên làm việc của hệ thống
- Chứng thực toàn vẹn dữ liệu: Dữ liệu được mã hóa và truyền đi, cho dù có sự can thiệp 1 ký tự
bất kỳ thì hệ thống vẫn phát hiện được
- Chống replay attack: Cơ chế này chống lại trường hợp tấn công trên đúng dữ liệu được sinh ra,
nhằm gây quá tải hệ thống, tương tự như DDOS
- Chống request tự động: Khi login sai sau n lần trong m phút thì hệ thống sẽ khóa tài khoản tạm
thời trong k phút
- Block IP: Khi dùng cơ chế này thì mỗi User chỉ được phép tương tác đến API từ một danh sách
IP được khai báo sẵn theo từng User, nếu không tồn tại thì hệ thống sẽ Reject
3.2 Cách thức truyền dữ liệu
- Dữ liệu được truyền đồng bộ qua phương thức POST đến trang http(s)://..../APIQuery.ashx, với
các thông số cơ bản sau(Do một số đối tác truyền bất đồng bộ dữ liệu 1 phiếu truyền 2 lần cùng
1 thời gian, khi đó dữ liệu mới đến trước, dữ liệu cũ đến sau, dẫn đến phiếu lưu là phiếu cũ)

Stt Mã Diễn giải
1 token
Mã phiên làm việc, mỗi token có hạn hiệu được định nghĩa trước,
khi token sắp hết hạn, sẽ gọi hàm cấp lại token khác
2 form Tên các hàm cần gọi, được mã hóa bằng Base64
3 key
Là khóa chứng thực dữ liệu được truyền đi không được chỉnh
sửa, có hướng dẫn tạo key ở mục sau
4 data
Dữ liệu truyền đi dạng Json, được mã hóa và có thể giải mã được,
có hướng dẫn tạo data ở mục sau
5 userid Mã user được fast cấp, để phân biệt nguồn dữ liệu
6 time
Có 2 cách như sau:
+ Định dạnh: yyyyMMddhhmmssffffff là giờ hiện của hệ thống
(Dùng cho hệ thống vừa và nhỏ, lượng request ít)
+ số n tự tăng sau mỗi lần request( dùng cho hệ thống lớn, lượng
reuqest nhiều)
* (phần time này nên cấp tập trung một nơi, để bảo đảm số sau
luôn lớn hơn số trước), khi nhận dữ liệu sau khi check key ok thì
kiểm tra nếu time trước đó phải nhỏ hơn time truyền qua thì mới
được thực thi, mục đích của việc này là chống spam và trùng dữ
liệu
Mô phỏng trên POSTMAN

Các mã lỗi chính khi bạn mới vừa tương tác với hệ thống, ngoài ra tùy theo chức năng mà có mã lỗi
con chi tiết theo từng Form
Mã Mô tả
11 Tham số truyền bị thiếu
12 Dữ liệu truyền chưa đúng
13 User chưa được cấp hoặc chưa được kích hoạt
14
Chứng thực không thành công, do sai privateKey hoặc cách sinh key không
đúng
15 Cấu trúc data chưa đúng định dạng JSON so với yêu cầu
16
Time truyền trong data nhỏ hơn time time trong hệ thống đang chạy, truyền
time thì chỉ dùng 1 máy chủ để cấp, cho ngày giờ (hoặc stt tự tăng) được
thống nhất
17 Mã hàm không tồn tại
18
Cột dữ liệu không đúng theo quy định, có kèm theo danh sách cột không tồn
tại
19 Không được phép xóa dữ liệu qua API
20 Token đã hết hạn, khi này bạn cần gọi hàm login lại
21
Cột … có giá trị không được rỗng (Vì mục đích báo mật, thông báo chi tiết
cột chỉ có hiệu lực khi debug, khi hệ thống go live sẽ chỉ báo giá trị không
được rỗng)
22 Độ dài của chuỗi vượt quá qui định
23 Mã không được chứ ký tự đặc biệt
24
Số liệu đã được khóa, bạn không được sửa, thêm khi các phiếu có ngày <=
ngày khóa
25 Sai ràng buộc, trường …. có giá trị nằm trong danh sách …..
26 Hàm ….. đã tắt, vui lòng liên hệ người quản trị
51 Có lỗi xảy ra trong quá trình thực thi, có kèm theo nội dung lỗi

3.2.1 Cách tạo token
Fast sẽ cấp một cặp privateKey và UserID login dùng để đăng nhập vào hệ thống. Khi login , bạn gọi
đến trang http(s)://..../APILogin.ashx, với thông số POST như sau:
- userID : được Fast cấp, userId này sẽ không đổi trong suốt quá trình hệ thống vận hành
- privateKey : key này sẽ thay đổi trong quá trình test và release sản phẩm, đôi khi có thể thay đổi
trong quá trình hệ thống vận hành để bảo đảm bảo mật, cho nên bạn cần phải khai báo động
thông tin này!
(privateKey này không truyền đi trong suốt phiên làm việc của hệ thống, privateKey chủ yếu để tạo
Key được truyền đi để chứng thực)
- time : Có mô tả làm tương tự ở mục các thông số cần thiết khi đồng bộ
- key: Tạo key ta làm như sau ta MD5 chuỗi privateKey + userID + time, lấy các ký tự thứ
2,9,30,18,23,16,12,17,22,1 (chuỗi này nên khai báo, vì có thể thay đổi khi chạy thực tế, vị trí bắt
đầu là 1, không phải 0), cách làm này tương tự như phần chứng thực data ở phía dưới
Sau khi request http(s)://..../APILogin.ashx, hệ thống Fast sẽ chứng thực, nếu thỏa điều kiện, hệ
thống sẽ trả về dữ liệu dạng JSON như sau:
[{“type”:1, “msg”:””, “token”:”xnshmsux34”, “expired”: “7”}]
Với:
- token : giá trị này sẽ được truyền đi trong suốt quá trình làm việc của hệ thống, độ dài 10 ký tự
- expired: số ngày hết hạn của token kể từ khi cấp (ngày, giờ, phút, giây cấp), bạn nên kiểm tra và
gọi lại hàm APIlogin.aspx trước khi token hết hạn, tốt nhất là gọi cấp lại trước 6 giờ hết hạn!
Cấu trúc của phương thức POST lúc Login như sau:
userID=34&time=20190529152810552037&key=35d2d7c163
Case test dưới đây để test code khi lập trình gọi APILogin
Position ID: 2,9,30,18,23,16,12,17,22,1
Private Key: BHAJKHJK
Time: 20200904232617669949
User ID: 34
Kết quả:
 MD5 (Base 64 (Private Key + User ID + Time)) :
c28cc460647e7a6831f01181e4462da8
 Key: 26d188e31c

3.2.2 Cách tạo data
Dữ liệu là một khối dữ liệu được xác định bởi cấu trúc JSON. Trong trường hợp dữ liệu quá lớn, nó
phải được chia thành nhiều lần,
Số dòng dữ liệu tối đa là tầm 2 000 dòng dữ liệu, mục đích để hạn chế phình dữ liệu lúc truyền đi, dữ
liệu sẽ được truyền qua phương thức POST đến trang APIQuery.aspx
Data có cấu trúc dạng JSON đặt tên là AA như sau:
[ { “YourID”:”1231235”,
“VoucherNo”:”DN001”,
“Date”: “20/05/2018”,
“CusCode”: “20/05/2018”,
“Product”: “VT001”,
“Quality”: 1,
“Price”: 1000000,
…
},{ “YourID”:”1231235”,
“VoucherNo”:”DN001”,
“Date”: “20/05/2018”,
“CusCode”: “20/05/2018”,
“Product”: “VT002”,
“Quality”: 1,
“Price”: 1000000,
…
}]
Sau đó base64 giá trị data AA vừa tạo ở trên ta sẽ có được chuỗ BB, Ta sẽ có {data} = BB
3.2.3 Cách tạo {key} lúc gọi ApiQuery (Khác với lúc gọi ApiLogin)
Ta MD5 chuỗi privateKey + time + data ta được chuỗi XK, lấy các ký tự thứ
2,9,30,18,23,16,12,17,22,1 của chuỗi XK(danh sách vị trí này nên khai báo, vì có thể thay đổi khi chạy
thực tế, vị trí bắt đầu là 1, không phải 0) ta được chuỗi XKEY
Ta sẽ có {key} = KEY
Cấu trúc của phương thức POST lúc GET hoặc SET như sau:
token=4D255AB8A8&userid=34&form=c2V0U2FsZXNJbnZvaWNlcw==&key=e11dd977f8&time=20
190607164504876746&data=W3siQmF0Y2hJRCI6MTg4NzQsIkNlbnRlcklEIjoyNiwiRGF0ZSI6IjE0LzA
2LzIwMTkifSx7IkJhdGNoSUQiOjE4ODc0LCJDZW50ZXJJRCI6MjYsIkRhdGUiOiIxOC8wNi8yMDE5In
1d

Case test dưới đây để test code khi lập trình gọi APIQuery
Position ID: 2,9,30,18,23,16,12,17,22,1
Private Key: BHAJKHJK
Time: 20200904230909639123
Data: W3sKICAgY2FjaGVJRDogInxjYWNoZUlEfCIKfV0=
Kết quả:
 MD5 (Base 64 (Private Key + Time + Data)):
c28cc460647e7a6831f01181e4462da8
 Key: 26d188e31c
3.3 Thông số trả về
Kết quả trả về dạng JSON được base64
Data có cấu trúc dạng JSON đặt tên là AA như sau
[{
type: 0, 1,2…,
msg: ‘Câu thông báo nếu có’,
count: 100, -- Số record trả về, dùng trong trường hợp get dữ liệu
continue: 1/0, -- 1 - Vẫn còn dữ liệu thỏa, nhưng chưa trả về, gọi tiếp tục để dữ
liệu trả về tiếp, 0 – Không còn dữ liệu
cacheID: Mã cache lưu tạm dữ liệu, để chờ đẩy đi,
data:
[
{id_qlcc:”KH01”, ten_kh: “Nguyễn Văn A”, ….},
{id_qlcc:”KH01”, ten_kh: “Nguyễn Văn A”, ….},
…..
]
}]
3.4 Thông báo khi có dữ liệu đầu vào cần chuyển qua đối tác
- API của Fast có hỗ trợ thông báo cho đối tác biết khi có dữ liệu cần chuyển từ Fast qua. Quý đối
tác cần phải xây dựng 1 URL (VD: http://127.25.64:8080/fastAlert.aspx) với các thông số POST
(không phải GET) như sau:
 time: Mỗi lần gọi URL, bên Fast sẽ gửi kèm một số N, bạn lưu số N lại, và số sau luôn
lớn hơn số trước, để hỗ trợ chống Replay Attack
 data: là cấu trúc JSON chứa danh sách các hàm có dữ liệu cần chuyển qua, JSON này
được Base64
VD: ["getItems","getCustomers","getSites","getSaleEmployees"]
 key: Cách tạo key tương tự cách tạo Key ở phần Fast nhận dữ liệu từ đối tác
Ta MD5 chuỗi privateKey + time + data ta được chuỗi XK, lấy các ký tự thứ
2,9,30,18,23,16,12,17,22,1 của chuỗi XK(danh sách vị trí này nên khai báo, vì có thể thay
đổi khi chạy thực tế, vị trí bắt đầu là 1, không phải 0) ta được chuỗi XKEY
Ta sẽ có {key} = KEY

Khi có dữ liệu cần chuyển từ Fast cho đối tác thì hệ thống bên Fast sẽ gọi URL do quý đối tác
cung cấp theo các thông số POST được quy định sẵn. Sau khi nhận được thông báo này, quý
đối tác sẽ gọi trang APIQuery.aspx với các hàm tương ứng trong phần data được gửi qua. Sau
khi quý đối tác lấy dữ liệu xong thì Respone kết quả [‘OK’], nếu có lỗi thì respone về [‘ERROR’,
‘Kèm nội dung lỗi’] để Fast lưu lại log và bắt đầu quy trình mới.

4. Kết nối FAST và CRM
4.1.1 Quy trình tổng thể
STT CRM truyền sang FAST nhận
1 Danh mục khách hàng Danh mục khách hàng
2 Danh mục căn hộ Danh mục căn hộ
3 Danh mục giao dịch Danh mục giao dịch
4 Chuyển nhượng Chuyển nhượng
5 Phiếu thu tiền mặt Phiếu thu tiền mặt
6 Phiếu chi tiền mặt Phiếu chi tiền mặt
7 Giấy báo nợ Giấy báo nợ
8 Giấy báo có Giấy báo có
4.2 Quy trình truyền dữ liệu chi tiết
4.2.1 Dữ liệu mapping giữa FAST và CRM
Đây là các danh mục cần khai báo trường để mapping dữ liệu giữa 02 bên, vì tính chất ít phát sinh và
chỉ đồng bộ 1 lần ban đầu nên không cần thông qua API
4.2.1.1 Danh mục dự án (vụ việc)
Trên danh mục dự án của CRM có trường khai báo mã dự án tương ứng của FAST để phục vụ
mapping mã dự án khi đồng bộ dữ liệu.(FAST sẽ gửi CRM mã dự án của FAST mỗi khi phát sinh dự
án mới)
4.2.2 Dữ liệu đồng bộ từ CRM sang FAST
4.2.2.1 Danh mục khách hàng
- CRM truyền qua FAST danh mục khách hàng. Khi nhận được data FAST sẽ kiểm tra [ID khách
hàng] nếu chưa tồn tại thì tạo mới, ngược lại thì cập nhật lại thông tin
- Thời điểm truyền dữ liệu: CRM sẽ tự quy định thời gian truyền, bất cứ lúc nào truyền nếu đúng
cấu trúc FAST sẽ nhận vào phần mềm
Tham số Kiểu dữ liệu
Bắt
buộc
Mô tả
id int X ID khách hàng của CRM

ten_kh nvarchar(128) X Tên khách hàng
dia_chi nvarchar(128) Địa chỉ thường trú
dc_lh nvarchar(128) Địa chỉ liên hệ
mst char(18) Mã số thuế
cmnd char(16) CMND
ngay_cap smalldatetime Ngày cấp CMND
noi_cap nvarchar(64) Nơi cấp CMND
dien_thoai varchar(32) Số điện thoại
e_mail nvarchar(256) Email
4.2.2.2 Danh mục căn hộ
- CRM truyền qua FAST danh mục căn hộ. Khi nhận được data FAST sẽ kiểm tra [ID căn hộ] nếu
chưa tồn tại thì tạo mới, ngược lại thì cập nhật lại thông tin
- Thời điểm truyền dữ liệu: CRM sẽ tự quy định thời gian truyền, bất cứ lúc nào truyền nếu đúng
cấu trúc FAST sẽ nhận vào phần mềm
Bắt
buộc
Mô tả
id int X ID sản phẩm của CRM
ten_hh nvarchar(128) X Tên SP BĐS
id_vv int X ID dự án của CRM
loai char(1) X Loại BĐS
dt0 numeric(19,3) Diện tích thông thuỷ

4.2.2.3 Giao dịch
-
-Tham số Kiểu dữ liệu
Bắt
buộc
Mô tả
id_gcc varchar(36) X ID giữ chỗ chung của CRM
id int X ID giao dịch của CRM
loai_gd tinyint X ID loại giao dịch của CRM (0-Giữ chỗ, 1-Phiếu cọc, 2-
Hợp đồng cọc, 4-Hợp đồng mua bán, 5-bàn giao)
id_hh int X ID sản phẩm của CRM
id_kh int X ID khách hàng của CRM
so_ct char(16) X Số giao dịch
ngay_lct smalldatetime X Ngày giao dịch
ma_nt char(3) X Mã ngoại tệ (Nếu ở Landsoft là 1 thì trả Fast = "VND",
nếu là 2 thì trả Fast = "USD")
t_tien_nt numeric(16,2) X Thành tiền trước thuế
thue_suat numeric(5,2) Thuế suất
t_thue_nt numeric(16,2) Thuế GTGT
t_tt_nt numeric(16,2) Thành tiền sau thuế
phi_bt_nt numeric(16,2) Phí bảo trì (Không cần thiết nếu không có trên CRM)
status char(1) X Trạng thái (1 - bình thường, 0 - đã thanh lý)
4.2.2.4 Chuyển nhượng
- CRM truyền qua FAST thông tin chuyển nhượng.
- Thời điểm truyền dữ liệu: CRM sẽ tự quy định thời gian truyền, bất cứ lúc nào truyền nếu đúng cấu
trúc FAST sẽ nhận vào phần mềm
Bắt
buộc
Mô tả

id int X ID chuyển nhượng
id_hd int X ID giao dịch của CRM
loai_gd tinyint X ID loại chuyển nhượng
id_kh int X ID khách hàng của CRM (nhận chuyển
nhượng)
ngay_ct smalldatetime X Ngày chuyển nhượng
4.2.2.5 Phiếu thu tiền mặt
- CRM truyền qua FAST thông tin phiếu thu tiền mặt
Master Kiểu dữ liệu
Bắt
buộc
Mô tả
id int X ID chứng từ của CRM
doi_tac nvarchar(128) Người giao dịch
tk char(16) X Tài khoản nợ
so_ct char(12) X Số chứng từ
ngay_ct smalldatetime X Ngày chứng từ
ma_nt char(3) X Mã ngoại tệ
dien_giai nvarchar(128) Lý do thu
Bắt
buộc
Mô tả
tk_co char(16) X Tài khoản có
tien_nt numeric(16,2) X Tiền
id_gcc varchar(36) X ID giữ chỗ chung của CRM (Nếu là phiếu giữ
chỗ chung thì truyền ID này)

ma_td1 char(16) X Mã đợt
4.2.2.6 Phiếu chi tiền mặt
- CRM truyền qua FAST thông tin phiếu chi tiền mặt
Bắt
buộc
Mô tả
tk char(16) X Tài khoản có
ma_nt char(3) X Mã ngoại tệ (Nếu ở Landsoft là 1 thì trả Fast =
"VND", nếu là 2 thì trả Fast = "USD")
dien_giai nvarchar(128) Lý do chi
Bắt
buộc
Mô tả
tk_no char(16) X Tài khoản nợ
ma_hd int X ID giao dịch của CRM
ma_vv int X ID dự án của CRM

4.2.2.7 Giấy báo nợ
- CRM truyền qua FAST thông tin giấy báo nợ
Bắt
buộc
Mô tả
tk char(16) X Tài khoản có
ma_nt char(3) X Mã ngoại tệ (Nếu ở Landsoft là 1 thì trả Fast =
"VND", nếu là 2 thì trả Fast = "USD")
dien_giai nvarchar(128) Lý do chi
Bắt
buộc
Mô tả
tk_no char(16) X Tài khoản nợ
ma_hd int X ID giao dịch của CRM
ma_vv int X ID dự án của CRM
4.2.2.8 Giấy báo có
- CRM truyền qua FAST thông tin giấy báo có

Bắt
buộc
Mô tả
tk char(16) X Tài khoản nợ
ma_nt char(3) X Mã ngoại tệ
dien_giai nvarchar(128) Lý do thu
Bắt
buộc
Mô tả
tk_co char(16) X Tài khoản có

TaiLieu KhaoSat.docx

Recommended

Recommended

More Related Content

Similar to TaiLieu KhaoSat.docx

Similar to TaiLieu KhaoSat.docx (20)

TaiLieu KhaoSat.docx