# 구매 API - Tax 조회
## 1. API Overview
### Purpose
[context]
상품 및 배송지 정보를 기반으로 예상 세금을 계산하는 API입니다.
사용자가 제공한 배송지와 청구지 주소, 상품 금액, 할인 및 배송비 정보를 바탕으로 세금 내역을 조회합니다.
결과에는 총 세액과 항목별 세금 상세 정보가 포함됩니다.
이 API는 결제 전에 세금 정보를 확인하여 정확한 결제 금액을 산출하는 데 사용됩니다.
[/context]
> **참고**: TAX 조회 기능은 PG사에 의존적입니다. TAX 조회 지원 여부는 빌링팀에 문의하시기 바랍니다. ([ebp-server@lge.com](mailto:ebp-server@lge.com))
### Details
[table:key-value]
| 항목 | 값 |
| :-------------- | :-------------------- |
| **API Name** | Tax 조회 |
| **API Path** | /api/v2/payment/taxes |
| **API ID** | EBP_API_227 |
| **HTTP Method** | [badge:POST,blue,lg] |
| **Region** | [badge:Global,green-subtle,lg] |
[/table]
## 2. Request Specification
### 2.1 Request Header
@@include:common-headers-link.md@@
### 2.2 Request Data Schema
| depth | Field | Details & Description |
| :---- | :---------------------- | :------------------------------------------------------------------------ |
| 0 | userNo | [type:string] [req:Yes] [desc:사용자 식별을 위한 고유 번호] |
| 0 | isTaxIncluded | [type:string] [req:Yes] [desc:상품 가격에 세금(TAX)이 포함 여부] |
| 0 | deliveryAddress | [type:object] [req:Yes] [desc:배송지 주소 정보] |
| 1 | recipientLocalName | [type:string] [req:Yes] [desc:수령인 현지 이름] |
| 1 | recipientLocalFirstName | [type:string] [req:Optional] [desc:수령인 현지 퍼스트 이름] |
| 1 | countryCode | [type:string] [req:Conditional] [desc:배송 국가 코드 (ISO 기준)] |
| 1 | streetAddress | [type:string] [req:Optional] [desc:배송지 도로명] |
| 1 | addressLine1 | [type:string] [req:Optional] [desc:배송지 주소1] |
| 1 | addressLine2 | [type:string] [req:Optional] [desc:배송지 주소2] |
| 1 | city | [type:string] [req:Optional] [desc:배송지 시/도] |
| 1 | postalCode | [type:string] [req:Optional] [desc:배송지 우편번호] |
| 0 | billingAddress | [type:object] [req:-] [desc:세금계산서 발행을 위한 청구지 주소 정보] |
| 1 | billingEmail | [type-ml:string,128] [req:Optional] [desc:청구 담당자 이메일 주소] |
| 1 | billingLastName | [type-ml:string,100] [req:Conditional] [desc:청구 담당자 성(현지 언어)] |
| 1 | billingFirstName | [type-ml:string,100] [req:Conditional] [desc:청구 담당자 이름(현지 언어)] |
| 1 | billingCountry | [type-ml:string,3] [req:Conditional] [desc:ISO 3166-1 alpha-3 국가 코드] |
| 1 | billingStreet | [type-ml:string,100] [req:Conditional] [desc:청구지 도로명] |
| 1 | billingAddressLine1 | [type-ml:string,100] [req:Conditional] [desc:청구지 주소1] |
| 1 | billingAddressLine2 | [type-ml:string,100] [req:Optional] [desc:청구지 주소2] |
| 1 | billingCity | [type-ml:string,100] [req:Conditional] [desc:청구지 도시] |
| 1 | billingPostalCode | [type-ml:string,100] [req:Conditional] [desc:청구지 우편번호] |
| 1 | billingState | [type-ml:string,100] [req:Conditional] [desc:청구지 주/도] |
| 0 | items | [type:array] [req:Yes] [desc:-] |
| 1 | seq | [type:number] [req:Yes] [desc:일련번호] |
| 1 | itemId | [type:string] [req:Yes] [desc:상품 ID] |
| 1 | productCode | [type:string] [req:Yes] [desc:상품 코드] |
| 1 | amount | [type:number] [req:Optional] [desc:상품금액] |
| 1 | discountAmount | [type:number] [req:Optional] [desc:할인금액] |
| 1 | deliveryAmount | [type:number] [req:Optional] [desc:배송금액] |
| 1 | deliveryProductCode | [type:number] [req:Optional] [desc:배송비 상품 코드] |
### 2.3 Request Examples
#### JSON Example
```json
{
"userNo": "U123456789",
"isTaxIncluded": "Y",
"deliveryAddress": {
"recipientLocalName": "홍길동",
"recipientLocalFirstName": "길동",
"countryCode": "KR",
"streetAddress": "123 강남대로",
"addressLine1": "강남구 역삼동",
"addressLine2": "삼성타워 101호",
"city": "서울",
"postalCode": "06236"
},
"billingAddress": {
"billingEmail": "billing@example.com",
"billingLastName": "Kim",
"billingFirstName": "Minsoo",
"billingCountry": "KOR",
"billingStreet": "456 테헤란로",
"billingAddressLine1": "강남구 삼성동",
"billingAddressLine2": "빌딩 202호",
"billingCity": "서울",
"billingPostalCode": "06164",
"billingState": "서울특별시"
},
"items": [
{
"seq": 1,
"productCode": "",
"amount": "",
"discountAmount": 0,
"deliveryAmount": 0,
"deliveryProductCode": "24643"
}
]
}
```
## 3. Response Specification
### 3.1 Response Data Schema
@@include:standard-response.md@@
| -1 | data | [type:object] [req:Yes] [desc:응답 데이터] |
| 0 | totalTaxAmount | [type:number] [req:Yes] [desc:사용자 전체 세금 금액] |
| 0 | taxItems | [type:array] [req:Yes] [desc:세금 항목 객체 리스트] |
| 1 | itemSeq | [type:number] [req:Yes] [desc:세금 항목의 순번] |
| 1 | itemId | [type:string] [req:Yes] [desc:상품 고유 식별자] |
| 1 | taxAmount | [type:number] [req:Yes] [desc:해당 상품의 세금 금액] |
| 1 | taxDetails | [type:array] [req:Yes] [desc:세금 상세 내역 리스트] |
| 2 | detailSeq | [type:number] [req:Yes] [desc:상세 내역 순번] |
| 2 | taxType | [type:string] [req:Yes] [desc:세금 유형 (예: VAT, Service)] |
| 2 | taxName | [type:string] [req:Yes] [desc:세금 이름] |
| 2 | taxAmount | [type:number] [req:Yes] [desc:해당 상세 내역의 세금 금액] |
### 3.2 Response Samples
#### Success Response
```json
{
"resultCode": "0",
"message": "SUCCESS",
"requestId": "1767142829863",
"timestamp": "2025-12-31T01:00:29.865421800Z",
"data": {
"totalTaxAmount": 0.41,
"taxItems": [
{
"itemSeq": 1,
"itemId": "PD_20250000000003",
"taxAmount": 0.41,
"taxDetails": [
{
"detailSeq": 1,
"taxType": "Sales And Use Taxes",
"taxName": "NY Local Transit Tax",
"taxAmount": 0.0225
},
{
"detailSeq": 2,
"taxType": "Sales And Use Taxes",
"taxName": "NY Sales Tax",
"taxAmount": 0.1875
},
{
"detailSeq": 3,
"taxType": "Sales And Use Taxes",
"taxName": "NY Sales Tax",
"taxAmount": 0.2
}
]
}
]
}
}
```