> 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/getting-started.md).

# 1. 시작하기

V5 Java API 클라이언트를 사용해 첫 호출까지 보내는 단계를 안내합니다.

## 1.1 의존성 추가

JAR 파일을 클래스패스에 추가하시면 됩니다.

```bash
# 빌드 (Gradle + Java 11)
cd plantpulse-api
./gradlew build
```

산출물은 `target/` 에 생성됩니다.

| 파일                          | 용도                     |
| --------------------------- | ---------------------- |
| `target/plantpulse-api.jar` | 기존 프로젝트에 의존성과 함께 통합할 때 |

## 1.2 클라이언트 생성

`APIClient_V5` 생성자에 옵션을 직접 전달합니다.

```java
import plantpulse.api.v5.APIClient_V5;

APIClient_V5 client = new APIClient_V5(
        "HTTPS",                                       // 프로토콜: "HTTP" 또는 "HTTPS"
        "100.68.69.41",                                // host
        7443,                                          // port
        "api",                                         // user_id
        "19ba7a54-1132-49f2-967e-3c6f5cd989a0",        // token (api_key 발급용)
        false);                                        // debug

client.connect();          // 인증 + HTTP 클라이언트 초기화

// ... API 호출 ...

client.close();            // 종료
```

### 생성자 파라미터

| 파라미터       | 타입      | 설명                    |
| ---------- | ------- | --------------------- |
| `protocol` | String  | `"HTTP"` 또는 `"HTTPS"` |
| `host`     | String  | 서버 호스트 또는 IP          |
| `port`     | int     | 서버 포트                 |
| `user_id`  | String  | 인증 계정 ID              |
| `token`    | String  | 발급된 토큰 (UUID 형식)      |
| `debug`    | boolean | HTTP 요청·응답 디버그 로그     |

> **인증 흐름**: `connect()` 호출 시 내부에서 `user_id` + `token` 으로 api\_key를 발급받고, 이후 모든 호출에서 그 키를 자동으로 헤더에 포함시킵니다. 사용자가 직접 다룰 필요는 없습니다.

## 1.3 첫 API 호출 — ping & 사이트 목록

```java
import java.util.List;
import plantpulse.api.v5.APIClient_V5;
import plantpulse.api.v5.dto.response.SiteResponseV5;
import plantpulse.api.v5.dto.response.SystemPingResponseV5;

public class FirstCall {
    public static void main(String[] args) throws Exception {

        try (APIClient_V5 client = new APIClient_V5(
                "HTTP", "100.68.69.41", 80, "api",
                "19ba7a54-1132-49f2-967e-3c6f5cd989a0", false)) {

            client.connect();

            // 1) 서버 헬스체크
            SystemPingResponseV5 ping = client.system().ping();
            System.out.println("Server alive: " + ping.isPing()
                + " (v" + ping.getVersion() + ")");

            // 2) 사이트 목록 (typed DTO 리스트)
            List<SiteResponseV5> sites = client.site().list();
            for (SiteResponseV5 s : sites) {
                System.out.println(s.getSite_id() + " — " + s.getSite_name());
            }
        }
    }
}
```

실행 결과:

```
Server alive: true (v5.0)
SITE_00001 — 대전 1공장
SITE_00002 — 천안 2공장
```

## 1.4 try-with-resources 패턴

`APIClient_V5`는 `AutoCloseable`을 구현합니다. **try-with-resources 사용을 권장**합니다.

```java
try (APIClient_V5 client = new APIClient_V5(proto, host, port, user, token, false)) {
    client.connect();
    // ... API 호출 ...
}
// close() 자동 호출 — HTTP 커넥션 정리
```

## 1.5 서비스 13개 한눈에 보기

`connect()` 직후 아래 서비스 메서드로 모든 도메인에 접근할 수 있습니다 (lazy 초기화).

```java
client.system()    // 헬스체크
client.site()      // 사이트(공장)
client.customer()  // 고객
client.employee()  // 직원
client.product()   // 제품
client.asset()     // 자산 계층 (Area → Line → Equipment)
client.opc()       // OPC 데이터 채널
client.tag()       // 태그(데이터 포인트)
client.alarm()     // 알람
client.order()     // 작업지시
client.calendar()  // 일정
client.path()      // 자산 경로
client.flow()      // Flow / Flow Node
```

## 1.6 V5 메서드 시그니처 표준 패턴

모든 도메인 서비스는 일관된 메서드 패턴을 따릅니다. 도메인 이름만 다를 뿐 사용법은 동일합니다.

| 패턴                | 반환 타입               | 실패 시 반환값  | 설명    |
| ----------------- | ------------------- | --------- | ----- |
| `create(req)`     | `*ResponseV5`       | `null`    | 등록    |
| `update(id, req)` | `*ResponseV5`       | `null`    | 전체 수정 |
| `delete(id)`      | `boolean`           | `false`   | 삭제    |
| `get(id)`         | `*ResponseV5`       | `null`    | 단건 조회 |
| `list()`          | `List<*ResponseV5>` | **빈 리스트** | 전체 목록 |
| `exists(id)`      | `boolean`           | `false`   | 존재 여부 |
| `count()`         | `long`              | `0`       | 카운트   |

> ⚠️ **예외가 throw 되지 않습니다.** 통신 오류나 서버 ERROR 응답은 위 표의 안전 기본값으로 반환됩니다. 에러 원인은 로그 또는 `BaseServiceV5.getErrorCode(env)` 로 확인하세요. 상세 내용은 [응답 형식 및 에러 처리](/plantpulse-platform/developer/api-manual/error-handling.md) 참고.

## 1.7 디버그 모드

생성자 마지막 인자를 `true` 로 주면 HTTP 요청·응답이 콘솔에 출력됩니다.

```java
APIClient_V5 client = new APIClient_V5(
        "HTTP", "100.68.69.41", 80, "api", TOKEN, true);  // debug=true
```

출력 예:

```
[V5] GET https://server/api/v5/site headers={api_key=ab****cd}
[V5] response: 200 {"_status":"OK","data":[{"site_id":"SITE_00001",...}]}
```

## 다음 단계

* [도메인 ID 규칙](/plantpulse-platform/developer/api-manual/id-rules.md) — **반드시 다음에 읽어주세요.** ID 접두사 검증이 강제됩니다.
* [응답 형식 및 에러 처리](/plantpulse-platform/developer/api-manual/error-handling.md) — 에러 코드 매핑과 안전한 처리 패턴
* [Site 서비스](/plantpulse-platform/developer/api-manual/site-service.md) — 첫 마스터 데이터 생성