# PINCOBIZ (핑코비즈) SMS · LMS · MMS Open API v1 & Remote MCP

> 핑코비즈(PINCOBIZ)는 대한민국 기업용 대량·알림 문자(SMS 단문, LMS 장문, MMS 포토문자) 발송 플랫폼입니다. 표준 REST JSON API(`https://sms-api.pinco.kr/api/open/v1/*`)와 별도 패키지 설치가 필요 없는 공식 Streamable HTTP Remote MCP를 제공합니다.

## 핵심 기본 정보 (Quick Facts)
- **운영 REST API Base URL**: `https://sms-api.pinco.kr`
- **인증 헤더**: `X-Pinco-Api-Token: pco_...` 또는 `Authorization: Bearer pco_...` (콘솔 `https://sms.pinco.kr/console/openapi` 에서 발급, 최대 15개 공인 IP/CIDR 화이트리스트 지원)
- **메시지 인코딩 · 바이트 기준**: `EUC-KR` 기준 `SMS` ≤ 90 bytes, `LMS` / `MMS` ≤ 2,000 bytes (한글 1자 = 2B, 영문·숫자·공백·줄바꿈 `\n` = 1B)
- **광고성 문자(`purpose: "AD"`) 필수 정책**: KST `08:00 ~ 20:45` 에만 발송·예약 가능, 상단 `(광고)` 및 하단 `무료수신거부 080...` 표기 필수 (`autoFormatAd: true` 지정 시 서버가 자동 부착)
- **예약 발송(`scheduled: true`)**: 현재 시각(KST) 기준 최소 **30분 이후**부터 설정 가능, 발송 예정 **5분 전 이전**까지 취소 및 100% 즉시 환급 가능
- **자동 환급 정산**: 선차감 후 통신사 최종 전송 실패 건은 결과 확정 시 예치금으로 100% 자동 환급
- **분당 호출 제한 (Rate Limit, 1분 고정 윈도우)**:
  - 문자 발송 접수 (`POST /api/open/v1/messages/send`): 토큰당 **분당 300회** (1회 호출 내 다건 동보 가능)
  - 상태·잔액·발신번호·캠페인 조회 및 사전 검증·예약 취소: 토큰당 **분당 30회**
  - MMS 이미지 업로드 (`POST /api/open/v1/mms/images`): 토큰당 **분당 10회**
  - 서버 헬스체크 (`GET /api/open/v1/health`): 공인 IP당 **분당 10회**
  - 한도 초과 시 `HTTP 429` (`error: "RATE_LIMITED"`) + `Retry-After`(초) 헤더 반환

## AI · 자동화 문서 및 스펙 링크
- [원샷 연동 마스터 가이드 (llms-full.txt)](https://sms-mcp.pinco.kr/llms-full.txt): 전체 9종 API 요청·응답 JSON 필드 규격, 13종 표준 오류 코드, 429 재시도 포함 언어별(Spring Boot, Node.js, Python, PHP, Go) 프로덕션 코드 전문
- [OpenAPI 3.1 스펙 (openapi.json)](https://sms-mcp.pinco.kr/openapi.json): GPTs Actions, n8n, Make, Postman 즉시 임포트용 스키마
- [인터랙티브 개발자 센터 & 브라우저 Try-It](https://sms.pinco.kr/developers): 웹 문서 및 실시간 API 호출 플레이그라운드

## 공식 Remote MCP 엔드포인트 (투트랙)
- **국내 IDE 풀기능 Remote MCP**: `https://sms-api.pinco.kr/mcp` (Streamable HTTP, `Authorization: Bearer pco_...` 인증 필수 — 상태·잔액·발신번호 조회, 사전검증, 실발송 `send_message`, 예약취소, 연동 코드 생성 등 8종 제공)
- **글로벌 무인증 도우미 Remote MCP**: `https://sms-mcp.pinco.kr/mcp` (Streamable HTTP, 무인증 — EUC-KR 바이트·KISA 광고 사전 시뮬레이션 `preview_message`, 프레임워크별 연동 코드 생성 `generate_integration_code`, API 스펙 질의 `explain_api_spec` 3종 제공)

## REST Open API v1 엔드포인트 요약 (9종)
- `GET /api/open/v1/health` — 서버 가동 상태 확인 (무인증, 10회/분)
- `GET /api/open/v1/products/status` — 계정·상품(SMS/LMS/MMS)·목적(INFO/AD/ELECTION)별 실시간 발송 가능 여부 및 한도 조회 (30회/분)
- `GET /api/open/v1/balance` — 실시간 가용 예치금 잔액 및 상품별 적용 단가 조회 (30회/분)
- `GET /api/open/v1/sender-numbers` — 사전등록 발신번호 목록·승인 상태·만료일 조회 (30회/분)
- `POST /api/open/v1/messages/preview` — 과금 없는 EUC-KR 바이트·광고문구·수신거부 제외·예상 비용 Dry-Run 검증 (30회/분)
- `POST /api/open/v1/messages/send` — SMS·LMS·MMS 즉시 발송 및 예약 발송 접수 (300회/분)
- `GET /api/open/v1/campaigns/{campaignId}` — 캠페인 진행 상태·전송 성공/실패 건수·자동 환급액 조회 (30회/분)
- `POST /api/open/v1/campaigns/{campaignId}/cancel` — 발송 5분 전 예약 캠페인 취소 및 즉시 전액 환급 (30회/분)
- `POST /api/open/v1/mms/images` — MMS 전용 JPG/JPEG 이미지 업로드 및 `fileId` 발급 (`multipart/form-data`, 10회/분)