bizgo Developers

Agent Overview

Agent는 고객사 시스템과 비즈고 메시지 API를 안정적으로 연결해 주는 자동 발송 프로그램입니다. 고객사 DB에 쌓인 발송 대상을 읽어 메시지를 보내고, 결과 리포트를 다시 수집해 상태를 업데이트합니다.

쉽게 말해, 반복적으로 구현해야 하는 발송/수집/재시도 흐름을 Agent가 대신 처리해 운영 부담을 줄여줍니다. 현재는 단방향 메시지 범위(문자메시지, RCS, 카카오 알림톡, 카카오 브랜드메시지)를 대상으로 제공합니다.

이 문서에서는 Agent를 처음 도입하는 단계부터 설치, 설정, 기능 구성, 운영/점검까지 순서대로 확인할 수 있습니다.

QUICK NAVIGATION

가이드 바로가기

⚙️

환경 설정

메시지·DB·로그 설정 파일

문서 바로가기
🧯

문제 해결

장애 점검 순서와 대응 방법

문서 바로가기

시작하기

기본 처리 흐름

기본 처리 흐름

고객사 영역

고객사 업무 시스템
고객사 RDB 서버 (요청/결과 저장)

Agent 데몬 (고객사 서버 내)

CollectorSenderReceiver

비즈고 영역

비즈고 API 엔드포인트 (`/api/omni`)
비동기 리포트 제공 (Webhook / Polling)

요청 흐름: 고객사 RDB 적재 → Agent(Collector/Sender) → 비즈고 API.

결과 흐름: 비즈고 리포트 → Agent(Receiver) → 고객사 RDB 상태 반영.

  1. 고객사 시스템이 전송 대상 데이터를 DB에 적재합니다.
  2. Collector가 발송 대상을 수집해 Queue에 적재합니다.
  3. Sender가 데이터를 Communication API(/api/omni)로 전송합니다.
  4. Receiver가 리포트를 수신해 상태를 반영합니다.
  5. Migrator가 운영 테이블과 이력 테이블을 정리합니다.

API 키

Agent는 Bizgo API 호출 시 통합 API KEY를 사용합니다. API KEY는 브라우저나 클라이언트 앱에 노출하지 말고, Agent 설정 파일 또는 서버 환경변수에서만 관리해야 합니다.

API 키 발급/확인 절차

  1. 비즈고 회원가입 및 로그인 후 비즈니스 인증을 완료합니다.
  2. 팀스페이스를 선택합니다. 팀스페이스 선택 예시
  3. 팀스페이스 대시보드에서 연동 Key 바로보기 > 연동관리로 이동합니다.
  4. 통합형(API Key)을 복사해 Agent 설정에 적용합니다. 통합형(API Key) 확인/복사 예시

Agent 연동 설정

Base URL

Product(운영)

IP 확인
https://mars.ibapi.kr

Sandbox(테스트)

IP 확인
https://sandbox-mars.ibapi.kr

Sandbox 이용 안내

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

운영 시 체크 포인트

  • API KEY를 교체한 경우 Agent 설정 반영 후 재기동하여 즉시 적용합니다.
  • API KEY 발급 직후 최대 10분 정도 동기화 시간이 필요할 수 있습니다.
  • Sandbox 환경 연동 테스트는 실제 발송되지 않는 가상망에서 수행됩니다.

방화벽 및 보안 프로토콜

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 호출 전 통합형(API Key) 기준으로 호출 서버 IP 등록이 필수입니다.
  • 개발/운영 환경이 분리되어 있으면 각 환경의 공인 IP를 모두 등록합니다.
  • ACL 미등록 IP에서 호출하면 인증/접근 제어 단계에서 차단됩니다.

IP 등록 방법

  1. 비즈고 로그인 후 콘솔 좌측 메뉴에서 발송관리 > 연동관리로 이동합니다.
  2. 통합형(API Key)별 허용 IP를 등록합니다.
  3. 개발/운영 서버 IP를 모두 반영해야 안정적입니다.

ACL IP 등록 화면 예시

Ratelimit

  • API별 초당/분당 호출 수 제한이 적용될 수 있습니다.
  • 제한 초과 시 429 Too Many Requests 또는 동등한 정책 오류가 반환될 수 있습니다.
  • Agent 재시도 간격과 배치 크기를 함께 조정해 안정적으로 운영하는 것을 권장합니다.

보안 체크리스트

  • API KEY는 Vault 또는 서버 환경변수에만 저장합니다.
  • 키 노출 가능성이 있으면 즉시 폐기/재발급합니다.
  • 요청/응답 로그는 민감정보(전화번호, 전문, 인증값)를 마스킹해 저장합니다.
  • 방화벽 아웃바운드 정책은 비즈고 API 도메인/포트만 허용하도록 관리합니다.