Best Practice

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

1. 항상 Fallback을 설정하세요

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

JSON

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

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

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

JavaScript

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 등 내부 식별자를 넣으면 발송 결과를 내부 시스템과 연결할 수 있습니다.

JSON

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

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

Bash

# .env
BIZGO_API_KEY=your_api_key_here

JavaScript

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

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

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

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

JavaScript

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

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

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

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

JavaScript

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-mars.ibapi.kr/api/comm
Sandbox 웹훅 발신 IP: 211.115.98.231

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

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

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

알림톡 템플릿 심사는 영업일 기준 2일 이내 처리됩니다.
서비스 오픈 일정에 맞춰 미리 등록 신청하세요.

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

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

JavaScript

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

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