Public API và Webhook

Giới thiệu Public API & Webhook

Để đáp ứng nhu cầu tích hợp với các hệ thống bên ngoài như ERP, CRM, Website, Mobile App, POS hoặc các phần mềm quản lý nội bộ, hệ thống cung cấp bộ Public API và Webhook giúp khách hàng và đối tác chủ động kết nối, đồng bộ dữ liệu và tự động hóa các quy trình nghiệp vụ.

Public API

Public API cho phép các hệ thống bên ngoài chủ động tương tác với nền tảng thông qua các giao thức chuẩn. Thông qua API, hệ thống bên ngoài có thể:

• Đồng bộ dữ liệu khách hàng, sản phẩm, đơn hàng và các dữ liệu nghiệp vụ khác.
• Tạo mới, cập nhật hoặc truy vấn thông tin trên hệ thống.
• Thực hiện các tác vụ theo nhu cầu tích hợp của doanh nghiệp.
• Kết nối các chức năng của nền tảng với hệ thống hiện có để xây dựng quy trình làm việc liền mạch.

Webhook

Webhook cho phép hệ thống chủ động gửi thông báo theo thời gian thực đến địa chỉ Endpoint của hệ thống bên ngoài khi phát sinh các sự kiện đã được đăng ký.

Thông qua Webhook, hệ thống tích hợp có thể nhận được thông tin ngay khi sự kiện xảy ra mà không cần thực hiện cơ chế kiểm tra dữ liệu định kỳ (Polling), từ đó giảm tải tài nguyên và tăng tốc độ đồng bộ.

Các sự kiện hỗ trợ sẽ phụ thuộc vào từng nghiệp vụ và có thể bao gồm:

• Khách hàng đăng ký hoặc cập nhật thông tin.
• Đơn hàng được tạo mới hoặc thay đổi trạng thái.
• Kích hoạt bảo hành thành công.
• Tích điểm, đổi quà hoặc thay đổi điểm thưởng.
• Các sự kiện nghiệp vụ khác theo từng phân hệ của hệ thống.

Lợi ích

• Tích hợp nhanh chóng với các hệ thống hiện có.
• Đồng bộ dữ liệu tự động, chính xác và theo thời gian thực.
• Giảm thao tác thủ công và hạn chế sai sót trong quá trình vận hành.
• Dễ dàng mở rộng và tùy biến theo nhu cầu của doanh nghiệp.
• Hỗ trợ xây dựng các quy trình tự động hóa nhằm nâng cao hiệu quả quản lý và trải nghiệm người dùng.

Tài liệu Public API và Webhook cung cấp đầy đủ thông tin về phương thức xác thực, danh sách API, cấu trúc Request/Response, mã phản hồi (Response Code), định dạng dữ liệu, danh sách sự kiện Webhook và các ví dụ tích hợp, giúp đội ngũ kỹ thuật triển khai kết nối một cách nhanh chóng, thuận tiện và nhất quán.

I. Tài liệu API

1. Nội dung tài liệu:

• Danh mục sản phẩm
• Khách hàng
• Nhóm sản phẩm
• Thông báo
• Đơn hàng
• Sản phẩm
• Tags
• Chương trình voucher
• Voucher

2. Chi tiết tài liệu: tại đây

II. Tài liệu webhook

A. Tổng quan

1. Loại sự kiện: các loại sự kiện sẽ được gửi cho khách hàng sau khi cài đặt cấu hình thành công.
2. Webhook url: đường dẫn khách hàng cung cấp, nhận data Zacademy gửi sang khi sự kiện xảy ra.
3. Thời gian gửi lại khi lỗi: Nếu gửi sang lần 1 bị lỗi thì sau x phút sẽ gửi lại lần 2, tối đa 3 lần tự động gửi

B. Cấu hình webhook

1. Vào Module Cửa hàng -> Cấu hình cửa hàng -> Cấu hình Webhook -> Thêm mới

2. Bổ sung thông tin vào popup cấu hình Webhook – Mở ra popup Thêm/sửa cấu hình webhook trong cửa hàng:

– Webhook URL: Nhập đường dẫn. Đây là địa chỉ Webhook callback URL (bắt buộc chạy https)

– Sự kiện: Chọn sự kiện muốn lấy nhận thông tin.

– Thông tin header: Bao gồm Key và Value, trường thông tin này không bắt buộc nhập (có thể là thông tin của Zacademy hoặc của bên bạn cần xuất hiện trong quá trình gửi dữ liệu để nhận biết nguồn tin)

3. Ấn Cập nhật để kết thúc quá trình

C. SỰ KIỆN WEBHOOK

Đây là trang báo cáo về các event webhook của hệ thống giúp bạn theo dõi và kiểm tra lại khi có phát sinh.

I. HƯỚNG DẪN SỬ DỤNG

1. STT là số thứ tự xuất hiện mới nhất của sự kiện phát sinh trên hệ thống.

2. Loại sự kiện chỉ định event phát sinh trong hệ thống Zacademy.

3. Mỗi event phát sinh mới sẽ được hiển thị đầu danh sách, ứng với một ID đối tượng cụ thể.

4. Số lần đã xử lý là số request của hệ thống bạn trả về với sự kiện được hệ thống Zacademy ghi nhận.

5. Trạng thái: – Chỉ định trạng lần xử lý mới nhất của event đó, là kết quả của việc gửi dữ liệu sang hệ thống của bạn. – Nội dung các trạng thái:

6. Ngày tạo: Thời gian event được sinh ra trên hệ thống Zacademy.

7. Hành động: – Click vào Lịch sử để mở ra popup theo dõi lịch sử của sự kiện.

Có thể truy cập json.parser.online.fr xem các dữ liệu đã gửi và đã nhận rõ hơn

– Click Gửi lại để gửi lại bằng tay 1 sự kiện cho bên khách hàng.

D. CÁC MẪU WEBHOOK

1.Mẫu của ĐƠN HÀNG

– Webhook URL:

– Method: POST

– Paramsend:

{ “id”: “208610”,

“cart_code”: “00000208610”,

“cart_type”: “cart”,

“user_id”: “56913”,

“ref_user_id”: null,

“payment_type”: “1”,

“payment_content”: “”,

“promotion_id”: “0”,

“user_voucher_id”: null,

“voucher_status”: “0”,

“total_value”: “1790000”,

“total_after”: “1790000”,

“total_cashback”: null,

“fee_ship”: null,

“weight”: “0”,

“wallet_fee”: null,

“commission_ref”: null,

“dropship_commission_ref”: null,

“accept_commission_ref”: “0”,

“cashback”: { “tickid”: { “user_cashback”: 35

}

},

“total_before”: “1790000”,

“total_cal_commission”: “1790000”,

“total_discount_value”: “0”,

“total_count_selected”: “5”,

“count_selected”: “3”, “status”: “5”,

“before_status”: “5”,

“address_id”: “30822”,

“store_id”: “552”,

“user_note”: null,

“site_note”: null,

“payment”: “Khi nhận hàng (COD)”,

“payment_method_id”: null,

“payment_id”: null,

“payment_status”: 0,

“txn_id”: null, “item_fee”: { “Phí Ship”: “Chưa tính”

},

“used_wallets”: null,

“wallet_option”: null,

“cart_fees”: null,

“commerce_fee”: “0”,

“is_reject”: “0”,

“commissions”: null,

“orders_time”: “2022-06-10 10:48:14”,

“delete_flag”: “0”,

“delivery_time”: null,

“utm_source”: “App”,

“modified”: “2022-06-10 10:53:56”,

“created”: “2022-06-10 10:47:45”,

“accept_commission_ref_date”: null,

“comment”: “”, “comment_time”: null,

“star”: null,

“pricing_id”: null,

“cart_type_name”: “Đơn hàng”,

“count”: 0,

“user”: {

“user_id”: “56913”,

“name”: “Đinh Thị Phương Thảo”

},

“pos_details”: “”, “promotions”: [],

“address”: { “id”: “30822”,

“user_id”: “56913”,

“name”: “Thẻo”,

“tel”: “0336965825”,

“address”: “64 đội cấn(Phường Đội Cấn,Quận Ba Đình,Thành phố Hà Nội)”,

“province_id”: “1”,

“district_id”: “101”,

“ward_id”: “1096”,

“city”: “Thành phố Hà Nội”,

“district”: “Quận Ba Đình”,

“ward”: “Phường Đội Cấn”,

“latitude”: “21.0344836”,

“longitude”: “105.8298894”,

“default_flag”: “1”,

“delete_flag”: “0”,

“modified”: “2022-05-26 14:02:22”,

“created”: “2022-05-26 14:02:22” },

“name_payment_method”: “Khi nhận hàng (COD)”,

“store_name”: “Điểm bán 1”,

“pricing_name”: “”,

“payment_status_name”: “Chưa thanh toán”

}

Response:

{

“status”: 200, “message”: “OK”

}

2. Mẫu của SẢN PHẨM

– Webhook URL: https://testapi.io/api/ToanPV/webhook

– Method: POST

– Paramsend:

{

“id”: “873167”,

“order_type”: “1”,

“product_code”: “CEkJ48H4W4”,

“product_type”: “0”, “name”: “Kẻ chân mày – Chanel”,

“unit_name”: null,

“discount”: “1500000”,

“discount_percent”: “0”,

“price”: “1500000”,

“price_steps”: null,

“commission_ref”: “0”,

“cashback_percent”: null,

“cart_step”: “1.0”,

“cat_id”: “53560”,

“ordering”: “1”,

“brand”: “”,

“sku”: null,

“rate”: “5”,

“inventory”: “998”,

“sale_in_stock”: “0”,

“level_inventory_min”: “0”,

“level_inventory_max”: “999999999”,

“weight”: “0”,

“slug”: “ke-chan-may-chanel”,

“image”: “https://abphotos.link/photos/origin/no-product-image.png”,
“video”: null,

“short_content”: “”,

“content”: “”,

“desc”: null,

“made_in”: “”,

“tags”: null,

“share_link”: null,

“has_attr”: “0”,

“sales”: “2”,

“delete_flag”: “0”,

“empty_flag”: “0”,

“modified”: “2022-06-09 13:10:30”,

“created”: “2022-05-26 14:34:10”,

“attributes”: null

}

Response

{

“status”: 200, “message”: “OK”

}

3. Mẫu của KHÁCH HÀNG

– Webhook URL: https://testapi.io/api/ToanPV/webhook – Method: POST – Paramsend:

{

“user_id”: “1347849”,

“name”: “Robot 2”,

“tel”: “0989898990”,

“premium”: “0”,

“premium_point”: “0”,

“premium_name”: null,

“premium_date”: null,

“last_login”: null,

“tags”: null,

“quote”: null,

“intro”: null,

“youtube”: null,

“facebook”: null,

“birthday”: “”,

“gender”: “”, “email”: “”,

“image”: null,

“image_cover”: null,

“id_card”: null,

“image_id_card_front”: null,

“image_id_card_back”: null,

“image_id_card”: null,

“bank_account”: null,

“bank_account_name”: null,

“bank_branch”: null,

“brand”: null,

“delete_flag”: “0”,

“invite_id”: null,

“refer”: null,

“is_refer”: “0”,

“ref_code”: null,

“invite_link”: null,

“invite_link_shorten”: null,

“language”: “vi”,

“invite_user_id”: null,

“bonus_invite_flag”: “0”,

“pricing_id”: null,

“pos_type”: null,

“pos_id”: null,

“store_id”: null,

“modified”: “2022-06-09 13:16:01”,

“created”: “2022-06-09 13:16:01”,

“accept_refer_date”: null

}

Response:

{

“status”: 200, “message”: “OK”

}

Response:

{

“status”: 200, “message”: “OK”

}