Third party app

Hướng Dẫn Tích Hợp DooPage

1. Yêu Cầu

1.1. Thông Tin Cần Chuẩn Bị

Trước khi bắt đầu tích hợp, bạn cần chuẩn bị các thông tin sau:

1. Tên ứng dụng: Tên của ứng dụng bạn sẽ tích hợp.

2. Mô tả của ứng dụng: Mô tả ngắn gọn về chức năng và mục đích của ứng dụng.

3. Logo của ứng dụng: Hình ảnh đại diện cho ứng dụng (URL hoặc file hình ảnh).

4. Webhook URL: Địa chỉ endpoint nhận sự kiện từ DooPage khi người dùng thực hiện hành động (ví dụ: tạo đơn hàng, cập nhật trạng thái).

5. Authorization Callback URL: Địa chỉ endpoint mà DooPage sẽ redirect người dùng về sau khi họ cho phép ứng dụng truy cập, kèm theo access_token.

6. Privacy URL: Địa chỉ URL của trang chính sách bảo mật.

7. TOS URL: Địa chỉ URL của trang điều khoản dịch vụ.

1.2. Thông Tin Cần Lấy Từ DooPage

Liên hệ với DooPage để nhận các thông tin sau:

1. Application Client ID: Mã định danh duy nhất của ứng dụng.

2. Application Client Secret: Khóa bảo mật của ứng dụng, dùng để xác thực khi gọi API.

2. Hướng Dẫn Tích Hợp

2.1. Cách Lấy Access Token

Bước 1: Tạo Authorization URL

Để lấy access token, bạn cần tạo một URL ủy quyền (Authorization URL) với cấu trúc như sau:

https://my.doopage.com/oauth2?client_id={client_id}&response_type=token&redirect_uri={callback_url}

Trong đó:

• client_id: Mã ứng dụng bạn đã nhận từ DooPage.

• response_type: Loại ủy quyền, giá trị bắt buộc là token.

• redirect_url: URL mà DooPage sẽ redirect về sau khi người dùng cấp quyền.

Bước 2: Gọi API Thay Mặt Người Dùng

Sau khi người dùng truy cập Authorization URL và cấp quyền, ứng dụng của bạn sẽ nhận được access_token thông qua tham số access_token trong URL callback. Mỗi access_token tương ứng với một công ty trên DooPage mà người dùng đã cấp quyền.

Sử dụng access_token, ứng dụng của bạn có thể gọi các API để lấy thông tin của công ty. Vui lòng tham khảo thêm trong Tài liệu API và Tài liệu Webhook.

2.2. Tạo Custom Menu

Custom menu là một mục menu mà ứng dụng có thể tạo trên giao diện center.doopage.com, hỗ trợ người bán hàng (seller) thực hiện các thao tác cụ thể liên quan đến ứng dụng. Khi seller nhấn vào một menu item, một sự kiện webhook sẽ được gửi đến webhook_url của ứng dụng.

Bước 1: Tạo Menu Item

Để tạo menu item, ứng dụng cần thực hiện một HTTP POST request đến endpoint sau: https://app.doopage.com/public/api/v1.0/partner/application/custom-menu/provision/

Header:

Authorization: <client_id>|<client_secret> 

Body:

[
    {
        "custom_id": "order_history",
        "title": "Lịch sử đơn hàng",
        "description": "Xem lịch sử đơn hàng của khách hàng này",
        "menu_position": 1,
        "icon_url": "https://example.com/menu_item1.png"
    },
    {
        "custom_id": "create_order",
        "title": "Tạo đơn",
        "description": "Tạo đơn cho khách hàng này",
        "menu_position": 2,
        "icon_url": "https://example.com/menu_item2.png"
    }
]

• custom_id: Chuỗi ký tự tùy ý, dùng để quản lý, xóa hoặc sửa menu. custom_id sẽ được gửi kèm trong sự kiện webhook khi seller nhấn vào menu item.

Bước 2: Xử Lý Sự Kiện Webhook

Khi seller nhấn vào một menu item, DooPage sẽ gửi một HTTP POST request đến webhook_url của ứng dụng với nội dung như sau:

{
    "company_id": "<company_id>",
    "event_type": "trigger_menu_item",
    "timestamp": 1724146023123,
    "data": {
        "customer": {
            "id": "<customer_id>",
            "name": "<customer_name>"
        },
        "menu_item": {
            "custom_id": "<your_custom_id>"
        }
    }
}

Để chuyển hướng seller đến một URL bất kỳ, phản hồi của bạn cần trả về mã trạng thái HTTP 200 và body như sau:

{
    "menu_item": {
        "action": "redirect",
        "url": "<your_redirect_url>"
    }
}