1. Tổng quan

1.1 Yêu cầu được giải quyết

1.2 Xác thực

Tất cả endpoint nội bộ yêu cầu xác thực dịch vụ với dịch vụ.

Các endpoint webhook được Twilio gọi (bên ngoài).

2. Định dạng Phản hồi

2.1 Phản hồi Thành công

{
  "success": true,
  "data": { ... },
  "meta": {
    "requestId": "req-abc-123",
    "timestamp": "2026-07-24T10:30:00Z"
  }
}

2.2 Phản hồi Lỗi

{
  "success": false,
  "error": {
    "code": "SMS_SEND_FAILED",
    "message": "Không thể gửi SMS qua nhà cung cấp"
  }
}

3. Endpoints

3.1 Thao tác SMS

POST /sms/send FR-001

Gửi SMS OTP đến số điện thoại. Gọi nội bộ dịch vụ với dịch vụ.

Yêu cầu:

{
  "phone": "+84901234567",
  "message": "Mã xác minh của bạn là: 123456",
  "otpCode": "123456",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "expiresIn": 300
}

Phản hồi 200:

{
  "success": true,
  "data": {
    "id": "sms-uuid-123",
    "status": "sent",
    "providerMessageId": "SM1234567890"
  }
}

POST /sms/verify FR-002

Xác minh mã OTP.

Yêu cầu:

{
  "phone": "+84901234567",
  "otpCode": "123456"
}

Phản hồi 200:

{
  "success": true,
  "data": {
    "verified": true,
    "userId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

GET /sms/:id/status FR-004

Truy vấn trạng thái giao SMS.

Phản hồi 200:

{
  "success": true,
  "data": {
    "id": "sms-uuid-123",
    "status": "delivered",
    "sentAt": "2026-07-24T10:30:00Z",
    "deliveredAt": "2026-07-24T10:30:05Z"
  }
}

3.2 Webhooks

POST /webhooks/sms/delivered FR-003

Callback trạng thái giao dịch từ Twilio. Endpoint webhook bên ngoài.

Yêu cầu (định dạng Twilio):

{
  "MessageSid": "SM1234567890",
  "MessageStatus": "delivered",
  "To": "+84901234567",
  "ErrorCode": null
}

4. Mã lỗi