API 문서

단체문자 API를 애플리케이션에 통합하기 위한 완전한 레퍼런스입니다.

Base URL

https://api-2ue64mzmvq-du.a.run.app

🔐 Authentication

모든 API 요청에는 API 키를 사용한 인증이 필요합니다. API 키를 X-API-Key 헤더에 포함하세요.

인증 헤더

X-API-Key: gsms_live_your_api_key_here

API 키 받기: 단체문자 앱을 다운로드하고 계정을 만든 다음 설정 > 개발자 API에서 API 키를 생성하세요.

API 키 형식

●gsms_live_xxxxx프로덕션 (실제 SMS)
●gsms_test_xxxxx테스팅 (샌드박스 모드)

📡 Endpoints

SMS 작업을 위한 사용 가능한 API 엔드포인트입니다.

POST/api/v1/developer/send

한 명 이상의 수신자에게 SMS 메시지 발송

GET/api/v1/developer/status/:batchId

배치의 전달 상태 확인

📤 Send SMS

한 명 이상의 수신자에게 SMS 메시지를 발송합니다. 메시지는 대기열에 추가되고 안드로이드폰에서 발송됩니다.

POST/api/v1/developer/send

요청 본문

recipients

requiredarray

전화번호와 메시지가 포함된 수신자 배열

phone

requiredstring

수신자 전화번호 (E.164 형식 권장: +821012345678)

message

requiredstring

메시지 텍스트 (메시지당 최대 2000자)

응답

{
  "success": true,
  "batchId": "batch_1736416234_a1b2c3",
  "totalCount": 2,
  "estimatedDeliveryTime": "2-5 minutes"
}

코드 예제

curl -X POST https://api-2ue64mzmvq-du.a.run.app/api/v1/developer/send \
  -H "X-API-Key: gsms_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"recipients":[{"phone":"+821012345678","message":"Your verification code is 123456"},{"phone":"+821087654321","message":"Hello! This is a test message."}]}'

📊 Get Status

발송 엔드포인트에서 반환된 batchId를 사용하여 메시지 배치의 전달 상태를 조회합니다.

GET/api/v1/developer/status/:batchId

응답

{
  "success": true,
  "batchId": "batch_1736416234_a1b2c3",
  "status": "completed",
  "totalCount": 10,
  "sentCount": 8,
  "failedCount": 2,
  "createdAt": "2026-01-09T03:30:34.000Z",
  "completedAt": "2026-01-09T03:35:12.000Z"
}

상태 값

pending - 배치 생성됨, 처리 대기 중
processing - 현재 메시지 발송 중
completed - 모든 메시지 성공적으로 발송됨
partial - 일부 메시지 발송됨, 일부 실패
failed - 모든 메시지 발송 실패

코드 예제

curl -X GET https://api-2ue64mzmvq-du.a.run.app/api/v1/developer/status/batch_1234567890 \
  -H "X-API-Key: gsms_live_your_api_key_here"

⚠️ Error Codes

API는 표준 HTTP 상태 코드를 사용하여 성공 또는 실패를 나타냅니다.

401

인증되지 않음

유효하지 않거나 누락된 API 키. X-API-Key 헤더를 확인하세요.

400

잘못된 요청

유효하지 않은 요청 형식. JSON 페이로드와 필수 필드를 확인하세요.

429

너무 많은 요청

속도 제한 초과. 더 많은 요청을 하기 전에 기다리세요.

500

내부 서버 오류

저희 쪽에서 오류가 발생했습니다. 나중에 다시 시도하세요.

⏱️ Rate Limits

공정한 사용을 보장하기 위해 API는 모든 엔드포인트에 속도 제한을 적용합니다.

100

일 메시지 수 (무료 등급)

분당 요청 수

더 높은 한도가 필요하신가요?: 더 높은 한도와 전담 지원이 포함된 엔터프라이즈 플랜은 문의하세요.

도움이 필요하신가요?

빠른 시작 가이드를 확인하거나 일반적인 질문에 대한 FAQ를 찾아보세요.

빠른 시작 가이드