API Overview

비즈고 API 연동을 시작하기 전에 먼저 확인해야 할 공통 가이드입니다.
이 페이지에서는 API Key 발급, Base URL, 인증 헤더, 요청/응답 본문 구조, 방화벽 및 보안 설정까지 한 번에 정리합니다.

QUICK NAVIGATION

API 가이드 바로가기

STEP 1

🧭

공통가이드

처음 연동 순서대로 확인

💬

커뮤니케이션 API

채널별 메시지 발송 규격

🔐

인증 API

2FA / 소셜로그인 규격

API 키

API Key는 비즈고 API를 호출하는 주체를 식별하고 인증하는 기본 자격 정보입니다.
브라우저에 직접 노출하지 말고 서버 환경 변수 또는 안전한 시크릿 저장소에 보관해 사용합니다.

API 키 발급 및 확인 절차

비즈고에 로그인한 뒤 비즈니스 인증을 완료합니다.
콘솔에서 사용할 워크스페이스를 선택합니다.
워크스페이스 대시보드에서 연동관리로 이동하여 발급된 통합 API Key를 복사해 서버 연동에 사용합니다.

인증 및 기타 헤더 설정

비즈고 API는 HTTPS 기반 REST 호출을 사용합니다.
각 상품별 API는 경로만 달라지고 인증 방식과 기본 헤더 규칙은 공통으로 유지됩니다.

Base URL

Product(운영)

IP 확인

https://mars.ibapi.kr

Sandbox(테스트)

IP 확인

https://sandbox-mars.ibapi.kr

Sandbox 이용 안내

운영과 동일한 API Key를 사용하며, 실제 메시지가 발송되지 않는 테스트 환경입니다. 신규 발급 또는 변경 직후에는 반영까지 최대 10분 정도 걸릴 수 있습니다.

운영/테스트 환경 모두 사전에 허용된 공인 IP에서만 호출할 수 있습니다. 자세한 허용 IP는 방화벽 및 보안 프로토콜에서 확인할 수 있습니다.

요청 헤더

Content-Type: application/json
Authorization: API KEY

요청·응답 본문

요청 본문은 JSON 형식을 사용합니다.
응답 본문은 공통부(common)와 개별부(data)로 나뉘며, 공통부는 인증 및 권한 체크 결과를, 개별부는 실제 상품 API의 처리 결과를 전달합니다.

인코딩 안내

비즈고 API의 기본 인코딩은 UTF-8 입니다.

단, 문자메시지(SMS/LMS/MMS)는 국내 이통사 규격 특성상 EUC-KR 문자를 포함해 발송할 수 있습니다.

요청 본문 구조는 각 상품별 API 규격에 맞춰 구성합니다.
메시지 API는 destinations, messageFlow, ref 같은 공통 필드를 사용하고, 채널별 상세 필드는 각 상품 규격에서 정의합니다.
응답의 common은 API Gateway 공통 결과, data는 실제 상품 처리 결과를 의미합니다.

{
  "destinations": [{ "to": "01000000000" }],
  "messageFlow": [
    {
      "sms": {
        "from": "01000000000",
        "text": "테스트 메시지"
      }
    }
  ],
  "ref": "req-20260331-001"
}

{
  "common": {
    "authCode": "A000",
    "authResult": "Success",
    "infobankTrId": "Infobank-Tracking-Id"
  },
  "data": {
    "code": "A000",
    "result": "SUCCESS",
    "data": {
      "destinations": [
        {
          "to": "01000000000",
          "msgKey": "SMS20260331-000001",
          "code": "A000",
          "result": "Success"
        }
      ]
    },
    "ref": "req-20260331-001"
  }
}

방화벽 및 보안 프로토콜

TLS

모든 API 통신은 HTTPS(TLS)로 제공합니다.
최소 TLS 1.2 이상을 지원합니다.

방화벽 허용 IP

운영 환경

요청 방향(고객 서버 → 비즈고 API)
PORT 443
3.35.80.15, 43.203.83.174, 54.116.59.12
수신 방향(비즈고 Webhook → 고객 서버)
3.37.214.83, 3.39.75.204, 43.200.251.230, 211.115.98.154, 211.115.98.155, 211.115.98.205

Sandbox 환경

요청 방향(고객 서버 → 비즈고 API)
PORT 443
211.115.98.231
수신 방향(비즈고 Webhook → 고객 서버)
211.115.98.231

ACL(IP 접근 제어)

API 호출 시 사용되는 공인 IP는 API Key 기준으로 사전에 등록되어 있어야 합니다.
개발/운영 서버가 분리되어 있다면 각 환경의 공인 IP를 모두 등록합니다.
등록되지 않은 IP에서 호출하면 인증 또는 접근 제어 단계에서 차단됩니다.

IP 등록 방법

비즈고 로그인 후 콘솔 좌측 메뉴에서 발송관리 > 연동관리로 이동합니다.
사용 중인 통합 API Key에 허용할 공인 IP를 등록합니다.
개발/운영 서버 IP를 모두 반영한 뒤 저장합니다.

ACL IP 등록 화면 예시 1

Rate Limit

API별 호출 제한이 적용될 수 있습니다.
제한을 초과하면 429 Too Many Requests 또는 동등한 정책 오류가 반환될 수 있습니다.
대량 발송이나 반복 조회는 지수 백오프 기반 재시도를 권장합니다.

권장 보안 체크리스트

API Key는 서버 환경 변수 또는 시크릿 저장소에만 보관합니다.
로그에는 API Key, 전화번호, 전문 등 민감 정보를 마스킹해 저장합니다.
아웃바운드 방화벽 정책은 비즈고 API 도메인과 허용 포트만 열어 두는 것을 권장합니다.