> For the complete documentation index, see [llms.txt](https://kopens.gitbook.io/plantpulse-platform/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kopens.gitbook.io/plantpulse-platform/developer/api-manual.md). # 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. 시작하기](/plantpulse-platform/developer/api-manual/getting-started.md) → [2. 도메인 ID 규칙](/plantpulse-platform/developer/api-manual/id-rules.md) → [3. 응답 형식·에러 처리](/plantpulse-platform/developer/api-manual/error-handling.md) 순으로 읽어주세요. | | **특정 도메인이 필요하다면** | 아래 목차에서 해당 서비스(예: Tag, Order)로 바로 이동하시면 됩니다. | | **REST를 직접 호출한다면** | [엔드포인트 전체 목록](/plantpulse-platform/developer/api-manual/endpoints.md)에 URL과 메서드 매핑이 정리되어 있습니다. | | **워크플로 예제가 필요하다면** | [통합 예제 모음](/plantpulse-platform/developer/api-manual/examples.md)에서 엔드투엔드 시나리오를 확인하세요. | ## 핵심 개념 * **진입점**: `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 검증**: `SITE_`, `ASSET_`, `OPC_`/`API_`, `TAG_` 접두사 강제 (서버 측 검증기) * **베이스 경로**: 모든 호출은 `/api/v5` 하위 엔드포인트 ## 매뉴얼 목차 ### 시작과 기본 규칙 1. [시작하기 — 클라이언트 생성·연결](/plantpulse-platform/developer/api-manual/getting-started.md) 2. [**도메인 ID 규칙**](/plantpulse-platform/developer/api-manual/id-rules.md) ⭐ 반드시 먼저 읽어주세요 3. [응답 형식 및 에러 처리](/plantpulse-platform/developer/api-manual/error-handling.md) ### 인프라 · 모델 도메인 4. [System 서비스](/plantpulse-platform/developer/api-manual/system-service.md) — 헬스체크 5. [Site 서비스](/plantpulse-platform/developer/api-manual/site-service.md) — 사이트(공장) 마스터 6. [OPC 서비스](/plantpulse-platform/developer/api-manual/opc-service.md) — 데이터 수집 채널 7. [Asset 서비스](/plantpulse-platform/developer/api-manual/asset-service.md) — 자산 계층(Area·Line·Equipment) 8. [Tag 서비스](/plantpulse-platform/developer/api-manual/tag-service.md) — 태그 정의 + 10종 PATCH 9. [Path 서비스](/plantpulse-platform/developer/api-manual/path-service.md) — 자산 경로 조회 ### 운영 도메인 10. [Alarm 서비스](/plantpulse-platform/developer/api-manual/alarm-service.md) — 알람 이벤트 조회 11. [Calendar 서비스](/plantpulse-platform/developer/api-manual/calendar-service.md) — 일정(점검·중단 등) 12. [Order 서비스](/plantpulse-platform/developer/api-manual/order-service.md) — 작업지시 + 라이프사이클 ### 마스터 데이터 13. [Customer 서비스](/plantpulse-platform/developer/api-manual/customer-service.md) — 고객 14. [Employee 서비스](/plantpulse-platform/developer/api-manual/employee-service.md) — 직원 15. [Product 서비스](/plantpulse-platform/developer/api-manual/product-service.md) — 제품 ### 자동화 16. [Flow 서비스](/plantpulse-platform/developer/api-manual/flow-service.md) — Flow / Flow Node 조회 ### 부록 17. [엔드포인트 전체 목록](/plantpulse-platform/developer/api-manual/endpoints.md) — URL 매핑 18. [통합 예제 모음](/plantpulse-platform/developer/api-manual/examples.md) — 엔드투엔드 워크플로 *** 문의: