Phương thức tích hợp
Tích hợp theo năng lực kỹ thuật và kênh bán của bạn
Đối tác chọn một hoặc kết hợp nhiều phương thức tùy năng lực kỹ thuật và kênh bán của mình.
Năm phương thức tích hợp
API
Ứng dụng đã có luồng thanh toán riêng (xe công nghệ, thương mại điện tử, điện máy).
Webview nhúng
Cần ra thị trường nhanh, ít nguồn lực lập trình.
Cổng bán (Sale Kit)
Kênh bán có nhân viên (ngân hàng, bưu điện, chuỗi cửa hàng).
White-label
Đối tác muốn trải nghiệm đồng nhất với thương hiệu của mình.
Trao đổi file
Đối tác chưa tích hợp thời gian thực hoặc cần đối soát số lượng lớn.
So sánh chi tiết
| Phương thức | Mô tả | Phù hợp khi | Thành phần Miracorp |
|---|---|---|---|
| API | Đối tác gọi API REST/JSON từ ứng dụng hoặc hệ thống bán hàng để báo phí, tạo đơn, tra cứu, cập nhật, hủy đơn. Giao diện do đối tác tự thiết kế. | Ứng dụng đã có luồng thanh toán riêng (xe công nghệ, thương mại điện tử, điện máy). | Miracorp Core API, API Gateway |
| Webview nhúng | Trang bán bảo hiểm dựng sẵn, nhúng vào ứng dụng hoặc website của đối tác. Gồm danh mục sản phẩm, kê khai, thanh toán và theo dõi đơn. | Cần ra thị trường nhanh, ít nguồn lực lập trình. | Miracorp Webview |
| Cổng bán (Sale Kit) | Cổng web cho nhân viên, chi nhánh và đại lý của đối tác: quản lý đơn, khách hàng, yêu cầu cấp đơn, nhắc thanh toán, tái tục, khuyến mãi, báo cáo đối soát, doanh thu và hoa hồng. | Kênh bán có nhân viên (ngân hàng, bưu điện, chuỗi cửa hàng). | Miracorp Sale Kit, Miracorp Admin Center |
| White-label | Cổng bán dựng riêng theo thương hiệu đối tác: logo, màu sắc, cấu hình sản phẩm, tên miền và môi trường triển khai riêng. | Đối tác muốn trải nghiệm đồng nhất với thương hiệu của mình. | Bản build riêng cho từng đối tác |
| Trao đổi file | Đồng bộ dữ liệu giao dịch và đối soát theo lô qua SFTP hoặc kho lưu trữ S3; ghi nhận giao dịch ngoại tuyến. | Đối tác chưa tích hợp thời gian thực hoặc cần đối soát số lượng lớn. | SFTP server, đồng bộ S3 |
API
- Mô tả
- Đối tác gọi API REST/JSON từ ứng dụng hoặc hệ thống bán hàng để báo phí, tạo đơn, tra cứu, cập nhật, hủy đơn. Giao diện do đối tác tự thiết kế.
- Phù hợp khi
- Ứng dụng đã có luồng thanh toán riêng (xe công nghệ, thương mại điện tử, điện máy).
- Thành phần Miracorp
- Miracorp Core API, API Gateway
Webview nhúng
- Mô tả
- Trang bán bảo hiểm dựng sẵn, nhúng vào ứng dụng hoặc website của đối tác. Gồm danh mục sản phẩm, kê khai, thanh toán và theo dõi đơn.
- Phù hợp khi
- Cần ra thị trường nhanh, ít nguồn lực lập trình.
- Thành phần Miracorp
- Miracorp Webview
Cổng bán (Sale Kit)
- Mô tả
- Cổng web cho nhân viên, chi nhánh và đại lý của đối tác: quản lý đơn, khách hàng, yêu cầu cấp đơn, nhắc thanh toán, tái tục, khuyến mãi, báo cáo đối soát, doanh thu và hoa hồng.
- Phù hợp khi
- Kênh bán có nhân viên (ngân hàng, bưu điện, chuỗi cửa hàng).
- Thành phần Miracorp
- Miracorp Sale Kit, Miracorp Admin Center
White-label
- Mô tả
- Cổng bán dựng riêng theo thương hiệu đối tác: logo, màu sắc, cấu hình sản phẩm, tên miền và môi trường triển khai riêng.
- Phù hợp khi
- Đối tác muốn trải nghiệm đồng nhất với thương hiệu của mình.
- Thành phần Miracorp
- Bản build riêng cho từng đối tác
Trao đổi file
- Mô tả
- Đồng bộ dữ liệu giao dịch và đối soát theo lô qua SFTP hoặc kho lưu trữ S3; ghi nhận giao dịch ngoại tuyến.
- Phù hợp khi
- Đối tác chưa tích hợp thời gian thực hoặc cần đối soát số lượng lớn.
- Thành phần Miracorp
- SFTP server, đồng bộ S3
Tích hợp qua API
Quy ước chung
- Giao thức
- HTTPS, dữ liệu JSON; các API ghi dữ liệu dùng phương thức POST với header Content-Type: application/json.
- Định danh giao dịch
- Đối tác tạo mã request_id duy nhất cho mỗi giao dịch; mã này dùng để tra cứu, cập nhật và hủy đơn.
- Xác thực
- Mỗi đối tác được cấp khóa riêng; mọi yêu cầu mang chữ ký xác thực. Chi tiết nằm trong tài liệu kỹ thuật cấp cho đối tác.
- Định dạng thời gian
- DD/MM/YYYY HH:mm.
- Môi trường
- UAT dùng để tích hợp và kiểm thử; production chỉ mở sau khi nghiệm thu.
Nhóm API
Mỗi đối tác chỉ được mở nhóm API và sản phẩm đã ký kết. Danh sách API mở rộng theo sản phẩm mới của đối tác.
| Nhóm | Chức năng |
|---|---|
| Kiểm tra kết nối | Kiểm tra kết nối giữa đối tác và nền tảng |
| Bảo hiểm thiết bị | Báo phí, tạo đơn, tra cứu trạng thái, cập nhật số IMEI, hủy đơn |
| Bảo hành mở rộng (GWI) | Tạo đơn, tra cứu, cập nhật IMEI, hủy đơn |
| Bảo hiểm chuyến đi | Tạo, tra cứu, cập nhật, hủy bảo hiểm theo từng chuyến |
| Bảo hiểm tài xế | Tạo bảo hiểm cho tài xế |
| Bảo hiểm vận chuyển (Express) | Tạo, tra cứu, cập nhật, hủy bảo hiểm cho đơn vận chuyển |
| Bảo hiểm thực phẩm (FoodCare) | Tạo, tra cứu, cập nhật, hủy đơn; tra cứu theo số đơn; thêm người được bảo hiểm |
| Bảo hiểm điện tử qua TPA | Lấy bảng giá, tạo đơn bán hàng, cập nhật, kiểm tra và hủy đơn qua đơn vị TPA |
Kiểm tra kết nối
- Chức năng
- Kiểm tra kết nối giữa đối tác và nền tảng
Bảo hiểm thiết bị
- Chức năng
- Báo phí, tạo đơn, tra cứu trạng thái, cập nhật số IMEI, hủy đơn
Bảo hành mở rộng (GWI)
- Chức năng
- Tạo đơn, tra cứu, cập nhật IMEI, hủy đơn
Bảo hiểm chuyến đi
- Chức năng
- Tạo, tra cứu, cập nhật, hủy bảo hiểm theo từng chuyến
Bảo hiểm tài xế
- Chức năng
- Tạo bảo hiểm cho tài xế
Bảo hiểm vận chuyển (Express)
- Chức năng
- Tạo, tra cứu, cập nhật, hủy bảo hiểm cho đơn vận chuyển
Bảo hiểm thực phẩm (FoodCare)
- Chức năng
- Tạo, tra cứu, cập nhật, hủy đơn; tra cứu theo số đơn; thêm người được bảo hiểm
Bảo hiểm điện tử qua TPA
- Chức năng
- Lấy bảng giá, tạo đơn bán hàng, cập nhật, kiểm tra và hủy đơn qua đơn vị TPA
Luồng gọi API điển hình
Bước 1: Kiểm tra kết nối
Gọi kiểm tra kết nối để xác nhận đường truyền và khóa.
Bước 2: Báo phí
Gọi báo phí với thông tin sản phẩm, gói, giá trị; nhận về mức phí.
Bước 3: Tạo đơn
Khách xác nhận; đối tác gọi tạo đơn kèm request_id và thông tin người mua.
Bước 4: Tra cứu trạng thái
Nền tảng trả kết quả; trạng thái và liên kết giấy chứng nhận tra cứu được bằng API trạng thái.
Bước 5: Cập nhật / hủy
Khi cần, đối tác gọi cập nhật thông tin (ví dụ IMEI) hoặc hủy đơn kèm lý do.
Độ tin cậy
- Ghi nhật ký API: mọi yêu cầu và phản hồi được lưu cùng mã request_id để truy vết và xử lý khiếu nại.
- Khi hệ thống công ty bảo hiểm phản hồi chậm hoặc timeout, đơn của đối tác không bị mất: nền tảng ghi nhận lỗi, đánh dấu đơn chờ đồng bộ và đưa vào hàng đợi thử lại.
- Kiểm tra đầu vào theo từng API; đơn đã hủy hoặc hết hiệu lực bị từ chối cập nhật và trả mã lỗi rõ ràng.
- Giám sát tự động và cảnh báo khi cấp giấy chứng nhận hoặc đồng bộ gặp lỗi.
Mã trả về tiêu biểu
| Mã | Ý nghĩa |
|---|---|
1 | Thành công |
-1 | Lỗi hệ thống |
-100 | Mã đối tác không hợp lệ |
-404 | Không tìm thấy đơn |
-300 | Đơn đã bị hủy |
-400 | Đơn đã hết hiệu lực |
1- Ý nghĩa
- Thành công
-1- Ý nghĩa
- Lỗi hệ thống
-100- Ý nghĩa
- Mã đối tác không hợp lệ
-404- Ý nghĩa
- Không tìm thấy đơn
-300- Ý nghĩa
- Đơn đã bị hủy
-400- Ý nghĩa
- Đơn đã hết hiệu lực
Bảng trên là các mã thông dụng. Tài liệu kỹ thuật chi tiết (kèm bộ Postman collection) được cung cấp cho đối tác khi bắt đầu tích hợp.
Nhận tài liệu kỹ thuật và tài khoản UAT
Tài liệu kỹ thuật chi tiết được cung cấp cho đối tác khi bắt đầu tích hợp.