Tigerfly API Documents
API Domain: https://api.tigerfly.tw/
User Authentication (身分驗證)
使用者身分的驗證,是以 Authorization
當作欄位,並且使用 Bearer {access_token}
的組合附加在每次的請求的 header 上,以確認使用者的身分。例如 access token 為 2bf1efe7cc51f6eh5ad1c98f05y9s34463ca85ad
,那麼在 header 中的格式為
Authorization:Bearer 2bf1efe7cc51f6eh5ad1c98f05y9s34463ca85ad
。
Tfas (系統簡訊)
POST /tfas/send (系統簡訊發送)
https://api.tigerfly.tw/tfas/send
Request
- method: POST
- header:
- Authorization
- Content-Type: (choose one of following)
- application/x-www-form-urlencoded
- application/json
- data:
- access_token: [required if no Authorization in headers | string]
- campaign: custom campaign,can be used to filter report.
[optional | string | max 255 chars]
- example:
202004-notification
- data [required | json | max 5000 objects]
- id [optional]
- number [required]
- content [required]
- callback_url [optional]
- examples:
- Content-Type: application/x-www-form-urlencoded
curl --location --request POST 'https://api.tigerfly.tw/tfas/send' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer {token}' \
--data-urlencode 'data=[
{
"id": 1,
"number": "0900000000",
"content": "test 1",
"callback_url": "https://example.com/callback"
},
{
"id": 2,
"number": "0900000000",
"content": "test 2",
"callback_url": "https://example.com/callback"
}
]' \
--data-urlencode 'campaign=202004-notification'
- Content-Type: application/json
curl --location --request POST 'https://api.tigerfly.tw/tfas/send' \
--header 'Authorization: Bearer {token}' \
--header 'Content-Type: application/json' \
--data-raw '{
"data": [
{
"id": 1,
"number": "0900000000",
"content": "test 1",
"callback_url": "https://example.com/callback"
},
{
"id": 2,
"number": "0900000000",
"content": "test 2",
"callback_url": "https://example.com/callback"
}
],
"campaign": "202004-notification"
}'
Response
-
200 | OK
{
"data": [
{
"id": 1,
"tfas_id": "07f67d51c8802cc550ae85972798fa5b"
},
{
"id": 2,
"error": {
"code": "1102",
"message": "invalid data"
},
"tfas_id": "c2ae5d0a3c7cc44505572279293dd33e"
}
]
}
-
400 | Bad Request
{
"error": {
"code": "1101",
"message": "data exceeded the maximum size (5000) limit"
}
}
Callback
You will be notified when the status changed if callback_url
given.
POST /tfas/search (系統簡訊查詢)
https://api.tigerfly.tw/tfas/search
Request
- method: POST
- header:
- data:
- access_token [required if no Authorization in headers]
- tfas_ids [required | json]
Response
-
200 | OK
{
"data": [
{
"tfas_id": "07f67d51c8802cc550ae85972798fa5b",
"number": "886900000000",
"content": "test 1",
"status_code": "1",
"sent_time": "2019-04-26T00:00:00+0000"
},
{
"tfas_id": "c2ae5d0a3c7cc44505572279293dd33e",
"error": {
"code": "1201",
"message": "record not found"
}
}
]
}
-
400 | Bad Request
{
"error": {
"code": "1101",
"message": "tfas_ids exceeded the maximum size (500) limit"
}
}
GET /tfas/report (系統簡訊報表)
https://api.tigerfly.tw/tfas/report
Request
- method: GET
- header:
- data:
- page: the current page, default is 1.
- limit: records per page, default is 10, maximum is 500.
- campaign: campaign filter [optional]
- start_time: start time filter, default is 3 month ago, can not be earlier than 3 months ago.
It will be treated as UTC time if there is no timezone with it.
2020-01-01T00:00:00Z
2020-01-01T00:00:00+0800
- end_time: end time filter, default is current time.
It will be treated as UTC time if there is no timezone with it.
2020-01-01T23:59:59Z
2020-01-01T23:59:59+0800
- Example
https://api.tigerfly.tw/tfas/report?page=1&limit=10&campaign=202004news&start_time=2020-04-01T00:00:00%2B0800&end_time=2020-04-01T23:59:59%2B0800
Response
-
200 | OK
{
"current_page": 1,
"data": [
{
"tfas_id": "aa5fed857be479f3e7b43b1e2c9bfe22",
"campaign": "202004news",
"number": "886900000000",
"content": "test content",
"status_code": "0",
"sent_time": "2020-04-01T02:00:00+0000"
},
{
"tfas_id": "cfb74c51bf507a8f076e4d1fe5ad1023",
"campaign": "202004news",
"number": "886900000000",
"content": "test content",
"status_code": "2",
"sent_time": "2020-04-01T01:00:00+0000"
}
],
"first_page_url": "https://api.tigerfly.tw/tfas/report?page=1",
"from": 1,
"last_page": 3,
"last_page_url": "https://api.tigerfly.tw/tfas/report?page=17",
"next_page_url": "https://api.tigerfly.tw/tfas/report?page=2",
"path": "https://api.tigerfly.tw/tfas/report",
"per_page": 10,
"prev_page_url": null,
"to": 10,
"total": 30
}
-
400 | Bad Request
{
"error": {
"code": "400",
"message": "invalid time range parameters"
}
}
{
"error": {
"code": "400",
"message": "limit exceeded the maximum size (500)"
}
}
Delivery (超商未取貨)
POST /delivery/upload (上傳未取貨名單)
https://api.tigerfly.tw/delivery/upload
Request
- method: POST
- header:
- data:
-
schema
- order_id 訂單編號
- phone_number 行動電話號碼 [required]
- email 電子郵件地址
- shipping_id 物流編號 [required]
- cvs_type 超商種類 [required]
- 1: Seven Eleven
- 2: Family Mart
- cvs_store_name 門市名稱
- cvs_store_no 門市店號 [required]
- delivery_time 貨到店時間 [required]
-
examples
[
{
"order_id": "CVS0001",
"phone_number": "0912000111",
"email": "test@examples.com",
"shipping_id": "100200300400",
"cvs_type": "1",
"cvs_store_name": "林安門市",
"cvs_store_no": "200065",
"delivery_time": "2019-06-05 19:30:00"
},
{
"order_id": "CVS0001",
"phone_number": "0912000111",
"email": "test@examples.com",
"shipping_id": "100200300400",
"cvs_type": "4",
"cvs_store_name": "林安門市",
"cvs_store_no": "200065",
"delivery_times": "2019-06-05 19:30:00"
}
]
Response
-
200 | OK
{
"total": 2,
"success": 1,
"failed": 1,
"failed_descriptions": [
{
"row": 2,
"shipping_id": "100200300400",
"fields": {
"delivery_time": "This field is required.",
"cvs_type": "This field should be one of the following: [1, 2]."
}
}
]
}
-
400 | Bad Request
{
"error": {
"code": 1103,
"message": "The request header should be application/json format, and body should be a valid json."
}
}
PATCH /delivery/update/{shipping_id}/picked (更新包裹狀態)
https://api.tigerfly.tw/delivery/update/{shipping_id}/picked
Request
- method: PATCH
- route:
- header:
Response
-
200 | OK
{
"is_picked": true,
"shipping_id": "2000065"
}
-
404 | 找不到商品
{
"error": {
"code": 1104,
"message": "The shipping_id doesn't exist."
}
}
GET /delivery/status/{shipping_id} (查詢包裹狀態)
https://api.tigerfly.tw/delivery/status/{shipping_id}
Request
- method: GET
- route:
- header:
Response
-
200 | OK
{
"is_picked": true,
"is_clicked": false,
"payload": {
"order_id": "CVS0001",
"phone_number": "0912000111",
"email": "test@examples.com",
"shipping_id": "20000",
"cvs_type": "1",
"cvs_store_name": "林安門市",
"cvs_store_no": "200065",
"delivery_time": "2019-06-05 19:30:00"
},
"create_time": "2019-06-06 12:00:00",
"update_time": "2019-06-06 12:00:00"
}
-
404 | 找不到商品
{
"error": {
"code": 1104,
"message": "The shipping_id doesn't exist."
}
}
Report (報表)
GET /report/tfam/failed (系統信失敗名單)
https://api.tigerfly.tw/report/tfam/failed
預設提供前一天的失敗名單
Request
- method: GET
- header:
- param:
- start 開始日期 (yyyy-mm-dd 格式) 例: 2019-07-30 (最多能查詢三個月內的資料)
- end 結束日期 (yyyy-mm-dd 格式) 例: 2019-06-01 [required if start given]
Response
- 200 | OK
[
{
"subject": "some_subject",
"time": "2019-06-10T15:06:34+0800",
"to_email": "example@example.com",
"from_email": "info@em.tigerflyapp.tw",
"status": "Failed"
},
{
"subject": "some_subject",
"time": "2019-06-19T15:06:34+0800",
"to_email": "example@example.com",
"from_email": "info@em.tigerflyapp.tw",
"status": "Failed"
},
{
"subject": "some_subject",
"time": "2019-06-19T15:06:34+0800",
"to_email": "example@example.com",
"from_email": "info@em.tigerflyapp.tw",
"status": "Bounced"
}
]
Audience (名單上傳)
POST /audience/tfm (行銷信名單上傳)
Request
- method: POST
- header:
- data:
- name [required] (the upload list name)
- lists [required] (in json format)
- example
[
{
"email" : "abcdefg@awoo.com.tw",
"vars" : [
"va1",
"va2",
"va3",
"va4",
"va5"
]
},
{
"email" : "higklmn@awoo.com.tw",
"vars" : [
"vb1",
"vb2",
"vb3",
"vb4",
"vb5"
]
}
]
Response
POST /audience/tfs (行銷簡訊名單上傳)
Request
- method: POST
- header:
- data:
- name [required] (the upload list name)
- lists [required] (json format)
- example
[
{
"phone" : "0900000000",
"vars" : [
"va1",
"va2",
"va3",
"va4",
"va5"
]
},
{
"phone" : "0900000001",
"vars" : [
"vb1",
"vb2",
"vb3",
"vb4",
"vb5"
]
}
]`
Response
Tfam (系統信)
POST /tfam/send (系統信發送)
Request
- method: POST
- header:
- data:
- data [required] (json format)
- example
{
"from": "example@tigerfly.com",
"from_displayname": "example",
"to": [
{
"name": "to",
"email": "to@tigerfly.com"
}
],
"cc": [
{
"name": "cc",
"email": "cc@tigerfly.com"
}
],
"bcc": [
],
"subject": "主旨",
"body": "",
"htmlbody": "<!doctype html><html><head><meta charset='utf-8'><title>標題</title></head><body>內容</body></html>",
"campaign": "campaign"
}
from
寄件者不可使用免費信箱
from_displayname
寄件者名稱限制 100 字
to
收件者最多 5 個
cc
副本最多 5 個
bcc
密件副本最多 5 個
subject
主旨限制 100 字
campaign
限制 255 字元
- file[] (file)
- 檔名上限 50 個字
- 附加檔案數量上限為 10 個
- 附加檔案大小總上限為 50 MB
Response
- 200 | OK
{
"result": true
}
Client-Users (會員)
POST /client-users (批次新增/更新會員)
Request
- method: POST
- header:
- data:
-
schema
user_id
自定義的會員ID,每一位會員的ID應唯一 必填
email
會員的信箱 必填
name
會員名稱
phone_number
會員手機號碼
-
examples
[
{
"user_id": "U1",
"email": "test1@example.com",
"name": "test1",
"phone_number": "0900000000"
},
{
"user_id": "U2",
"email": "test2@example.com",
"name": "test2",
"phone_number": "0900000000"
}
]
Response
- 200 | OK
{
"insert_count": 2,
"update_count": 0,
"errors": []
}
- 200 | If there are some invalid data
{
"insert_count": 0,
"update_count": 0,
"errors": [
{
"index": "0",
"data": "{\"email\":\"test1@example.com\",\"name\":\"test1\",\"phone_number\":\"0900000000\"}",
"message": {
"user_id": [
"user_id can not be empty"
]
}
},
{
"index": "1",
"data": "{\"user_id\":\"U2\",\"name\":\"test2\",\"phone_number\":\"0900000000\"}",
"message": {
"email": [
"email can not be empty"
]
}
}
]
}
GET /client-users/{user_id} (單筆查詢會員)
Request
Response
- 200 | OK
{
"users": [
{
"user_id": "U1",
"email": "test1@example.com",
"name": "test1",
"phone_number": "886900000000"
}
]
}
- 200 | If the user not exists
{
"users": [
{
"user_id": "U1",
"error": {
"code": "1104",
"message": "User not found"
}
}
]
}
Request
- method: GET
- header:
- data:
Response
- 200 | OK
{
"users": [
{
"user_id": "U1",
"email": "test1@example.com",
"name": "test1",
"phone_number": "886900000000"
},
{
"user_id": "U2",
"email": "test2@example.com",
"name": "test2",
"phone_number": "886900000000"
}
]
}
- 200 | If there are some users not exist
{
"users": [
{
"user_id": "U1",
"error": {
"code": "1104",
"message": "User not found"
}
},
{
"user_id": "U2",
"email": "test2@example.com",
"name": "test2",
"phone_number": "886900000000"
}
]
}
Client-Products (產品)
POST /client-products (批次新增/更新產品)
Request
- method: POST
- header:
- data:
-
schema
product_id
自定義的產品ID,每一位產品的ID應唯一 必填
title
產品名稱 必填
product_url
產品連結 必填
image_url
產品圖片連結 必填
-
examples
[
{
"product_id": "P1",
"title": "test1",
"product_url": "https://www.example.com/P1",
"image_url": "https://img.example.com/P1.jpg"
},
{
"product_id": "P2",
"title": "test2",
"product_url": "https://www.example.com/P2",
"image_url": "https://img.example.com/P2.jpg"
}
]
Response
- 200 | OK
{
"insert_count": 2,
"update_count": 0,
"errors": []
}
- 200 | If there are some invalid data
{
"insert_count": 0,
"update_count": 0,
"errors": [
{
"index": 0,
"data": "{\"title\":\"test1\",\"product_url\":\"https:\\/\\/www.example.com\\/P1\",\"image_url\":\"https:\\/\\/img.example.com\\/P1.jpg\"}",
"message": {
"product_id": [
"A product ID can't be empty"
]
}
},
{
"index": 1,
"data": "{\"product_id\":\"P2\",\"product_url\":\"https:\\/\\/www.example.com\\/P2\",\"image_url\":\"https:\\/\\/img.example.com\\/P2.jpg\"}",
"message": {
"title": [
"Product title can't be empty"
]
}
}
]
}
GET /client-product/{product_id} (單筆查詢產品)
Request
Response
- 200 | OK
{
"products": [
{
"product_id": "P1",
"title": "test1",
"image_url": "https://img.example.com/P1.jpg",
"product_url": "https://www.example.com/P1"
}
]
}
- 200 | If the product not exists
{
"products": [
{
"product_id": "P1",
"error": {
"code": "1104",
"message": "Product not found"
}
}
]
}
POST /client-product/search (批次查詢產品)
Request
- method: POST
- header:
- data:
Response
- 200 | OK
{
"products": [
{
"product_id": "P1",
"title": "test1",
"image_url": "https://img.example.com/P1.jpg",
"product_url": "https://www.example.com/P1"
},
{
"product_id": "P2",
"title": "test2",
"image_url": "https://img.example.com/P2.jpg",
"product_url": "https://www.example.com/P2"
}
]
}
- 200 | If there are some users not exist
{
"users": [
{
"product_id": "P1",
"error": {
"code": "1104",
"message": "Product not found"
}
},
{
"product_id": "P2",
"title": "test2",
"image_url": "https://img.example.com/P2.jpg",
"product_url": "https://www.example.com/P2"
}
]
}
DELETE /client-product/{product_id} (單筆刪除產品)
Request
Response
POST /client-product/delete (批次刪除產品)
Request
- method: GET
- header:
- data:
Response
Client-Carts (未結購物車)
POST /client-carts (批次新增/更新購物車)
Request
- method: POST
- header:
- data:
-
schema
cart_id
自定義的購物車ID,每一位購物車的ID應唯一 必填
customer_id
會員ID 必填
product_id
產品ID 必填
quantity
商品在購物車的數量
price
商品在購物車的價格
currency
參照 ISO 4217 標準,預設為 TWD
-
examples
{
"cart_id": "C1",
"customer_id": "U1",
"products": [
{
"product_id": "P1",
"quantity": "1",
"price": "999",
"currency": "TWD"
},
{
"product_id": "P2",
"quantity": "2",
"price": "999",
"currency": "TWD"
}
]
}
Response
POST /client-carts/search (批次查詢購物車)
Request
- method: POST
- header:
- data:
Response
- 200 | OK
{
"carts": [
{
"cart_id": "C1",
"user_id": "U1",
"products": [
{
"product_id": "P1",
"quantity": 1,
"price": 999,
"currency": "TWD"
},
{
"product_id": "P2",
"quantity": 2,
"price": 999,
"currency": "TWD"
}
]
},
{
"cart_id": "C2",
"user_id": "U2",
"products": [
{
"product_id": "P1",
"quantity": 1,
"price": 999,
"currency": "TWD"
},
{
"product_id": "P2",
"quantity": 2,
"price": 999,
"currency": "TWD"
}
]
}
]
}
- 200 | If there are some carts not exist
{
"carts": [
{
"cart_id": "C1",
"user_id": "U1",
"products": [
{
"product_id": "P1",
"quantity": 1,
"price": 999,
"currency": "TWD"
},
{
"product_id": "P2",
"quantity": 2,
"price": 999,
"currency": "TWD"
}
]
},
{
"cart_id": "C2",
"error": {
"code": "1104",
"message": "Cart not found"
}
}
]
}
DELETE /client-carts/{cart_id} (單筆刪除購物車)
Request
Response
Code reference
Tfas Status Code
Code |
Description |
0 |
Sent to service provider |
1 |
Service provider accepted |
2 |
Delivered to the phone |
3 |
The number can’t be undelivered |
4 |
Expired |
5 |
Error |
99 |
Undefined |
Error Code
HTTP Code
Code |
Description |
400 |
Invalid parameters or body content |
401 |
Authentication failed |
404 |
Resource not found |
429 |
Too many requests |
500 |
Server error |
Detail Error Code
Code |
Description |
400 |
Invalid parameters or body content for general cases |
1101 |
Empty field |
1102 |
Field exceeded the maximum size limit |
1103 |
Invalid request format |
1104 |
Not found |
1106 |
Too many requests |
1201 |
User upload quota runs out |
Global error response
Tigerfly API Documents
API Domain: https://api.tigerfly.tw/
User Authentication (身分驗證)
使用者身分的驗證,是以
Authorization
當作欄位,並且使用Bearer {access_token}
的組合附加在每次的請求的 header 上,以確認使用者的身分。例如 access token 為2bf1efe7cc51f6eh5ad1c98f05y9s34463ca85ad
,那麼在 header 中的格式為Authorization:Bearer 2bf1efe7cc51f6eh5ad1c98f05y9s34463ca85ad
。Tfas (系統簡訊)
POST /tfas/send (系統簡訊發送)
https://api.tigerfly.tw/tfas/send
Request
202004-notification
curl --location --request POST 'https://api.tigerfly.tw/tfas/send' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Bearer {token}' \ --data-urlencode 'data=[ { "id": 1, "number": "0900000000", "content": "test 1", "callback_url": "https://example.com/callback" }, { "id": 2, "number": "0900000000", "content": "test 2", "callback_url": "https://example.com/callback" } ]' \ --data-urlencode 'campaign=202004-notification'
curl --location --request POST 'https://api.tigerfly.tw/tfas/send' \ --header 'Authorization: Bearer {token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "data": [ { "id": 1, "number": "0900000000", "content": "test 1", "callback_url": "https://example.com/callback" }, { "id": 2, "number": "0900000000", "content": "test 2", "callback_url": "https://example.com/callback" } ], "campaign": "202004-notification" }'
Response
200 | OK
400 | Bad Request
Callback
You will be notified when the status changed if
callback_url
given.parameters
07f67d51c8802cc550ae85972798fa5b
20190101000000
example:
POST /tfas/search (系統簡訊查詢)
https://api.tigerfly.tw/tfas/search
Request
Response
200 | OK
400 | Bad Request
GET /tfas/report (系統簡訊報表)
https://api.tigerfly.tw/tfas/report
Request
Response
200 | OK
400 | Bad Request
Delivery (超商未取貨)
POST /delivery/upload (上傳未取貨名單)
https://api.tigerfly.tw/delivery/upload
Request
schema
examples
Response
200 | OK
400 | Bad Request
PATCH /delivery/update/{shipping_id}/picked (更新包裹狀態)
https://api.tigerfly.tw/delivery/update/{shipping_id}/picked
Request
Response
200 | OK
404 | 找不到商品
GET /delivery/status/{shipping_id} (查詢包裹狀態)
https://api.tigerfly.tw/delivery/status/{shipping_id}
Request
Response
200 | OK
404 | 找不到商品
Report (報表)
GET /report/tfam/failed (系統信失敗名單)
https://api.tigerfly.tw/report/tfam/failed
Request
Response
Audience (名單上傳)
POST /audience/tfm (行銷信名單上傳)
Request
Response
POST /audience/tfs (行銷簡訊名單上傳)
Request
Response
Tfam (系統信)
POST /tfam/send (系統信發送)
Request
from
寄件者不可使用免費信箱from_displayname
寄件者名稱限制 100 字to
收件者最多 5 個cc
副本最多 5 個bcc
密件副本最多 5 個subject
主旨限制 100 字campaign
限制 255 字元Response
Client-Users (會員)
POST /client-users (批次新增/更新會員)
Request
schema
user_id
自定義的會員ID,每一位會員的ID應唯一 必填email
會員的信箱 必填name
會員名稱phone_number
會員手機號碼examples
Response
GET /client-users/{user_id} (單筆查詢會員)
Request
Response
POST /client-users/search (批次查詢會員)
Request
Response
Client-Products (產品)
POST /client-products (批次新增/更新產品)
Request
schema
product_id
自定義的產品ID,每一位產品的ID應唯一 必填title
產品名稱 必填product_url
產品連結 必填image_url
產品圖片連結 必填examples
Response
GET /client-product/{product_id} (單筆查詢產品)
Request
Response
POST /client-product/search (批次查詢產品)
Request
Response
DELETE /client-product/{product_id} (單筆刪除產品)
Request
Response
POST /client-product/delete (批次刪除產品)
Request
Response
Client-Carts (未結購物車)
POST /client-carts (批次新增/更新購物車)
Request
schema
cart_id
自定義的購物車ID,每一位購物車的ID應唯一 必填customer_id
會員ID 必填product_id
產品ID 必填quantity
商品在購物車的數量price
商品在購物車的價格currency
參照 ISO 4217 標準,預設為TWD
examples
Response
POST /client-carts/search (批次查詢購物車)
Request
Response
DELETE /client-carts/{cart_id} (單筆刪除購物車)
Request
Response
Code reference
Tfas Status Code
Error Code
HTTP Code
Detail Error Code
Global error response