공통 운영

일반

Q. 검수 환경과 운영 환경이 어떻게 다른가요?

검수와 운영은 별도의 비즈뿌리오 계정으로 운영하는 것을 권장합니다.

Q. 메시지 보관 기간은?

• 비즈뿌리오 서버 메시지 데이터: 35일
• Polling 결과 데이터: 3일 (조회 또는 완료 처리 안 하면 제거)
• RCS 이미지: 365일 (등록일 기준)

Q. 단가/요금 정보는 어디서 확인하나요?

비즈뿌리오 고객센터 또는 사이트 내 [요금 안내] 메뉴 참고.

API 호출

Q. code 1000인데 메시지가 안 와요.

code 1000은 비즈뿌리오 서버 접수 성공을 의미할 뿐, 단말 도달 성공은 아닙니다. 실제 도달 결과는 Webhook 또는 Polling으로 받는 RESULT 코드를 확인하세요 (4100/6600/7000/8000/5000 = 도달 성공).

Q. HTTP 429를 어떻게 다루나요?

RateLimit-Reset 헤더 값만큼 대기 후 재시도. 자세한 패턴은 Rate Limit 다루기 참고.

Q. 토큰 만료 시간을 알 수 있나요?

/v1/token 응답의 expired 필드 (yyyyMMddHHmmss 형식). 만료 1분 전에 재발급하는 것을 권장.

Q. 동일 메시지 키로 두 번 호출하면 어떻게 되나요?

refkey는 고객사가 부여한 식별자일 뿐, 비즈뿌리오에서 중복 체크하지 않습니다. 같은 refkey로 두 번 호출하면 두 건 발송됩니다. 중복 발송을 막으려면 BIZCLIENT 중복 발송 제한 사용 또는 호출 측에서 idempotency 보장.

BIZCLIENT

Q. 한 비즈뿌리오 계정을 여러 BIZCLIENT 모듈에 사용할 수 있나요?

권장하지 않습니다. 결과 리포트가 분산되어 일부 메시지의 결과 매핑이 누락될 수 있습니다. 하나의 모듈에 하나의 계정 원칙.

Q. STATUS = 13이 무엇인가요?

대체 발송이 지정되었으나 비즈뿌리오 ID가 대체 발송 사용 가능 상태가 아닐 때 발생. 비즈뿌리오 고객센터에 대체 발송 사용 신청 필요. 자세한 내용은 BIZCLIENT 발송상태변화 참고.

Q. RCS 발송이 시작되지 않습니다.

기본 설정에서는 RCS 테이블이 자동 생성되지 않습니다. uds.conf에 MESSAGE_SUPPORT_TYPE = ALL을 추가하고 모듈을 재구동하세요. BIZCLIENT 설치 — RCS 활성화 참고.

Q. CMID에 한글을 사용할 수 있나요?

기본은 ASCII 문자만 허용. uds.conf에서 CMID 추가 문자 사용 옵션을 활성화하면 한글·특수문자 사용 가능 (biz_client_v4000 이상). 단, 부분적으로 호환성 이슈 가능성이 있어 ASCII 권장.

Q. STATUS = 0에서 더 이상 진행되지 않습니다.

BIZCLIENT 모듈이 큐를 픽업하지 못한 상태입니다. ① 모듈 구동 여부 확인 (Linux/Unix: 프로세스 / Windows: 서비스 상태), ② uds.conf 의 DB 연결 정보(DBNAME / DBURL / DBUSER / DBPASS) 확인, ③ BIZCLIENT 가 큐 테이블을 폴링할 수 있는 DB 접근 권한 확인.

Q. STATUS = 2인데 CALL_STATUS가 비어 있습니다.

비즈뿌리오 서버가 아직 결과를 회신하지 않은 상태로, 통상 1~5분 내 갱신됩니다. 5분 이상 지연되면 비즈뿌리오 [발송 조회]에서 메시지 상태를 직접 확인하세요.

Q. 결과 리포트가 일부만 반영됩니다.

한 번에 발송한 메시지의 CMID가 중복되면 결과 매핑이 일부 누락될 수 있습니다. CMID는 트랜잭션마다 유일한 값을 사용하세요. 동일 계정을 여러 모듈에 세팅한 경우에도 리포트가 분산되므로 한 모듈 = 한 계정 원칙을 지키세요.

Q. Microsoft SQL Server를 사용합니다. 추가 설정이 있나요?

uds.conf에서 DBNAME = MSSQL2005로 설정하고(2008 이상도 동일), lib/jdbc/의 JDBC 드라이버를 사용 중인 SQL Server 버전에 맞게 교체하세요(기본 드라이버는 낮은 버전).

Q. BIZCLIENT 운영 시 권고 사항이 있나요?

• 하나의 모듈에는 하나의 비즈뿌리오 계정만 세팅하세요 (결과 리포트 분산 방지).
• DBMS 버전 업그레이드 시 lib/jdbc/ JDBC 드라이버도 함께 교체하세요.
• 정기 점검 시 로그 테이블(BIZ_LOG_YYYYMM 등) 용량을 모니터링하세요 (월별 누적).
• 백업 옵션(RCS_BACKUP_OPTION, ATTACHMENTS_BACKUP_OPTION) 동작에 따라 데이터 보관 정책이 달라집니다.

카카오 비즈메시지

Q. 알림톡과 브랜드메시지 중 무엇을 써야 하나요?

Q. 알림톡 본문이 1000자가 넘으면?

API 규격서는 1300자, BIZCLIENT 매뉴얼은 1000자로 표기되어 있습니다. 보수적인 1000자 기준을 권장하며, 초과 시 코드 7314 (메시지 길이 제한 초과) 발생.

Q. 브랜드메시지 발송 시간 제약이 있나요?

08:00 ~ 20:50 KST (광고성 메시지). 21시 이후 또는 8시 이전 발송 시 코드 7322 발생. 해외 사용자는 시간 제한 없음.

Q. 알림톡 템플릿 검수 기간은?

평균 영업일 1~3일. 템플릿 등록 후 /v3/kakao/template/request로 검수 요청 → 카카오 검수.

Q. 발신프로필이 휴면(DMT) 상태입니다.

발신프로필 휴면 해제 API 호출 또는 비즈뿌리오 사이트에서 해제. 휴면 해제 후 30일 미사용 시 재 휴면.

RCS

Q. RCS 메시지가 일부 단말에서 안 와요.

안드로이드 RCS는 채팅+ 지원 단말(Samsung 갤럭시 등)만 수신 가능. iOS와 일부 안드로이드는 통합 RCS(RP* 메시지베이스)를 사용해야 합니다 (iOS 26+, Android 10+).

Q. RCS 이미지를 한 번 업로드한 뒤 계속 사용할 수 있나요?

등록일로부터 365일 사용 가능. 이후 자동 삭제되므로 만료 관리 필요.

Q. RCS 발송 시 agencykey / brandkey가 자꾸 실패합니다.

2023.08.01 이후 잘못된 agencykey / brandkey는 발송 실패 처리됩니다. RBC에서 발급된 정확한 키를 사용하세요. 코드 8970 발생.

발송 결과

Q. Webhook과 Polling 중 무엇을 쓰나요?

기본은 Webhook 권장. 사내망에서 인바운드 통신이 막혀있다면 Polling. 자세한 비교는 전송 결과 수신 가이드 참고.

Q. 결과를 못 받았어요. 어떻게 복구하나요?

POST /v2/report로 결과 재요청. 35일 이내 메시지만 가능.

Q. 발송 후 얼마나 기다려야 결과를 받나요?

5분 이상 결과가 없으면 비즈뿌리오 [발송 조회] 사이트에서 직접 확인.

장애 대응

Q. Webhook 수신 서버가 잠시 다운되면 결과가 유실되나요?

유실되지 않습니다. 비즈뿌리오는 PUSH 실패 시 일정 횟수 재시도한 뒤 결과를 보관합니다. 고객사 서버 복구 후 POST /v2/report로 누락분을 복구하세요 (35일 이내).

Q. BIZCLIENT 모듈이 비정상 종료되면 남은 메시지는 어떻게 처리되나요?

모듈 종료 시점의 STATUS=7(발송 중) 메시지가 남습니다. 모듈을 재구동하면 SEND_VALID_TIME 옵션이 일정 시간 경과한 미발송 메시지를, REMOVE_PRESEND_MSG_OPTION이 STATUS=7 잔존 메시지를 자동 실패 처리합니다. 자세한 옵션은 재시도 정책의 잔존 메시지 처리 참고.

Q. 일시적으로 Rate Limit에 걸리면 어떻게 대응하나요?

HTTP 429 + code 5002 응답 시 RateLimit-Reset 헤더 값만큼 대기한 뒤 재시도하세요. 빈번하게 발생하면 한도 상향을 신청하거나 호출을 분산합니다.

Q. 토큰이 만료되어 호출이 실패하면?

code 3002 / 3005 응답 시 /v1/token으로 새 토큰을 발급받아 동일 요청을 1회 재시도하세요.

채널 선택

Q. 처음 연동할 때 어떤 채널부터 추천하나요?

1. SMS — 가장 단순, 모든 단말에 도달
2. LMS / MMS — 본문 길거나 이미지 필요 시
3. 알림톡 — 카카오톡 사용자 대상 정보성 (단가 저렴)
4. 브랜드메시지 — 마케팅
5. RCS — 풍부한 표현이 필요한 경우

Q. 채널을 자동으로 골라주는 기능이 있나요?

대체 발송으로 비슷한 효과를 얻을 수 있습니다. 예: 알림톡 본 발송 → 카카오톡 미사용 단말은 SMS로 자동 대체. 자세한 내용은 대체 발송 가이드 참고.

발신 IP 화이트리스트 (API)

비즈뿌리오 API는 계정별로 접속 허용 IP가 사전 등록되어 있어야 합니다. 미등록 IP에서 호출하면 다음 코드로 거부됩니다.

등록 방법

비즈뿌리오 사이트의 [내 정보] → [API 관리] 메뉴 또는 고객센터로 다음 정보 전달:

• 비즈뿌리오 계정 (bizId)
• 등록할 IP / IP 대역
• 운영 / 검수 환경 구분

NOTE: 검수 vs 운영 IP 분리 — 검수(dev-api.bizppurio.com)와 운영(api.bizppurio.com)은 별도 계정으로 운영하는 것을 권장합니다. 각 환경별로 다른 IP를 등록하여 코드/네트워크 격리.

NOTE: API Webhook 수신 URL 등록·운영 권장은 전송 결과 수신 가이드로 통합되었습니다.

BIZCLIENT 방화벽 정책

BIZCLIENT 모듈이 비즈뿌리오 서버로 outbound 통신을 합니다.

WARNING: BIZCLIENT는 양방향 연결을 만들지 않습니다. 모듈이 서버로 outbound 연결만 하면 결과 리포트도 같은 채널로 수신됩니다. 인바운드 방화벽 추가 작업은 불필요.

채널별 추가 등록

BIZAPI 재시도 정책

자세한 코드는 BIZAPI 응답 상태 코드, 백오프 패턴은 Rate Limit 다루기 참고.

BIZCLIENT 잔존 메시지 처리

네트워크 장애·모듈 비정상 종료로 결과 업데이트가 누락된 메시지를 자동으로 처리하는 옵션입니다. BATCH 스레드가 5분 간격으로 동작.

WARNING: 이 옵션을 사용하면 비즈뿌리오 서버 통계와 고객사 DB 통계의 불일치가 발생할 수 있습니다. 운영 정책에 맞게 활성화하세요.

REPORT_RECONFIRM_OPTION (Y/N)

STATUS=1(발송 후 대기) 상태이고 발송 시간이 55시간(WAIT_REPORT_HOUR) 경과한 메시지에 대해 결과 1회 재요청 + STATUS=3로 변경. 이후 발송 시간 기준 3일 이내 결과 미수신 시 실패 처리하여 로그 테이블로 이동.

REMOVE_PRESEND_MSG_OPTION (Y/N)

STATUS=7(발송 중) 상태이고 발송 시간이 3일(CLIENT_TIMEOUT_HOUR) 경과한 메시지를 실패 처리하여 로그 테이블로 이동.

타임아웃 설정

SEND_VALID_TIME (분)

모듈 재구동 / DB 세션 재연결 시 실패 처리할 발송 유효 시간 (대상: SEND_TIME 컬럼).

결과 코드: 9034 (발송 유효시간 만료)

API Webhook 미도달 시 결과 재요청(/v2/report)은 전송 결과 수신 가이드 — 결과 재요청 참고. 자주 발생하는 장애 대응은 FAQ — 장애 대응 참고.