API 사용 매뉴얼

PlantPulse Java API 클라이언트 라이브러리(plantpulse-api)의 완전한 사용 매뉴얼입니다. 13개 도메인 서비스를 통해 사이트·자산·태그·알람·작업지시 등 플랫폼의 모든 마스터/운영 데이터에 접근할 수 있습니다.

라이브러리 특징

표준 REST — GET/POST/PUT/PATCH/DELETE 메서드를 의미에 맞게 사용
타입 DTO — 모든 요청·응답이 *RequestV5 / *ResponseV5 클래스로 자동 매핑 (JSONObject 수동 파싱 불필요)
탭별 PATCH — Tag의 알람·메타데이터·계산·집계 등 부분 수정 10종 지원
13개 도메인 서비스 — system, site, customer, employee, product, asset, opc, tag, alarm, order, calendar, path, flow
안전한 기본값 — 실패 시 null 또는 빈 리스트 반환 (예외 throw 없음)

이 매뉴얼은 누구를 위한 것인가요? PlantPulse 플랫폼과 Java로 연동하는 외부 시스템(MES, ERP, 자체 대시보드 등)을 개발하시는 분들을 위한 본격 레퍼런스입니다.

영역	안내
처음 시작한다면	1. 시작하기 → 2. 도메인 ID 규칙 → 3. 응답 형식·에러 처리 순으로 읽어주세요.
특정 도메인이 필요하다면	아래 목차에서 해당 서비스(예: Tag, Order)로 바로 이동하시면 됩니다.
REST를 직접 호출한다면	엔드포인트 전체 목록에 URL과 메서드 매핑이 정리되어 있습니다.
워크플로우 예제가 필요하다면	통합 예제 모음에서 엔드투엔드 시나리오를 확인하세요.
AI 어시스턴트를 붙인다면	MCP 서버 — Claude 같은 클라이언트가 태그·알람·자산을 자연어로 조회하고 알람 확인까지 합니다.

진입점: new APIClient_V5(proto, host, port, user, token, debug) → connect()
서비스 13개: client.system(), client.site(), client.customer(), client.employee(), client.product(), client.asset(), client.opc(), client.tag(), client.alarm(), client.order(), client.calendar(), client.path(), client.flow()
타입 DTO 반환: 모든 메서드가 JSONObject 대신 타입 클래스(SiteResponseV5, TagResponseV5 등)를 반환
실패 시 안전 기본값: create/update/get → null, list → 빈 리스트, delete/exists → false, count → 0
에러 응답 추출: BaseServiceV5.getErrorCode(env), getErrorMessage(env), getHttpStatus(env) static 메서드
도메인 ID 검증: 도메인마다 정해진 접두사를 서버가 검사합니다. 층은 접두사가 아니라 asset_type 으로 판단합니다 — 도메인 ID 규칙
베이스 경로: 모든 호출은 /api/v5 하위 엔드포인트