Best Practice

비즈고 API를 프로덕션 환경에서 안정적으로 운영하기 위한 권장 패턴입니다.

1. 항상 Fallback을 설정하세요

카카오, RCS 등 특정 채널만 사용하면 단말 미지원, 채널 장애 시 발송이 완전히 실패합니다.
SMS를 마지막 Fallback으로 항상 포함하는 것을 권장합니다.

"messageFlow": [
  { "kakaoAlimtalk": { ... } },
  { "sms": { "from": "0200000000", "text": "대체 문자" } }
]

2. msgKey를 반드시 저장하세요

발송 응답의 msgKey는 이후 발송 결과 조회, 문의, 재시도에 필요합니다.
DB에 저장하지 않으면 결과를 추적할 수 없습니다.

const response = await sendMessage(payload);
const msgKey = response.data.data.destinations[0].msgKey;

// DB에 저장
await db.messages.insert({ msgKey, ref: payload.ref, status: 'sent' });

3. ref 필드를 활용하세요

ref에 주문 ID, 사용자 ID 등 내부 식별자를 넣으면 발송 결과를 내부 시스템과 연결할 수 있습니다.

{
  "destinations": [{ "to": "01000000000" }],
  "messageFlow": [{ "sms": { ... } }],
  "ref": "order-20260403-001"
}

4. API 키는 서버 환경 변수에만 저장하세요

# .env
BIZGO_API_KEY=your_api_key_here

// 코드에 직접 하드코딩 금지
const apiKey = process.env.BIZGO_API_KEY; // ✓
const apiKey = "실제키값";                // ✗

키가 노출되면 즉시 콘솔에서 폐기하고 재발급하세요.

5. 웹훅은 빠르게 응답하세요

웹훅 수신 서버는 5초 이내에 HTTP 200을 반환해야 합니다.
무거운 처리는 비동기로 분리하세요.

app.post('/webhook/bizgo', async (req, res) => {
  // 즉시 200 응답
  res.status(200).json({ result: 'ok' });

  // 처리는 비동기로
  setImmediate(() => processReport(req.body));
});

6. 중복 발송을 방어하세요

웹훅 재시도로 인해 같은 msgKey의 리포트가 여러 번 수신될 수 있습니다.
msgKey를 기준으로 멱등성(idempotency) 처리를 구현하세요.

async function processReport(report) {
  const exists = await db.reports.findOne({ msgKey: report.msgKey });
  if (exists) return; // 이미 처리된 경우 무시

  await db.reports.insert(report);
  // 후속 처리...
}

7. Sandbox 환경에서 먼저 테스트하세요

프로덕션 발송 전 반드시 Sandbox 환경에서 테스트합니다.

Sandbox Base URL: https://sandbox.ibapi.kr/api/comm
Sandbox 웹훅 발신 IP: 211.115.98.231

8. 발신번호를 사전 등록하세요

미등록 발신번호로 발송하면 이통사에서 차단됩니다.
SMS/LMS/MMS 발송 전 반드시 콘솔에서 발신번호를 등록하세요.

9. 알림톡 템플릿은 미리 준비하세요

알림톡 템플릿 심사는 1~3 영업일이 소요됩니다.
서비스 오픈 일정에 맞춰 미리 등록 신청하세요.

10. 에러 로그에 민감정보를 마스킹하세요

전화번호, 인증번호 등 민감정보는 로그에 마스킹 처리합니다.

function maskPhone(phone) {
  return phone.replace(/(\d{3})\d{4}(\d{4})/, '$1****$2');
}

console.log(`발송 대상: ${maskPhone('01012345678')}`); // 010****5678