Giới thiệu 3NS API

3NS API cho phép doanh nghiệp quản lý các mẫu thông báo của OA và tương tác với khách hàng thông qua số điện thoại liên kết với tài khoản Zalo sử dụng các mẫu thông báo đã đăng kí với Zalo.

Tạo API Key

1. Truy cập vào Zalo Official Account > API Key

2. Nhập tên Token và bấm nút Tạo mới

3. Copy và lưu lại Token

Cách sử dụng

Ở phần header, chúng tôi sẽ sử dụng API Key trong trường Authorization với giá trị như sau: "Bearer [API KEY]"

Ví dụ

curl --location --request GET 'https://api.3ns.com.vn/profile --header 'Authorization: Bearer [API_KEY]'

Lưu ý:

+ API Key không có thời gian hết hạn sử dụng. Bạn có thể thu hồi ở trang Zalo Official Account > API Key

API Lấy thông tin tài khoản

API cho phép đối tác truy xuất thông tin của doanh nghiệp/tài khoản.

URL: https://api.3ns.com.vn/profile
Method: GET
Content Type: application/json
Response Type: application/json

Example request

curl --location --request GET 'https://api.3ns.com.vn/profile' 
--header 'Authorization: Bearer [API_KEY]'

Example response

{
    "error": 0,
    "message": "Success",
    "data": {
        "id": 1000,
        "oa_id": "764023222428847626",
        "name": "3NS TEST",
        "description": "Zalo OA Test ZNS (3NS Agency)",
        "avatar": "https://s160-ava-talk.zadn.vn/c/2/9/7/1/160/2a2c46bcafa6936ac795e7e5de79fb8b.jpg",
        "cover": "https://cover-talk.zadn.vn/b/e/6/5/2/2a2c46bcafa6936ac795e7e5de79fb8b.jpg",
        "is_verified": true,
        "template_tags": "",
        "daily_quota": 500,
        "remaining_quota": 0,
        "free_remaining_quota": 100,
        "free_expired_datetime": 1692082112,
        "balance": "0",
        "status": "ACTIVE"
    }
}

API Lấy danh sách mẫu tin nhắn

URL: https://api.3ns.com.vn/templates
Method: GET
Content Type: application/json
Response Type: application/json

Example request

curl --location --request GET 'https://api.3ns.com.vn/templates' 
--header 'Authorization: Bearer [API_KEY]'

Example response

{
    "error": 0,
    "message": "Success",
    "data": [
        {
            "id": 1000,
            "name": "Mã xác thực OTP",
            "status": "ENABLE",
            "list_params": [
                {
                    "name": "otp",
                    "require": true,
                    "type": "STRING",
                    "maxLength": 10,
                    "minLength": 0,
                    "acceptNull": false
                }
            ],
            "timeout": 15000,
            "template_quality": "UNDEFINED",
            "template_tag": "TRANSACTION",
            "price": "300",
            "apply_template_quota": 0,
            "template_daily_quota": 0,
            "template_remaining_quota": 0
        }
    ]
}

API Lấy thông tin mẫu tin nhắn

URL: https://api.3ns.com.vn/templates/[template_id]
Method: GET
Content Type: application/json
Response Type: application/json

Example request

curl --location --request GET 'https://api.3ns.com.vn/templates' 
--header 'Authorization: Bearer [API_KEY]'

Example response

{
    "error": 0,
    "message": "Success",
    "data": {
        "id": 1000,
        "name": "Mã xác thực OTP",
        "status": "ENABLE",
        "list_params": [
            {
                "name": "otp",
                "require": true,
                "type": "STRING",
                "maxLength": 10,
                "minLength": 0,
                "acceptNull": false
            }
        ],
        "timeout": 15000,
        "template_quality": "UNDEFINED",
        "template_tag": "TRANSACTION",
        "price": "300",
        "apply_template_quota": 0,
        "template_daily_quota": 500,
        "template_remaining_quota": 0
    }
}

API Tạo mẫu tin nhắn ZNS

URL: https://api.3ns.com.vn/templates
Method: POST
Content Type: application/json
Response Type: application/json

{
    "template_name": "ZNS Xác nhận đơn hàng"
}

{
    "param_type": "1"
}

{
    "template_tag": "PROMOTION"
}

{
    "title": "Xác nhận đơn hàng,"
}

{
    "buttons": 
    [        
        {
            "type": "1",
            "label": "Tìm hiểu thêm",
            "url": "http://3ns.com.vn",
            "desc": "Nhấp vào đây"
        },        
        {
            "type": "4",
            "label": "Truy cập Mini App",
            "url": "http://3ns.com.vn",
            "desc": ""
        }
    ]
}

{
    "paragraphs": 
    [
        "Cám ơn <customer_name> đã tin tưởng."
    ]
}

{
    "rows": 
    [        
        {
            "key": "Mã đơn hàng",
            "value": "<order_code>"
        },        
        {
            "key": "Trạng thái",
            "value": "<payment_status>"
        },        
        {
            "key": "Giá tiền",
            "value": "<cost>"
        },        
        {
            "key": "Ghi chú",
            "value": "<note>"
        }
    ]
}

[
        [
            'id' => 1,
            'name' => 'Tên khách hàng (30)'
        ],
        [
            'id' => 2,
            'name' => 'Số điện thoại (15)'
        ],
        [
            'id' => 3,
            'name' => 'Địa chỉ (80)'
        ],
        [
            'id' => 4,
            'name' => 'Mã số (30)'
        ],
        [
            'id' => 5,
            'name' => 'Nhãn tuỳ chỉnh (30)'
        ],
        [
            'id' => 6,
            'name' => 'OTP (10)'
        ],
        [
            'id' => 7,
            'name' => 'Trạng thái giao dịch (30)'
        ],
        [
            'id' => 8,
            'name' => 'Thông tin liên hệ (50)'
        ],
        [
            'id' => 9,
            'name' => 'Giới tính / Danh xưng (5)'
        ],
        [
            'id' => 10,
            'name' => 'Tên sản phẩm / Thương hiệu (100)'
        ],
        [
            'id' => 11,
            'name' => 'Số lượng / Số tiền (20)'
        ],
        [
            'id' => 12,
            'name' => 'Thời gian (20)'
        ]
    ]

{
    "params": 
    [        
        {
            "name": "customer_name",
            "znsType": "1"
        },        
        {
            "name": "order_code",
            "znsType": "4"
        },        
        {
            "name": "payment_status",
            "znsType": "7"
        },        
        {
            "name": "cost",
            "znsType": "5"
        },        
        {
            "name": "note",
            "znsType": "5"
        }
    ]
}

{
  "postRowParagraphs": [
    "Mọi thắc mắc vui lòng liên hệ Hotline"
  ]}

{
    "ratings": 
    [        
        {
            "star": "1",
            "title": "Rất không hài lòng"
        },        
        {
            "star": "2",
            "title": "Không hài lòng"
        },        
        {
            "star": "3",
            "title": "Bình thường"
        },        
        {
            "star": "4",
            "title": "Hài lòng"
        },        
        {
            "star": "5",
            "title": "Rất hài lòng"
        }
    ]
}

{
    "censorship_notes": "Vui lòng kiểm tra lại"
}

{
    "logos": 
    {
        "light": "https://app.3ns.com.vn/build/assets/logo.png",
        "dark": "https://app.3ns.com.vn/build/assets/logo.png"
    }
}

Example request

curl --location --request POST 'https://api.3ns.com.vn/templates' 
--header 'Authorization: Bearer [API_KEY]' 
--header 'Content-Type: application/json' 
--data '{"template_name":"ZNS Xác nhận đơn hàng","buttons":[{"type":"3","label":"Quan tâm OA"},{"type":"1","label":"Tìm hiểu thêm","url":"https://hua.com.vn","desc":"Gọi cho tôi"}],"title":"Xác nhận đơn hàng,","paragraphs":["Cám ơn <customer_name> đã tin tưởng. Chúng tôi đã nhận được yêu cầu đặt hàng của bạn. Thông tin chi tiết đơn hàng:"],"rows":[{"key":"Mã đơn","value":"<order_code>"},{"key":"Trạng thái","value":"<payment_status>"},{"key":"Giá tiền","value":"<cost>"},{"key":"Ghi chú","value":"<note>"}],"params":[{"name":"customer_name","znsType":"1"},{"name":"order_code","znsType":"4"},{"name":"payment_status","znsType":"7"},{"name":"cost","znsType":"5"},{"name":"note","znsType":"5"}],"postRowParagraphs":["Mọi thắc mắc vui lòng liên hệ Hotline nếu cần tư vấn thêm về các sản phẩm và dịch vụ khác. Trân trọng!"],"ratings":null,"param_types":"1","template_tag":"TRANSACTION","censorship_notes":"DEMO","logos":{"light":null,"dark":null}}'

Example response

{
    "error": 0,
    "message": "Success",
    "data": {
        "id": 1021,
        "name": "Xác nhận đơn hàng,",
        "status": "DRAFT",
        "list_params": null,
        "timeout": null,
        "template_quality": null,
        "template_tag": null,
        "price": 300,
        "apply_template_quota": null,
        "template_daily_quota": null,
        "template_remaining_quota": null
    }
}

{
    "error": -109,
    "message": "Vui lòng nhập chọn loại mẫu ZNS"
}

API Gửi tin nhắn ZNS

URL: https://api.3ns.com.vn/messages
Method: POST
Content Type: application/json
Response Type: application/json

Example request

curl --location --request POST 'https://api.3ns.com.vn/messages' 
--header 'Authorization: Bearer [API_KEY]' 
--header 'Content-Type: application/json' 
--data '{
"phone": "0123456789",
"template_id": 1,
"template_data": {
"otp": "123456"
}
}'

Example response

{
    "error": -115,
    "message": "Tài khoản không đủ số dư"
}

{
    "error": 0,
    "message": "Success"
}

API Danh sách tin nhắn ZNS

URL: https://api.3ns.com.vn/messages
Method: GET
Content Type: application/json
Response Type: application/json

Example request

curl --location --request GET 'https://api.3ns.com.vn/messages?limit=100&offset=0' 
--header 'Authorization: Bearer [API_KEY]' 

Example response

{
    "error": 0,
    "message": "Success"
    "data": [
      {
        "id": "9a1ce4c8-259b-4dd6-98b2-d01ec4772737",
        "phone": "84912345678",
        "template_id": 12345678,
        "template_data": {
          "customer_name": "Nguyễn Văn A",
          "order_id": "123456",
          "order_date": "20/10/2023"
        },
        "status": "Hoàn thành",
        "error": null,
        "sent_time": "1694493336",
        "delivery_time": "1694493338"
      }
    ]}

API nạp tiền 3NS

URL: https://api.3ns.com.vn/deposits
Method: POST
Content Type: application/json
Response Type: application/json

Example request

curl --location --request POST 'https://api.3ns.com.vn/deposits' 
--header 'Authorization: Bearer [API_KEY]' 
--header 'Content-Type: application/json' 
--data '{"amount": "100000","redirect_url": "http://3ns.com.vn"}'

Example response

{
    "error": 0,
    "message": "Success",
    "data": {
        "redirect_url": "http://app.3ns.com.vn/platform/deposit/f4049f3f194e6da0036ac2ea612830c60c9d2237"
    }
}

{
    "error": -132,
    "message": "Tham số không hợp lệ"
}