당신의 서비스에,
그린문자를 연결하세요.

처음 연동하는 순서

1. 계정의 API 키 화면에서 서버용 키를 만듭니다.
2. 예상 차감 건수 조회로 수신 번호와 메시지를 검증합니다.
3. 고유한 요청 키와 함께 발송하고 내역에서 결과를 확인합니다.

https://green-sms.com/api/v1

인증

모든 요청의 Authorization 헤더에 API 키를 전달합니다. API 키는 서버에서만 사용하고 소스 저장소나 브라우저 코드에 노출하지 마세요.

Authorization: Bearer YOUR_GREEN_SMS_API_KEY
Content-Type: application/json

키를 폐기하면 해당 키의 모든 요청이 차단됩니다. 키를 새로 발급한 뒤 서비스 설정을 교체하세요.

예상 차감 건수 조회

발송하지 않고 번호, 문자 인코딩, 메시지 단위와 차감할 문자 건수을 검증합니다.

{
  "recipients": "+821012345678",
  "body": "예약이 확인되었습니다.",
  "sender": "GreenSMS",
  "label": "예약 확인"
}

예상 차감 건수 응답은 최상위 JSON 객체입니다. errors를 확인하세요. recipientCount, parts, messageCount가 계산 결과입니다.

메시지 발송

예상 차감 건수 조회와 같은 본문을 사용합니다. 중복 발송 방지를 위해 Idempotency-Key 헤더에 요청별 고유 값을 반드시 넣어 주세요.

curl -X POST 'https://green-sms.com/api/v1/messages' \
  -H 'Authorization: Bearer YOUR_GREEN_SMS_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-2026-0001' \
  -d '{"recipients":"+821012345678","body":"예약이 확인되었습니다.","sender":"GreenSMS","label":"예약 확인"}'

발송 응답의 data.id와 data.reference를 저장하세요. data.isSimulation이 true이면 실제 발송이 아닌 테스트 처리입니다.

발송 내역 조회

현재 API 키의 계정에 속한 메시지를 응답의 data 배열로 반환합니다. 선택적으로 search와 status 쿼리 값을 사용할 수 있습니다.

GET /api/v1/messages?status=Delivered

처리 대기, 처리 중, 접수 완료, 전달 완료는 서로 다른 단계입니다. 최종 결과가 아직 도착하지 않은 요청을 새 요청 키로 다시 보내지 마세요.

잔여 건수 조회

계정의 현재 발송 가능한 문자을 반환합니다. 웹 발송과 API 발송은 같은 잔여 건수을 사용합니다.

오류와 재시도

오류 응답의 error.code와 error.message를 확인하세요. 입력 오류는 내용을 수정한 뒤 다시 요청해야 합니다.