API Reference

SmartX SMS API

본인 Android 폰의 SIM으로 문자를 발송하는 REST API입니다. 모든 응답은 { success, data } 봉투 형식입니다. API 키는 콘솔의 API Key 관리에서 발급하세요.

인증

모든 /api 요청에 Bearer 토큰으로 API 키를 보냅니다. 키는 부여된 계정의 플랜·크레딧·레이트리밋을 그대로 따릅니다.

Authorization: Bearer sk_live_...

엔드포인트

POST/api/send

문자 1건 발송. 실패 시 4xx/5xx와 함께 success:false가 반환되고, 디바이스 오프라인 등 재시도 가능한 오류는 큐에 남아 온라인 복귀 시 자동 재시도됩니다.

{
  "to": "+821012345678",        // 필수. 국내 번호는 010-1234-5678도 가능
  "body": "안녕하세요 {이름}님",  // SMS 필수. {이름}·{전화번호} 등 변수 치환 지원
  "deviceId": "abc123",          // 발송에 쓸 디바이스
  "simName": "SIM1",             // 디바이스 내 SIM 이름
  "scheduledAt": "2026-01-02T09:00:00Z",  // 선택. 미래 시각이면 예약 발송
  "vars": { "이름": "홍길동" }   // 선택. 치환 변수 값
}
// attachments 배열을 넣으면 MMS로 발송 (url + mimeType, 최대 10건)

POST/messages/bulk-send

대량 발송 (콘솔 JWT 인증). 수신자당 vars를 달면 개인화 발송이 됩니다. 수신거부 등록 번호는 자동으로 blocked 처리됩니다.

{
  "deviceId": "abc123",
  "simName": "SIM1",
  "body": "{이름}님 {날짜} 예약 확인되었습니다.",
  "scheduledAt": null,
  "recipients": [
    {
      "normalizedPhoneNumber": "+821012345678",
      "displayName": "홍길동",
      "vars": { "날짜": "1월 15일" }
    }
  ]
}

GET/messages?status=&limit=&startAfter=

GET/messages/received?limit=&startAfter=

수신 문자 조회. 폰으로 온 답장이 서버에 기록됩니다.

GET/messages/stats?days=30

발송 통계 — 합계, 성공률, 일별·디바이스별 분산.

POST/messages/:id/cancel

scheduled 상태 메시지 취소 → cancelled.

POST/messages/resend-failed

failed 상태 메시지 일괄 재발송 (최대 500건).

수신 웹훅

콘솔 → 웹훅 메뉴에서 https URL을 등록하면 수신 문자가 실시간으로 POST됩니다. 헤더 x-smartx-signature는 발급된 시크릿으로 본문을 HMAC-SHA256 서명한 값입니다. 5xx/타임아웃 시 1회 재시도합니다.

POST {등록한 URL}
Content-Type: application/json
x-smartx-signature: sha256=<hmac>

{ "event": "sms.received", "data": { "from": "...", "body": "...", "simName": "...", "deviceId": "...", "receivedAt": "..." } }

에러와 한도

400 입력 검증 실패 — details 필드에 필드별 오류
401/403 인증 실패 또는 소유하지 않은 리소스
402 크레딧 부족
429 플랜 레이트리밋 초과 (분당/일일 발송 한도)
503 디바이스 오프라인 — retryable로 큐에 남아 자동 재시도