코드를 쓰기 전에 무엇부터 준비하나요?
문자발송 서비스 보내줘의 API는 승인받은 사이트만 이용할 수 있는 구조입니다. 준비 없이 코드부터 짜면 인증·접근 에러에서 멈추므로 아래 세 가지를 먼저 갖추세요.
| 준비 항목 | 내용 |
|---|---|
| 서비스 사용 승인 | API 사용 승인을 먼저 받습니다. 발급·등록 절차는 고객센터(1644-6537)로 문의합니다. |
| 인증 정보 | 사이트 식별 코드(siteCode)와 사이트 인증 키(siteKey)를 발급받습니다. |
| IP 등록 | 등록된 IP에서만 API를 쓸 수 있습니다. 발송 요청을 보낼 서버의 IP를 미리 등록합니다. |
요청 경로는 모두 /api/로 시작하고, 요청에 쓸 전용 주소는 승인 후 인증 정보와 함께 안내받습니다.
인증과 요청 형식은 어떻게 되나요?
별도의 토큰 발급 없이 모든 요청 헤더에 siteCode와 siteKey 두 값을 담아 보내는 방식이라 초기 연동이 어렵지 않습니다. 요청과 응답은 JSON이며 공통 헤더는 Content-Type: application/json;charset=utf-8, Accept: application/json입니다. GET과 POST를 모두 지원합니다.
연동 4단계
- 잔액과 요금제 코드 확인보내줘는 선불 충전 방식이라 잔액 조회(/api/balance)로 잔여 금액을 확인하고, 요금제 조회(/api/mng-charge-plan)로 발송에 쓸 chargeCode를 확보합니다. 잔액이 부족하면 발송할 수 없습니다.
- 발송 요청(/api/msg-send)POST로 보냅니다. 최상위에 전송 건수(count), 요금제 코드(chargeCode), 수신자별 데이터 배열(contents)을 담습니다.
- 접수 응답 확인정상 접수되면 code 200, message Success 응답이 옵니다.
- 결과 조회(/api/msg-result-gid)발송 때 지정한 gid로 실제 전송 결과를 조회합니다.
contents 배열의 주요 항목
| 항목 | 설명 |
|---|---|
| sendType | 발송 타입. SMS 0, MMS 1, LMS 2, 알림톡 6. 타입 값만 바꿔 다른 채널로 확장할 수 있음 |
| callback / destTel / destName | 발신번호 / 수신번호 / 수신자 이름 |
| msgText | 문자 내용. SMS는 90byte, LMS·MMS는 2000byte |
| scheduleType | 즉시 발송 0, 예약 발송 1 |
| gid | 메시지 그룹을 구분하는 고유 아이디. 결과 조회에 쓰는 핵심 값 |
| nowDate / sendDate | yyyyMMddHHmmss 형식의 날짜 |
요청 성공이 곧 수신 완료는 아닙니다
발송 요청과 결과 조회가 분리된 2단계 구조이기 때문에, 요청 응답만 보고 "보냈다"고 처리하면 실제 실패를 놓칩니다. 결과 조회 응답의 contents 배열에는 메시지별 결과 코드, 상세 코드, 전송 시간이 담기며, 결과 코드는 성공 2000, 실패 1000, 결과 대기 3000으로 구분됩니다. 대기 상태의 의미와 실패 사유별 조치는 문자 전송 실패 원인 5가지와 해결 방법에 정리해 두었습니다.
자주 막히는 에러와 해결
| 코드 | 원인 | 확인할 것 |
|---|---|---|
| 10001 | 허용되지 않은 IP | 요청 서버 IP를 등록했는지 |
| 10002 | 인증받지 않은 클라이언트 | siteCode·siteKey 오타 |
| 10000 | 캐시 잔액 부족 | 충전과 잔액 조회 |
| 10004 | 문자 개수 불일치 | count와 contents 배열 길이가 같은지 |
| 10026 | 잘못된 파라미터 형식 | 날짜가 yyyyMMddHHmmss인지 |
| 결과 4434 | 발신번호 미등록 차단 | 발신번호가 사전 등록되어 있는지 |
초기 실패의 상당수는 IP 미등록과 발신번호 미등록 두 가지에서 시작하니 이 둘부터 점검하세요. 발신번호 등록 규정은 전송자격인증제 안내 글에서 볼 수 있습니다. 상세 규격서와 전용 인증 정보는 계약·승인 후 제공됩니다.
함께 보면 좋은 글
자주 묻는 질문
Q. API를 쓰려면 무엇이 필요한가요?
서비스 사용 승인, 사이트 코드와 사이트 키 같은 인증 정보, 요청을 보낼 서버의 IP 등록이 필요합니다. 세 가지가 준비되지 않으면 인증·접근 에러가 발생합니다.
Q. 발송 요청이 성공했는데 수신 확인은 어떻게 하나요?
발송 요청의 성공 응답은 접수되었다는 뜻입니다. 발송 때 지정한 gid로 결과 조회 API를 호출해 성공·실패·대기 상태를 확인해야 합니다.
Q. 허용되지 않은 IP 에러(10001)가 나면요?
요청을 보내는 서버의 IP가 등록되어 있는지 확인하고 IP를 등록하세요.
Q. 결과가 발신번호 미등록 차단(4434)으로 나오면요?
발신번호가 사전 등록되어 있는지 확인하세요. 등록된 번호로만 문자를 보낼 수 있습니다.
※ 이 글은 보내줘 블로그의 안내 글을 바탕으로 정리했습니다. 원문은 보내줘 블로그에서 볼 수 있습니다.