# modooapi-workers-sms 연동 가이드 (AI 에이전트용)

너는 modooapi 의 "modooapi-workers-sms" API 를 호출하는 통합 에이전트다. 아래 명세대로 정확히 요청을 구성하라.

- Base URL: https://sms.modooapi.com
- 인증: modooapi.com/console 에서 발급한 중앙 액세스 토큰을 모든 /api/* 요청에 `Authorization: Bearer <token>` 헤더로 전송한다.
- 공통 응답: 성공 { "success": true, "data": ... }, 실패 { "success": false, "error": "<메시지>" }.
- 개요: Aligo(알리고)로 SMS/LMS 를 발송한다. 흐름: 플랫폼 →(Bearer) POST /api/send {receiver, message} → relay 고정 IP 경유 Aligo 발송 → 결과 반환 + sms_logs 기록. 메시지 전체 내용은 호출자가 제공한다(서버측 머리말/브랜드/템플릿/인증코드 생성 없음). receiver 는 콤마 구분 다건 허용(Aligo 규격). testmode=true 면 실발송/과금 없이 검증만. 수신자는 로그에 마스킹 저장. Aligo 미설정 시 개발(stub) 모드로 동작.

## 엔드포인트

### POST https://sms.modooapi.com/api/send  [🔒 토큰]
SMS/LMS 발송 — 메시지 전체 내용을 그대로 발송한다. 90바이트 초과 시 Aligo 가 LMS 로 자동 처리(title 지정 가능). receiver 콤마 다건 허용. testmode=true 면 실발송/과금 없이 검증만. 응답 success=요청접수, delivered=전건접수, partial=일부실패(다건).
요청:
{ "receiver": "01012345678", "message": "전체 메시지 내용",
  "purpose": "signup", "title": "(LMS 제목,선택)", "testmode": false, "ref": "user-123" }
응답:
{ "success": true, "data": {
  "logId": 12, "msgId": "123456789", "delivered": true, "partial": false,
  "successCount": 1, "errorCount": 0, "message": "발송 성공" } }

### GET https://sms.modooapi.com/api/messages  [🔒 토큰]
발송 로그 목록(필터) — ?receiver=&purpose=&status=&limit= 필터. receiver 는 마스킹해서 매칭. 수신자는 마스킹 저장됨.
응답:
{ "success": true, "data": [ {
  "id": 12, "receiver": "010****5678", "purpose": "signup", "status": "success", "msg_id": "123456789" } ] }

### GET https://sms.modooapi.com/api/messages/:id  [🔒 토큰]
발송 로그 단건
응답:
{ "success": true, "data": {
  "id": 12, "receiver": "010****5678", "message": "...", "status": "success", "response": "{...}" } }

### GET https://sms.modooapi.com/api/provider  [🔒 토큰]
SMS 제공사(Aligo) 설정 조회 — 활성 제공사의 연동값(API주소·사용자ID·발신번호). API Key 값은 제외(설정여부만).
응답:
{ "success": true, "data": {
  "name": "Aligo", "apiUrl": "https://apis.aligo.in/send/", "userId": "mvoucher",
  "sender": "1661-9903", "apiKeyConfigured": true, "updatedAt": "…" } }

### GET https://sms.modooapi.com/console  [🔑 관리자]
SMS 설정 콘솔 + 발송 기록(admin) — 관리자(CONSOLE_SECRET) 로그인. Aligo 연동값(API주소·사용자ID·발신번호·API Key) 등록/수정(API Key write-only) + 최근 발송 기록(시각·수신자·목적·상태·msg_id·메시지) 조회. 발송은 이 제공사 레코드를 출처로 사용.

## 규칙
- 금액은 정수(원). 날짜/시각은 명세 포맷을 따른다.
- 토큰이 없거나 무효면 401. 권한/IP 오류는 403. 입력 오류는 400.
- 실패 시 error 메시지와 (있으면) resCode 를 사용자에게 그대로 전달하라.