바른문자 API 연동 가이드

1. 5분 만에 시작하기

1. 로그인 → 대시보드 > API 연동 페이지 이동
2. 새 API Key 발급 버튼 클릭 → 이름(예: “구글시트”) 입력 → 발급
3. 생성된 bmk_live_... 키를 복사해서 안전한 곳에 저장 (이후에는 다시 표시되지 않음)
4. 발신번호를 미리 승인받아 두기
5. 잔액이 있는지 결제 페이지에서 확인
6. 아래 언어/도구별 예제 코드를 복사해서 발송 테스트

2. 구글 스프레드시트 연동 (초보자용)

프로그래밍 지식 없이, 스프레드시트에서 버튼 한 번으로 대량 발송을 할 수 있습니다.

📋 Apps Script 전체 코드 (그대로 복사)

/**
 * 바른문자 API 연동 (Google Apps Script)
 * 스프레드시트 메뉴 > 확장 프로그램 > Apps Script 에 붙여넣기
 */

// ⚠️ 본인의 API Key로 교체하세요
const BARUN_API_KEY = 'bmk_live_여기에_발급받은_키_붙여넣기';
const BARUN_BASE = 'https://barunsms.com/api/v1';

/**
 * 문자 한 건 보내기 (셀 함수로 사용 가능)
 * 사용: =sendSMS("010-1234-5678", "안녕하세요", "070-0000-0000")
 */
function sendSMS(phone, message, senderId) {
  const res = UrlFetchApp.fetch(BARUN_BASE + '/messages/send', {
    method: 'post',
    contentType: 'application/json',
    headers: { 'Authorization': 'Bearer ' + BARUN_API_KEY },
    payload: JSON.stringify({
      senderId: senderId,
      to: phone,
      message: message,
    }),
    muteHttpExceptions: true,
  });
  const data = JSON.parse(res.getContentText());
  if (data.error) return '❌ ' + data.error;
  return '✅ 발송완료 (잔액 ' + data.balance.toLocaleString() + '원)';
}

/**
 * 시트 전체 일괄 발송
 *   A열: 전화번호
 *   B열: 메시지 (비워두면 C1 셀의 공통 메시지 사용)
 *   상단 스크립트 메뉴 > 일괄 발송 실행
 */
function sendFromSheet() {
  const sheet = SpreadsheetApp.getActiveSheet();
  const senderId = sheet.getRange('D1').getValue(); // D1 셀에 발신번호
  const commonMsg = sheet.getRange('C1').getValue(); // C1 셀에 공통 메시지
  const lastRow = sheet.getLastRow();

  if (!senderId) { SpreadsheetApp.getUi().alert('D1 셀에 승인된 발신번호를 입력하세요.'); return; }

  // 번호 목록 만들기 (개별 메시지 사용 여부로 분기)
  const recipients = [];
  for (let r = 2; r <= lastRow; r++) {
    const phone = sheet.getRange(r, 1).getValue();
    const msg = sheet.getRange(r, 2).getValue() || commonMsg;
    if (phone && msg) recipients.push({ phone: String(phone), msg: String(msg) });
  }
  if (recipients.length === 0) { SpreadsheetApp.getUi().alert('발송할 번호가 없습니다.'); return; }

  // 메시지가 전부 동일하면 한번에, 다르면 건별로
  const uniqueMessages = [...new Set(recipients.map(r => r.msg))];

  if (uniqueMessages.length === 1) {
    // 공통 메시지 → 1회 API 호출로 일괄 발송
    const res = UrlFetchApp.fetch(BARUN_BASE + '/messages/send', {
      method: 'post',
      contentType: 'application/json',
      headers: { 'Authorization': 'Bearer ' + BARUN_API_KEY },
      payload: JSON.stringify({
        senderId: senderId,
        to: recipients.map(r => r.phone),
        message: uniqueMessages[0],
      }),
      muteHttpExceptions: true,
    });
    const data = JSON.parse(res.getContentText());
    SpreadsheetApp.getUi().alert('발송 결과: ' + JSON.stringify(data, null, 2));
  } else {
    // 건별 메시지 → 하나씩 발송
    let success = 0, fail = 0;
    recipients.forEach((r, i) => {
      sheet.getRange(i + 2, 5).setValue('발송중...'); // E열에 상태 기록
      const res = UrlFetchApp.fetch(BARUN_BASE + '/messages/send', {
        method: 'post',
        contentType: 'application/json',
        headers: { 'Authorization': 'Bearer ' + BARUN_API_KEY },
        payload: JSON.stringify({
          senderId: senderId,
          to: r.phone,
          message: r.msg,
        }),
        muteHttpExceptions: true,
      });
      const data = JSON.parse(res.getContentText());
      if (data.error) {
        sheet.getRange(i + 2, 5).setValue('❌ ' + data.error);
        fail++;
      } else {
        sheet.getRange(i + 2, 5).setValue('✅ 완료');
        success++;
      }
      Utilities.sleep(100); // rate limit 완화
    });
    SpreadsheetApp.getUi().alert('발송 완료\n성공: ' + success + '건\n실패: ' + fail + '건');
  }
}

/** 잔액 조회 */
function checkBalance() {
  const res = UrlFetchApp.fetch(BARUN_BASE + '/balance', {
    headers: { 'Authorization': 'Bearer ' + BARUN_API_KEY },
    muteHttpExceptions: true,
  });
  const data = JSON.parse(res.getContentText());
  SpreadsheetApp.getUi().alert('현재 잔액: ₩' + data.balance.toLocaleString() +
    '\n요금제: ' + data.pricingPlan +
    '\nSMS: ' + data.unitPrices.sms + '원');
}

/** 메뉴 추가 — 스프레드시트 열 때 자동 실행 */
function onOpen() {
  SpreadsheetApp.getUi().createMenu('바른문자')
    .addItem('📨 시트 전체 일괄 발송', 'sendFromSheet')
    .addItem('💰 잔액 조회', 'checkBalance')
    .addToUi();
}

3. API 엔드포인트

모든 요청은 HTTPS여야 하며, Authorization: Bearer bmk_... 헤더가 필요합니다.

{
  "senderId": "070-0000-0000",        // 승인된 발신번호
  "to": "010-1234-5678",              // 또는 배열: ["010-...", "010-..."]
  "message": "안녕하세요",
  "title": "선택 (LMS일 때 표시)",
  "scheduledAt": "2026-05-01T10:00:00+09:00"  // 선택 — 예약 발송
}

{
  "success": true,
  "messageId": "sendon_1714521600_xxx",
  "type": "SMS",
  "recipients": 1,
  "sent": 1,
  "failed": 0,
  "unitPrice": 9,
  "cost": 9,
  "balance": 99991
}

{
  "balance": 99991,
  "pricingPlan": "기본",
  "unitPrices": { "sms": 9, "lms": 27, "mms": 50, "rcs": 30 }
}

{
  "senders": [
    { "phoneNumber": "070-0000-0000", "status": "VERIFIED", "createdAt": "..." }
  ]
}

4. 언어별 예제

cURL

curl -X POST https://barunsms.com/api/v1/messages/send \
  -H "Authorization: Bearer bmk_live_xxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "senderId": "070-0000-0000",
    "to": "010-1234-5678",
    "message": "안녕하세요, 바른문자입니다."
  }'

Python

import requests

API_KEY = 'bmk_live_xxxxxxxxxxx'
resp = requests.post(
    'https://barunsms.com/api/v1/messages/send',
    headers={'Authorization': f'Bearer {API_KEY}'},
    json={
        'senderId': '070-0000-0000',
        'to': ['010-1111-2222', '010-3333-4444'],
        'message': '안녕하세요, 바른문자입니다.',
    },
)
print(resp.json())

5. 자주 묻는 질문