Atimabox API Public Docs
1. Information:
Version Date Author Desciption
1.0 Aug, 19 2024 MinhHD2 GetAccessToken
GetProfile
AddCustomer
SendBroadcastMessage
2.0 Aug, 27 2024 MinhHD2 UpdateCustomer
SendZNSMessage
Table of Contents
1. Information: ..................................................................................................................... 1
2. Config: ................................................................................................................................... 3
3. API: ....................................................................................................................................... 4
3.1 Authorization Public API ............................................................................................... 4
3.1.1 Request .................................................................................................................... 4
3.1.2 Response ................................................................................................................. 4
3.2 Get profile .................................................................................................................... 4
3.2.1 Request .................................................................................................................... 4
3.2.2 Response ................................................................................................................. 5
3.3 Add customer public api ............................................................................................... 6
3.3.1 Request .................................................................................................................... 6
3.4 Update customer public api .......................................................................................... 8
3.4.1 Request .................................................................................................................... 8
3.5 Send ZNS Message ................................................................................................... 10
3.5.1 Request .................................................................................................................. 10
3.5.2 Response ............................................................................................................... 11
4 Status Codes ................................................................................................................. 11
2. Config:
Key Value Description
Production:[Link]
BASE_URL Base url from Production
Staging: [Link]
Body data of 3.1
app_id XXXX (send via email)
(Authorization Request)
Body data of 3.1
app_secrect XXXX (send via email)
(Authorization Request)
Header of every request to
organization XXXX (send via email)
server
URL Structure: {BASE_URL}/{ENDPOINT}
3. API:
3.1 Authorization Public API
3.1.1 Request
Method POST
URL {BASE_URL}/auth/get-access-token
Header: Content-Type: application/json
organization: string (required)
Body {
"app_id": "string",
"app_secret": "string",
}
3.1.2 Response
Status Response
200
{
“statusCode”: 200,
"data": {accessToken: <jwtToken>}
}
jwtToken (string) - all further API calls must have this key in header
401 {“statusCode”: 401, message":"Unauthorization"}
403 {“statusCode”: 403, message":"Forbidden"}
500 {“statusCode”: 500, message":"Opps! Somethings went wrong."}
3.2 Get profile
3.2.1 Request
Method GET
URL {BASE_URL} /business-customer/get-profile
Header: Content-Type: application/json
authorization: Bearer <Token>
organization: string (required)
Query Params phone: 84XXXXXXX
zalo_id_by_oa: XXXXXXXXX
zalo_id_by_app: XXXXXXXXX
1 of 3 fields required
3.2.2 Response
Status Response
200 {
"statusCode": 200,
"data": {
"address": {},
"_id": "66c304316d9bf9b5d4da9a49",
"name": "Nguyen Van A",
"phone": "84XXXXXX",
"zalo_id_by_app": "XXXXXXXX",
"zalo_id_by_oa": "XXXXXXXX",
"zalo_name": "XXXXXXXX",
"zalo_avatar": "[Link]
"oa_id": "XXXXXXXX",
"extras": {},
"status": 1,
"deleted": false,
"createdAt": "2024-08-14T03:45:36.857Z",
"updatedAt": "2024-08-14T08:19:04.580Z",
"__v": 0
}
}
{“statusCode”: 400, message":"Query params is empty!"}
400
{“statusCode”: 400, message":"Customer profile doesn’t exist"}
401 {“statusCode”: 401, message":"Unauthorization"}
403 {“statusCode”: 403, message":"Forbidden"}
500 {“statusCode”: 500, message":"Opps! Somethings went wrong."}
3.3 Add customer public api
3.3.1 Request
Method POST
URL {BASE_URL}/business-customer/add-customer
Header: Content-Type: application/json
authorization: Bearer <Token>
organization: string (required)
Body {
"oa_id": "string", //Required
"source": "string", //Required
"name": "string", //Required
"zalo_id_by_oa": "string",
"zalo_id_by_app": "string",
"zalo_name": "string",
"phone": "string", //Required
"orgId": "string",
"address": {
"province_name": "string",
"district_name": "string",
"ward_name": "string",
"province_code": "string",
"district_code": "string",
"ward_code": "string",
"street": "string",
"note": "string"
},
"date": "string",
"month": "string",
"year": "string",
“extras”: {
// custom fields
}
}
Body Example {
"oa_id": "XXXXXXXX",
"source": "miniapp",
"name": "Nguyễn Văn A",
"zalo_id_by_oa": "XXXXXXXX",
"zalo_id_by_app": "XXXXXXXX",
"zalo_name": " Nguyễn Văn A ",
"phone": "84XXXXXXXX",
"orgId": "XXXXXXXX",
"address": {
"province_name": "string", (Optional)
"district_name": "string", (Optional)
"ward_name": "string", (Optional)
"province_code": "string", (Optional)
"district_code": "string", (Optional)
"ward_code": "string", (Optional)
"street": "string", (Optional)
"note": "string" (Optional)
},
"date": "string", (Optional)
"month": "string", (Optional)
"year": "string", (Optional)
“extras”: {
// custom fields
}
}
3.4 Update customer public api
3.4.1 Request
Method POST
URL {BASE_URL}/business-customer/update-customer
Header: Content-Type: application/json
authorization: Bearer <Token>
organization: string (required)
Body {
"oa_id": "string",
"source": "string",
"name": "string",
"zalo_id_by_oa": "string",
"zalo_id_by_app": "string",
"zalo_name": "string",
"phone": "string",
"orgId": "string",
"address": {
"province_name": "string",
"district_name": "string",
"ward_name": "string",
"province_code": "string",
"district_code": "string",
"ward_code": "string",
"street": "string",
"note": "string"
},
"date": "string",
"month": "string",
"year": "string",
“extras”: {
// custom fields
}
}
Body Example {
"oa_id": "XXXXXXXX",
"source": "miniapp",
"name": "Nguyễn Văn A",
"zalo_id_by_oa": "XXXXXXXX",
"zalo_id_by_app": "XXXXXXXX",
"zalo_name": " Nguyễn Văn A ",
"phone": "84XXXXXXXX",
"orgId": "XXXXXXXX",
"address": {
"province_name": "string", (Optional)
"district_name": "string", (Optional)
"ward_name": "string", (Optional)
"province_code": "string", (Optional)
"district_code": "string", (Optional)
"ward_code": "string", (Optional)
"street": "string", (Optional)
"note": "string" (Optional)
},
"date": "string", (Optional)
"month": "string", (Optional)
"year": "string", (Optional)
“extras”: {
// custom fields
}
}
3.5 Send ZNS Message
3.5.1 Request
Method POST
URL {BASE_URL}/messaging/send-zns
Header: Content-Type: application/json
authorization: Bearer <Token>
organization: string (required)
Body {
"templateId": "string", //required
"reciptionId: "string",
“dataContext”: {
“customer”: {
“phone”: “string”
}
}
}
// reciptionId & dataContext: 1 of 2 fields required
Body Example {
"templateId": "XXXXXXXXX",
"reciptionId": "XXXXXXXXX" //customer_id
“dataContext”: {
“customer”: {
“phone”: “84XXXXXXXX”
}
}
}
3.5.2 Response
Status Response
200 {“statusCode ": 200, "message”: “Send message success”}
400 {“statusCode”: 400, message":"Send message fail"}
401 {“statusCode”: 401, message":"Unauthorization"}
403 {“statusCode”: 403, message":"Forbidden"}
{“statusCode”: 404, message":"Message template not found"}
404
{“statusCode”: 404, message":"Customer not found"}
500 {“statusCode”: 500, message":"Opps! Somethings went wrong."}
4 Status Codes
All status codes are standard HTTP status codes. The below ones are used in this API.
2XX - Success of some kind
4XX - Error occurred in client’s part
5XX - Error occurred in server’s part
Status Code Description
200 OK
400 Bad request
401 Authentication failure
403 Forbidden
500 Internal Server Error