# Ever API · 시작하기

세 단계로 첫 호출을 완료합니다. 모든 오류 응답에는 해결 방법이 함께 담겨 있고, 전체 오류 목록도 바로 확인할 수 있습니다.

## 가장 쉬운 길: 명령줄 (한 줄 설치 · 코드 불필요)

API 를 터미널에서 입력하는 명령으로: 설치 직후 재고 조회와 문서 열람; 스크립트는 `--json`; AI 코딩 에이전트도 그대로 씁니다.

```bash
curl -fsSL https://connect.everugg.net.au/cli/install.sh | sh
ever login --sandbox
ever stock changes AU --since 0
```

쓰기는 --confirm 이 필요하며 항상 초안입니다.

## 아직 인증 정보가 없나요? 샌드박스로 먼저 (가입 불필요 · 데모 데이터)

권한을 기다릴 필요 없습니다. 공개된 sandbox 채널로 전체 흐름을 그대로 테스트할 수 있습니다. 엔드포인트와 응답 형식은 실제와 동일하고 데이터만 데모(DEMO-*)입니다. 실제 재고에는 전혀 영향이 없고, 주문은 가짜 번호만 반환합니다:

```bash
curl -X POST "https://connect.everugg.net.au/api/v1/auth/token" -H "content-type: application/json" \
  -d '{"client_id":"sandbox","client_secret":"sandbox"}'
```

토큰을 받은 뒤 아래 세 단계를 그대로 진행하세요. 샌드박스 응답에는 X-Sandbox: true 헤더가 붙습니다. 테스트가 끝나면 담당자에게 정식 인증 정보를 요청하세요.

## 0. 두 가지가 필요합니다 (담당자가 발급)

채널 번호(예: 100944)와 비밀키(ever_xxxxxxxx… 형태).

비밀키는 발급 시 한 번만 표시됩니다. 서버에는 해시만 저장되어 담당자도 원문을 볼 수 없으니 반드시 안전하게 보관하세요. 분실 시 재발급을 요청하면 됩니다(기존 키는 즉시 무효화).

## 1. 토큰으로 교환하기

```bash
curl -X POST "https://connect.everugg.net.au/api/v1/auth/token" -H "content-type: application/json" \
  -d '{"client_id":"<채널번호>","client_secret":"<비밀키>"}'
```

{"data":{"token":"eyJ…","token_type":"Bearer","expires_in":3600,"expires_at":"…"}} 를 반환합니다. token 이 이후 호출의 열쇠이고 expires_in 은 남은 초입니다. 만료되면 다시 교환하세요.

## 2. 토큰으로 API 호출하기

Authorization: Bearer 헤더에 넣으세요(API 는 ?token= 을 받지 않습니다 — 시크릿과 토큰은 URL 에 넣지 않습니다):

```bash
curl "https://connect.everugg.net.au/api/v1/warehouses" -H "Authorization: Bearer <토큰>"

curl "https://connect.everugg.net.au/api/v1/warehouses/AU/stock?sku=OB0021611" -H "Authorization: Bearer <토큰>"
```

호출 가능한 엔드포인트와 창고는 담당자가 부여한 권한에 따릅니다. 현재 본인의 신원과 권한 확인:

```bash
curl "https://connect.everugg.net.au/whoami" -H "Authorization: Bearer <토큰>"
```

눈으로 보고 싶다면 내 연동에서 역할·기능·웹훅·플랜을 한 페이지로 확인하세요.

## 3. 문제가 생겼을 때

모든 오류 응답에는 error.code / message / hint / request_id / doc_url 이 있습니다 — 먼저 hint(해결 방법)를 보고, 안 되면 request_id 를 담당자에게 보내세요.

> 예: 토큰 누락 → error.code=AUTH_MISSING_TOKEN, hint 가 1단계로 안내합니다.

## 4. 쓰기 요청에는 멱등성 key 를 (중복 주문 방지)

주문 생성 같은 쓰기 요청에는 Idempotency-Key 헤더를 보내세요. 업무 건별로 고유한 문자열(UUID 또는 자체 주문번호)이면 됩니다:

```bash
curl -X POST "https://connect.everugg.net.au/api/v1/orders" -H "Authorization: Bearer <토큰>"   -H "content-type: application/json"   -H "Idempotency-Key: 8f14e45f-ea0d-4b2a-9c1b-000000000001"   -d '{"warehouse_code":"AU","lines":[{"sku":"OB0021611","quantity":1}]}'
```

타임아웃, 네트워크 불안정, 성공 여부 불확실——같은 key 로 그대로 재시도하세요. 중복 생성되지 않고 처음 응답이 그대로 반환됩니다(Idempotency-Replayed: true 헤더 포함). 재시도 시 key 를 바꾸면 실제로 주문이 두 건 생성됩니다.

## 5. 전체 대신 증분으로 동기화 (7.3MB → 수 KB)

전체 재고 조회는 7.3MB / 3만여 행 / 8.5초 입니다. 처음 한 번만 전체를 받고 응답 헤더의 x-stock-version 을 저장한 뒤, 이후에는 변경된 내용만 조회하세요:

```bash
curl "https://connect.everugg.net.au/api/v1/warehouses/AU/stock/changes?since=<42>" -H "Authorization: Bearer <토큰>"
```

changes(added/updated/removed)와 새 version 이 반환됩니다. 새 version 을 다음 since 로 사용하세요. full: true 가 반환되면 오프라인 기간이 길어 변경 로그가 지나간 것이므로 전체를 다시 받아야 합니다. 전체 조회는 ?page=1&pageSize=1000 페이지네이션도 지원합니다(생략 시 기존대로 전체 반환).

## 이 API 를 내 AI 에 연결

문서는 이미 AI 가 읽기 좋은 형태입니다: llms.txt 가 색인이고 모든 페이지에 Markdown 이 있습니다. AI 어시스턴트(Claude, Cursor 등)는 MCP 로 직접 연결하거나 Ever CLI 를 실행합니다. 권한은 항상 토큰을 따릅니다.

## 더 보기

- [API 참조(바로 테스트 가능)](https://connect.everugg.net.au/reference.md?lang=ko)
- [오류 코드 목록(해결 방법)](https://connect.everugg.net.au/reference/errors.md?lang=ko)
- [명령줄 도구(CLI)](https://connect.everugg.net.au/cli?lang=ko)
- [llms.txt](https://connect.everugg.net.au/llms.txt?lang=ko)

---
Markdown 원본: https://connect.everugg.net.au/start.md?lang=ko · 웹 페이지: https://connect.everugg.net.au/start?lang=ko