# 수취인 신분증 이미지 업로드 ⚠️ 최종 소비자 신분증 앞뒤(개인정보)

`POST /api/v1/shipments/identity-documents` — 토큰 필요 · logistics:write · 쓰기 · 2포인트

출고와 물류

수취인 신분증 이미지 업로드 ⚠️ 최종 소비자 신분증 앞뒤(개인정보). 기본 비활성, 신청 후 사용; 전달만 하며 로그/캐시 없음

## 요청 본문(JSON)

| 필드 | 타입 | 설명 |
| --- | --- | --- |
| `front_image` **필수** | string | ⚠️ 신분증 앞면(base64). 최종 소비자의 민감 개인정보: 전달만 하며 로그/캐시에 남기지 않습니다. 기본 비활성, 명시적 신청 필요. (최대 길이 8000000) |
| `back_image` **필수** | string | ⚠️ 신분증 뒷면(base64). 위와 동일. (최대 길이 8000000) |
| `shipment_ids` | array<string> | 관련 출고번호 목록(선택). (0–100) |
| `recipient` | object | 수취인 객체 { name, phone, address, country_code, state, city, postal_code }. country_code 는 AU / CN / NZ; 호주·뉴질랜드는 state, city, postal_code 필수. 국제 배송은 전화번호에 국가번호(+61…), 주소에 번지까지 포함하세요 — 주소 불완전이 배송 실패의 가장 흔한 원인입니다. |
| `recipient.name` | string | 수취인 이름. (최대 길이 128) |
| `recipient.phone` | string | 수취인 전화번호. 국제 배송은 국가번호 포함(예: +61…). (최대 길이 64) |
| `document_number` | string | 신분증 번호(선택). (최대 길이 64) |

## 응답

봉투는 HTTP 상태 코드만으로 판단합니다: 2xx 는 `{ data: … }`(목록은 `page / page_size / has_more` 또는 `total_count` 포함); 4xx / 5xx 는 `{ error: { code, message, hint, request_id, doc_url } }`.

```json
{
  "data": { … }
}
```

성공 응답에는 사람이 읽는 문구가 없습니다 — `code / result / msg` 없음. 프로그램이 분기해야 할 필드는 `error.code` 뿐이며 `message` 는 `Accept-Language` 를 따릅니다.

> 쓰기 요청에는 `Idempotency-Key` 헤더(UUID 등 고유 문자열)를 보내세요. 네트워크 재시도로 주문이 두 번 생기지 않습니다. 주문은 ERP에서 사람이 확인하기 전까지 초안입니다.

## 예제

### curl

```bash
curl -X POST "https://connect.everugg.net.au/api/v1/shipments/identity-documents" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <uuid>" \
  -d '{ "front_image": "<front_image>", "back_image": "<back_image>" }'
```

### Python

```python
import requests

r = requests.post(
    "https://connect.everugg.net.au/api/v1/shipments/identity-documents",
    headers={"Authorization": "Bearer " + TOKEN, "Idempotency-Key": str(uuid.uuid4())},
    json={
      "front_image": "<front_image>",
      "back_image": "<back_image>"
    },
)
data = r.json()
r.raise_for_status()  # 4xx/5xx: data["error"]["code"] / ["hint"]
```

### Node

```js
const res = await fetch("https://connect.everugg.net.au/api/v1/shipments/identity-documents", {
  method: "POST",
  headers: { Authorization: `Bearer ${TOKEN}`, "Content-Type": "application/json", "Idempotency-Key": crypto.randomUUID() },
  body: JSON.stringify({
    "front_image": "<front_image>",
    "back_image": "<back_image>"
  }),
})
const data = await res.json()
if (!res.ok) throw new Error(`${data.error?.code}: ${data.error?.message}`)
```

### Java

```java
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://connect.everugg.net.au/api/v1/shipments/identity-documents"))
    .header("Authorization", "Bearer " + token)
    .header("Content-Type", "application/json")
    .header("Idempotency-Key", UUID.randomUUID().toString())
    .POST(HttpRequest.BodyPublishers.ofString("{ \"front_image\": \"<front_image>\", \"back_image\": \"<back_image>\" }"))
    .build();
HttpResponse<String> res = HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString());
```

---
Markdown 원본: https://connect.everugg.net.au/reference/post-api-v1-shipments-identity-documents.md?lang=ko · 웹 페이지: https://connect.everugg.net.au/reference?op=post-api-v1-shipments-identity-documents&lang=ko