เทมเพลต&รหัสผู้ส่ง

เอกสารนี้อธิบายเกี่ยวกับ RESTful API ที่เกี่ยวข้องกับการกำหนดค่ารูปแบบและการกำหนดค่าลายเซ็น

ข้อมูลพื้นฐาน

• โดเมน: https://smsapi.engagelab.com
• วิธีการยืนยันตัวตน: Basic Authentication (การเข้ารหัส Base64)
  • รูปแบบ: Authorization: Basic base64(apikey:apisecret)
  • ตัวอย่าง: ทำการเข้ารหัส Base64 บน apikey:apisecret จากนั้นเพิ่ม Authorization: Basic <encoded string> ลงในส่วนหัวของคำขอ
• Content-Type: application/json

รูปแบบการตอบกลับ

การตอบกลับที่สำเร็จ

การตอบกลับที่สำเร็จจะคืนค่าอ็อบเจ็กต์หรืออาร์เรย์ของข้อมูลโดยตรง:

              
              {
  "template_id": "123456789",
  "template_name": "Example Template",
  ...
}

            

หรือการตอบกลับแบบรายการ:

              
              [
  {
    "template_id": "123456789",
    "template_name": "Example Template",
    ...
  }
]

            

การตอบกลับข้อผิดพลาด

รูปแบบการตอบกลับข้อผิดพลาด:

              
              {
  "code": 400,
  "message": "Error message description"
}

            

อินเทอร์เฟซการกำหนดค่ารูปแบบ

1. รับรายการการกำหนดค่ารูปแบบ

คำอธิบายอินเทอร์เฟซ: ดึงรายการการกำหนดค่ารูปแบบทั้งหมดภายใต้ธุรกิจปัจจุบัน

ข้อมูลคำขอ:

• วิธีการ: GET
• เส้นทาง: /v1/template-configs
• การยืนยันตัวตน: จำเป็น

พารามิเตอร์คำขอ: ไม่มี

ตัวอย่างการตอบกลับ:

              
              [
  {
    "template_id": "123456789",
    "template_name": "Order Notification Template",
    "template_type": "utility",
    "template_content": "Your order {order_no} has been shipped and is expected to arrive by {delivery_time}.",
    "country_codes": "CN,US",
    "status": 2,
    "sign_id": "987654321",
    "sign_name": "Company Name",
    "sign_position": 2,
    "sign_status": 2,
    "audit_remark": "",
    "created_time": 1699000000,
    "updated_time": 1699000000
  }
]

            

คำอธิบายฟิลด์การตอบกลับ:

2. รับรายละเอียดการกำหนดค่ารูปแบบ

คำอธิบายอินเทอร์เฟซ: ดึงข้อมูลรายละเอียดเกี่ยวกับการกำหนดค่ารูปแบบโดยใช้รหัสรูปแบบ

ข้อมูลคำขอ:

• วิธีการ: GET
• เส้นทาง: /v1/template-configs/:templateId
• การยืนยันตัวตน: จำเป็น

พารามิเตอร์เส้นทาง:

ตัวอย่างการตอบกลับ:

              
              {
  "template_id": "123456789",
  "template_name": "Order Notification Template",
  "template_type": "utility",
  "template_content": "Your order {order_no} has been shipped and is expected to arrive by {delivery_time}.",
  "country_codes": "CN,US",
  "status": 2,
  "sign_id": "987654321",
  "sign_name": "Company Name",
  "sign_position": 2,
  "sign_status": 2,
  "audit_remark": "",
  "created_time": 1699000000,
  "updated_time": 1699000000
}

            

การตอบกลับข้อผิดพลาด:

• 400: รูปแบบรหัสรูปแบบผิดพลาดหรือไม่มีรูปแบบ
• 500: ข้อผิดพลาดภายในเซิร์ฟเวอร์

3. สร้างการกำหนดค่ารูปแบบ

คำอธิบายอินเทอร์เฟซ: สร้างการกำหนดค่ารูปแบบใหม่

ข้อมูลคำขอ:

• วิธีการ: POST
• เส้นทาง: /v1/template-configs
• การยืนยันตัวตน: จำเป็น

เนื้อหาคำขอ:

              
              {
  "template_name": "Order Notification Template",
  "template_type": "utility",
  "template_content": "Your order {order_no} has been shipped and is expected to arrive by {delivery_time}.",
  "country_codes": "CN,US",
  "add_signature": true,
  "sign_id": "987654321",
  "sign_position": 2
}

            

คำอธิบายฟิลด์คำขอ:

ตัวอย่างการตอบกลับ:

              
              {
  "code": 0,
  "message": "success"
}

            

การตอบกลับข้อผิดพลาด:

• 400: รูปแบบพารามิเตอร์ผิดพลาด การตรวจสอบพารามิเตอร์ล้มเหลว ไม่มีการกำหนดค่าลายเซ็น หรือสถานะลายเซ็นไม่ได้รับการอนุมัติ
• 500: ข้อผิดพลาดภายในเซิร์ฟเวอร์

กฎทางธุรกิจ:

• สถานะของรูปแบบหลังจากการสร้างคือ "รอการตรวจสอบ" (status=1)
• หากเพิ่มลายเซ็น ลายเซ็นต้องอยู่ในสถานะที่ได้รับการอนุมัติ

4. อัปเดตการกำหนดค่ารูปแบบ

คำอธิบายอินเทอร์เฟซ: อัปเดตการกำหนดค่ารูปแบบที่มีอยู่

ข้อมูลคำขอ:

• วิธีการ: PUT
• เส้นทาง: /v1/template-configs/:templateId
• การยืนยันตัวตน: จำเป็น

พารามิเตอร์เส้นทาง:

เนื้อหาคำขอ: เหมือนกับอินเทอร์เฟซการสร้าง ทุกฟิลด์จำเป็น

ตัวอย่างการตอบกลับ:

              
              {
  "code": 0,
  "message": "success"
}

            

การตอบกลับข้อผิดพลาด:

• 400: รูปแบบพารามิเตอร์ผิดพลาด ไม่มีรูปแบบ สถานะรูปแบบอยู่ระหว่างรอการตรวจสอบและไม่สามารถอัปเดตได้ มีแผนที่รอดำเนินการหรือกำลังดำเนินการที่ไม่สามารถอัปเดตได้ ไม่มีการกำหนดค่าลายเซ็น หรือสถานะลายเซ็นไม่ได้รับการอนุมัติ
• 500: ข้อผิดพลาดภายในเซิร์ฟเวอร์

กฎทางธุรกิจ:

• รูปแบบที่อยู่ในสถานะ "รอการตรวจสอบ" ไม่สามารถอัปเดตได้
• หากมีแผนข้อความที่รอดำเนินการหรือกำลังดำเนินการที่ใช้รูปแบบนั้น จะไม่สามารถอัปเดตได้
• หลังจากการอัปเดต สถานะของรูปแบบจะกลับไปเป็น "รอการตรวจสอบ" (status=1)

5. ลบการกำหนดค่ารูปแบบ

คำอธิบายอินเทอร์เฟซ: ลบการกำหนดค่ารูปแบบที่ระบุ

ข้อมูลคำขอ:

• วิธีการ: DELETE
• เส้นทาง: /v1/template-configs/:templateId
• การยืนยันตัวตน: จำเป็น

พารามิเตอร์เส้นทาง:

ตัวอย่างการตอบกลับ:

              
              {
  "code": 0,
  "message": "success"
}

            

การตอบกลับข้อผิดพลาด:

• 400: รูปแบบรหัสรูปแบบผิดพลาด ไม่มีรูปแบบ มีแผนที่รอดำเนินการหรือกำลังดำเนินการที่ไม่สามารถลบได้
• 500: ข้อผิดพลาดภายในเซิร์ฟเวอร์

กฎทางธุรกิจ:

• หากมีแผนข้อความที่รอดำเนินการหรือกำลังดำเนินการที่ใช้รูปแบบนั้น จะไม่สามารถลบได้

API การตั้งค่าลายเซ็น

1. รับรายการการตั้งค่าลายเซ็น

คำอธิบาย API: ดึงรายการการตั้งค่าลายเซ็นทั้งหมดภายใต้ธุรกิจปัจจุบัน

ข้อมูลคำขอ:

• วิธี: GET
• เส้นทาง: /v1/sign-configs
• การยืนยันตัวตน: จำเป็น

พารามิเตอร์คำขอ: ไม่มี

ตัวอย่างการตอบกลับ:

              
              [
  {
    "sign_id": "987654321",
    "sign_name": "ชื่อบริษัท",
    "status": 2,
    "related_template_count": 5,
    "audit_remark": "",
    "created_time": 1699000000,
    "updated_time": 1699000000
  }
]

            

คำอธิบายฟิลด์การตอบกลับ:

2. รับรายละเอียดการตั้งค่าลายเซ็น

คำอธิบาย API: ดึงข้อมูลรายละเอียดของการตั้งค่าลายเซ็นตามรหัสลายเซ็น

ข้อมูลคำขอ:

• วิธี: GET
• เส้นทาง: /v1/sign-configs/:signId
• การยืนยันตัวตน: จำเป็น

พารามิเตอร์เส้นทาง:

ตัวอย่างการตอบกลับ:

              
              {
  "sign_id": "987654321",
  "sign_name": "ชื่อบริษัท",
  "status": 2,
  "related_template_count": 5,
  "audit_remark": "",
  "created_time": 1699000000,
  "updated_time": 1699000000
}

            

การตอบกลับข้อผิดพลาด:

• 400: รูปแบบรหัสลายเซ็นไม่ถูกต้อง, ลายเซ็นไม่มีอยู่, หรือลายเซ็นไม่เป็นของธุรกิจปัจจุบัน
• 500: ข้อผิดพลาดภายในเซิร์ฟเวอร์

3. สร้างการตั้งค่าลายเซ็น

คำอธิบาย API: สร้างการตั้งค่าลายเซ็นใหม่

ข้อมูลคำขอ:

• วิธี: POST
• เส้นทาง: /v1/sign-configs
• การยืนยันตัวตน: จำเป็น

เนื้อหาคำขอ:

              
              {
  "sign_name": "ชื่อบริษัท"
}

            

คำอธิบายฟิลด์คำขอ:

ตัวอย่างการตอบกลับ:

              
              {
  "code": 0,
  "message": "success"
}

            

การตอบกลับข้อผิดพลาด:

• 400: รูปแบบพารามิเตอร์ผิดพลาด, การตรวจสอบพารามิเตอร์ล้มเหลว, หรือชื่อลายเซ็นมีอยู่แล้ว
• 500: ข้อผิดพลาดภายในเซิร์ฟเวอร์

กฎทางธุรกิจ:

• สถานะของลายเซ็นที่สร้างใหม่คือ "รอการตรวจสอบ" (status=1)
• ชื่อลายเซ็นภายใต้ธุรกิจเดียวกันต้องไม่ซ้ำกัน

4. อัปเดตการตั้งค่าลายเซ็น

คำอธิบาย API: อัปเดตการตั้งค่าลายเซ็นที่มีอยู่

ข้อมูลคำขอ:

• วิธี: PUT
• เส้นทาง: /v1/sign-configs/:signId
• การยืนยันตัวตน: จำเป็น

พารามิเตอร์เส้นทาง:

เนื้อหาคำขอ: เหมือนกับ API การสร้าง

ตัวอย่างการตอบกลับ:

              
              {
  "code": 0,
  "message": "success"
}

            

การตอบกลับข้อผิดพลาด:

• 400: รูปแบบพารามิเตอร์ผิดพลาด, ลายเซ็นไม่มีอยู่, ลายเซ็นไม่เป็นของธุรกิจปัจจุบัน, สถานะลายเซ็นอยู่ระหว่างรอการตรวจสอบและไม่สามารถอัปเดตได้, ชื่อลายเซ็นมีอยู่แล้ว, หรือมีแผนที่รอดำเนินการหรือกำลังดำเนินการที่ไม่สามารถอัปเดตได้
• 500: ข้อผิดพลาดภายในเซิร์ฟเวอร์

กฎทางธุรกิจ:

• ลายเซ็นที่อยู่ในสถานะรอการตรวจสอบไม่สามารถอัปเดตได้
• หากมีแผนข้อความที่รอดำเนินการหรือกำลังดำเนินการที่ใช้ลายเซ็นนั้น จะไม่สามารถอัปเดตได้
• หลังการอัปเดต สถานะลายเซ็นจะกลับไปเป็น "รอการตรวจสอบ" (status=1)

5. ลบการตั้งค่าลายเซ็น

คำอธิบาย API: ลบการตั้งค่าลายเซ็นที่ระบุ

ข้อมูลคำขอ:

• วิธี: DELETE
• เส้นทาง: /v1/sign-configs/:signId
• การยืนยันตัวตน: จำเป็น

พารามิเตอร์เส้นทาง:

ตัวอย่างการตอบกลับ:

              
              {
  "code": 0,
  "message": "success"
}

            

การตอบกลับข้อผิดพลาด:

• 400: รูปแบบรหัสลายเซ็นไม่ถูกต้อง, ลายเซ็นไม่มีอยู่, ลายเซ็นไม่เป็นของธุรกิจปัจจุบัน, หรือมีแผนที่รอดำเนินการหรือกำลังดำเนินการที่ไม่สามารถลบได้
• 500: ข้อผิดพลาดภายในเซิร์ฟเวอร์

กฎทางธุรกิจ:

• หากมีแผนข้อความที่รอดำเนินการหรือกำลังดำเนินการที่ใช้ลายเซ็นนั้น จะไม่สามารถลบได้

คำอธิบายรหัสสถานะ

สถานะการตั้งค่าเทมเพลต (status)

สถานะการตั้งค่าลายเซ็น (status)

ตำแหน่งลายเซ็น (sign_position)

ประเภทเทมเพลต (template_type)

คำอธิบายรหัสข้อผิดพลาด

ข้อความข้อผิดพลาดทั่วไป:

• invalid templateId: รูปแบบรหัสเทมเพลตไม่ถูกต้อง
• template config not exist: การตั้งค่าเทมเพลตไม่มีอยู่
• invalid signId: รูปแบบรหัสลายเซ็นไม่ถูกต้อง
• sign config not exist: การตั้งค่าลายเซ็นไม่มีอยู่
• sign_name already exist: ชื่อลายเซ็นมีอยู่แล้ว
• can not update pending status template: เทมเพลตที่อยู่ในสถานะรอการตรวจสอบไม่สามารถอัปเดตได้
• can not update pending status sign: ลายเซ็นที่อยู่ในสถานะรอการตรวจสอบไม่สามารถอัปเดตได้
• there are pending or running plans using current template, can not update: มีแผนที่รอดำเนินการหรือกำลังดำเนินการที่ใช้เทมเพลตปัจจุบัน ไม่สามารถอัปเดตได้
• there are pending or running plans using current sign, can not update: มีแผนที่รอดำเนินการหรือกำลังดำเนินการที่ใช้ลายเซ็นปัจจุบัน ไม่สามารถอัปเดตได้
• sign status is not approved, can not use: สถานะลายเซ็นไม่ได้รับการอนุมัติ ไม่สามารถใช้งานได้

หมายเหตุ

1. API ทั้งหมดต้องการการตรวจสอบสิทธิ์ผ่าน middleware
2. API ทั้งหมดจะเชื่อมโยง ID ธุรกิจ (businessId) ของผู้ใช้ที่ได้รับการตรวจสอบสิทธิ์โดยอัตโนมัติ
3. การสร้างและการอัปเดตสำหรับเทมเพลตและลายเซ็นจะเรียกกระบวนการตรวจสอบ
4. หากเทมเพลตหรือลายเซ็นถูกใช้โดยแผนข้อความ จะไม่สามารถอัปเดตหรือลบได้ในขณะที่แผนอยู่ในสถานะรอดำเนินการหรือกำลังดำเนินการ
5. เนื้อหาเทมเพลตต้องไม่มีอักขระต้องห้าม: 【, 】, ,, test, [, ]
6. ชื่อลายเซ็นต้องไม่มีอักขระต้องห้าม: 【, 】, [, ]
7. รหัสเทมเพลตและลายเซ็นเป็นสตริงตัวเลข