# 영수증 데이터 참조

WCPOS 로직리스 HTML 템플릿과 열전사 XML 템플릿은 동일한 표준 영수증 페이로드에서 렌더링됩니다. `{{order.number}}`, `{{store.name}}`, `{{totals.total_display}}`와 같은 Mustache 점 경로를 사용합니다. 배열은 섹션으로 렌더링됩니다:

```
{{#lines}}

  {{name}} x {{qty}} — {{line_total_display}}

{{/lines}}
```

표준 계약은 서버의 WCPOS 영수증 데이터 빌더에서 생성되며, 앱의 오프라인 영수증 렌더러에서 미러링됩니다. 영수증은 로컬 데이터에서 즉시 열리고 서버 응답이 사용 가능해지면 해당 응답으로 업그레이드되므로, 사용자 정의 템플릿에서는 PHP 주문 메서드 대신 아래 필드를 사용해야 합니다.

## 렌더링 규칙[​](#rendering-rules "렌더링 규칙으로 직접 링크")

### 통화 필드[​](#currency-fields "통화 필드으로 직접 링크")

숫자 금액 필드는 숫자로 유지되며, 렌더러가 템플릿 출력용으로 로케일 인식 `_display` 필드를 추가합니다:

| 숫자 필드                  | 표시 필드                          |
| -------------------------- | ---------------------------------- |
| `totals.total`             | `totals.total_display`             |
| `lines[].line_total`       | `lines[].line_total_display`       |
| `payments[].amount`        | `payments[].amount_display`        |
| `tax_summary[].tax_amount` | `tax_summary[].tax_amount_display` |

영수증 인쇄 시 `_display` 필드를 사용하는 것이 좋습니다. 숫자 필드는 조건부 섹션이나 기계 판독용 출력에만 사용하십시오.

### 세금 표시 관련 필드[​](#tax-display-aware-fields "세금 표시 관련 필드으로 직접 링크")

여러 필드에는 세금 포함 및 세금 제외 변형과 함께 표시용 편의 값이 있습니다. 편의 값은 매장의 장바구니 세금 표시 설정을 따릅니다.

| 편의 필드               | 세금 포함 필드               | 세금 제외 필드               |
| ----------------------- | ---------------------------- | ---------------------------- |
| `lines[].unit_price`    | `lines[].unit_price_incl`    | `lines[].unit_price_excl`    |
| `lines[].unit_subtotal` | `lines[].unit_subtotal_incl` | `lines[].unit_subtotal_excl` |
| `lines[].line_subtotal` | `lines[].line_subtotal_incl` | `lines[].line_subtotal_excl` |
| `lines[].discounts`     | `lines[].discounts_incl`     | `lines[].discounts_excl`     |
| `lines[].line_total`    | `lines[].line_total_incl`    | `lines[].line_total_excl`    |
| `fees[].total`          | `fees[].total_incl`          | `fees[].total_excl`          |
| `shipping[].total`      | `shipping[].total_incl`      | `shipping[].total_excl`      |
| `discounts[].total`     | `discounts[].total_incl`     | `discounts[].total_excl`     |
| `totals.subtotal`       | `totals.subtotal_incl`       | `totals.subtotal_excl`       |
| `totals.discount_total` | `totals.discount_total_incl` | `totals.discount_total_excl` |
| `totals.total`          | `totals.total_incl`          | `totals.total_excl`          |

### 날짜 객체[​](#date-objects "날짜 객체으로 직접 링크")

날짜 필드는 미리 포맷된 여러 변형을 포함하는 객체입니다. Mustache 내부에서 날짜 포맷을 처리할 필요가 없습니다.

| 필드                                                | 설명                       |
| --------------------------------------------------- | -------------------------- |
| `datetime`, `date`, `time`                          | 기본 날짜/시간 문자열      |
| `datetime_short`, `datetime_long`, `datetime_full`  | 로케일 기반 결합 형식      |
| `date_short`, `date_long`, `date_full`              | 로케일 기반 날짜 전용 형식 |
| `date_ymd`, `date_dmy`, `date_mdy`                  | 고정 순서 날짜 형식        |
| `weekday_short`, `weekday_long`                     | 요일 이름                  |
| `day`, `month`, `month_short`, `month_long`, `year` | 개별 날짜 구성 요소        |

사용 가능한 날짜 객체: `order.created`, `order.paid`, `order.completed`, `order.printed`, `refunds[].date`. `order.printed`는 렌더링 시점에 갱신되므로 재인쇄 시 유용합니다.

## 최상위 섹션[​](#top-level-sections "최상위 섹션으로 직접 링크")

| 섹션                 | 타입    | 설명                                                               |
| -------------------- | ------- | ------------------------------------------------------------------ |
| `order`              | object  | 주문 식별 정보, 상태, 날짜, 메모, 결제 URL 정보                    |
| `store`              | object  | 매장 식별 정보, 주소, 연락처, 세금 ID, 로고, 영업시간, 푸터 텍스트 |
| `cashier`            | object  | 주문을 처리한 사용자                                               |
| `customer`           | object  | 고객 표시 이름, 주소, 세금 ID                                      |
| `lines`              | array   | 상품 항목                                                          |
| `fees`               | array   | 수수료 항목                                                        |
| `shipping`           | array   | 배송 항목                                                          |
| `discounts`          | array   | 쿠폰/할인 항목                                                     |
| `totals`             | object  | 주문 합계, 결제 합계, 환불 요약 및 항목 수                         |
| `tax`                | object  | 섹션 가드를 위한 세금 표시 모드 플래그                             |
| `tax_summary`        | array   | 세율별 세금 요약 항목                                              |
| `has_tax_summary`    | boolean | `tax_summary` 존재 여부 확인용 편의 가드                           |
| `payments`           | array   | 결제 항목                                                          |
| `refunds`            | array   | 주문에 적용된 환불 내역                                            |
| `fiscal`             | object  | 재정 통합에 의해 채워지는 재정 스냅샷 필드                         |
| `presentation_hints` | object  | 서식 및 렌더러 힌트                                                |
| `i18n`               | object  | 기본 제공 및 사용자 정의 템플릿용 번역된 레이블                    |

## 필드 참조[​](#field-reference "필드 참조으로 직접 링크")

전체 필드 참조는 아래에 섹션별로 그룹화되어 있습니다. 모든 항목은 기본적으로 접혀 있으니 필요한 그룹을 펼치세요.

order — 식별 정보, 상태, 날짜

### order[​](#order "order으로 직접 링크")

| 필드                  | 타입        | 예시 / 설명                                        |
| --------------------- | ----------- | -------------------------------------------------- |
| `order.id`            | number      | `1234`                                             |
| `order.number`        | string      | 사용자에게 표시되는 주문 번호, 예: `"10045"`       |
| `order.currency`      | string      | ISO 통화 코드, 예: `"USD"`                         |
| `order.customer_note` | string      | 고객/주문 메모                                     |
| `order.wc_status`     | string      | WooCommerce 상태 슬러그 원본값, 예: `"processing"` |
| `order.status_label`  | string      | 사용자 정의 상태를 포함한 현지화된 상태 레이블     |
| `order.created_via`   | string      | 출처/채널, 예: `"woocommerce-pos"`                 |
| `order.needs_payment` | boolean     | 결제 섹션 표시 여부                                |
| `order.payment_url`   | string      | 사용 가능한 경우 주문 결제 URL                     |
| `order.created`       | date object | 주문 생성 날짜                                     |
| `order.paid`          | date object | 결제 날짜, 미결제 시 빈 문자열                     |
| `order.completed`     | date object | 완료 날짜, 미완료 시 빈 문자열                     |
| `order.printed`       | date object | 렌더링 시점의 인쇄/재인쇄 타임스탬프               |

store — 식별 정보, 주소, 연락처, 영업시간

### store[​](#store "store으로 직접 링크")

| 필드                            | 타입        | 예시 / 설명                                                     |
| ------------------------------- | ----------- | --------------------------------------------------------------- |
| `store.id`                      | number      | 매장 ID, 삭제된 매장의 경우 이전 ID                             |
| `store.name`                    | string      | 매장 표시 이름                                                  |
| `store.address.address_1`       | string      | 도로명 주소 1                                                   |
| `store.address.address_2`       | string      | 상세 주소                                                       |
| `store.address.city`            | string      | 시/구/군                                                        |
| `store.address.state`           | string      | 시/도                                                           |
| `store.address.postcode`        | string      | 우편번호                                                        |
| `store.address.country`         | string      | ISO 국가 코드                                                   |
| `store.address_lines`           | array       | 미리 서식이 지정된 주소 줄; 대부분의 템플릿에 권장              |
| `store.tax_ids`                 | array       | 구조화된 사업자 등록번호; 단일 세금 ID 대신 이 배열을 반복 사용 |
| `store.phone`                   | string      | 매장 전화번호                                                   |
| `store.email`                   | string      | 매장 이메일                                                     |
| `store.logo`                    | string/null | 매장 로고 URL 또는 데이터 URI                                   |
| `store.opening_hours`           | string/null | 간략한 영업시간 텍스트                                          |
| `store.opening_hours_vertical`  | string/null | 여러 줄 영업시간 블록                                           |
| `store.opening_hours_inline`    | string/null | 쉼표로 구분된 영업시간 텍스트                                   |
| `store.opening_hours_notes`     | string/null | 영업시간 관련 자유 텍스트 메모                                  |
| `store.personal_notes`          | string/null | 영수증 하단/개인 메모                                           |
| `store.policies_and_conditions` | string/null | 환불, 반품 또는 이용약관 텍스트                                 |
| `store.footer_imprint`          | string/null | 법적 고지 하단 문구                                             |

### 세금 ID 객체[​](#tax-id-objects "세금 ID 객체으로 직접 링크")

`store.tax_ids`와 `customer.tax_ids`는 동일한 구조의 객체를 포함합니다:

| 필드      | 타입        | 설명                                                                                 |
| --------- | ----------- | ------------------------------------------------------------------------------------ |
| `type`    | string      | `eu_vat`, `de_steuernummer`, `au_abn`, `br_cpf`, `us_ein` 또는 `other`와 같은 식별자 |
| `value`   | string      | 인쇄할 세금 ID 값                                                                    |
| `country` | string/null | 확인된 경우 ISO 국가 코드                                                            |
| `label`   | string/null | 렌더링 전에 결정되는 현지화된 표시 라벨                                              |

예시:

```
{{#store.tax_ids}}

  {{label}}: {{value}}

{{/store.tax_ids}}
```

cashier — 주문을 처리한 사용자

### cashier[​](#cashier "cashier으로 직접 링크")

| 필드           | 타입   | 예시 / 설명                              |
| -------------- | ------ | ---------------------------------------- |
| `cashier.id`   | number | WordPress 사용자 ID, 알 수 없는 경우 `0` |
| `cashier.name` | string | 계산원 표시 이름                         |

customer — 이름, 주소, 세금 ID

### customer[​](#customer "customer으로 직접 링크")

| 필드                          | 타입        | 예시 / 설명                         |
| ----------------------------- | ----------- | ----------------------------------- |
| `customer.id`                 | number/null | 고객 ID, 비회원의 경우 `null`       |
| `customer.name`               | string      | 고객 표시 이름 또는 비회원 라벨     |
| `customer.billing_address.*`  | object      | WooCommerce 청구 주소 필드          |
| `customer.shipping_address.*` | object      | WooCommerce 배송 주소 필드          |
| `customer.tax_ids`            | array       | 주문에서 스냅샷된 고객 세금 ID 구조 |

일반적인 주소 키에는 `first_name`, `last_name`, `company`, `address_1`, `address_2`, `city`, `state`, `postcode`, `country`, `email`, `phone`이 포함됩니다.

lines — 상품 항목

### lines[​](#lines "lines으로 직접 링크")

`{{#lines}}...{{/lines}}`로 반복합니다.

| 필드                                | 타입   | 설명                                        |
| ----------------------------------- | ------ | ------------------------------------------- |
| `key`                               | string | 고정 라인 키/주문 항목 ID                   |
| `sku`                               | string | 상품 SKU                                    |
| `name`                              | string | 상품 또는 라인 표시 이름                    |
| `qty`                               | number | 판매 수량                                   |
| `qty_refunded`                      | number | 해당 라인의 환불 수량                       |
| `unit_subtotal` / `_incl` / `_excl` | number | 할인 전 단가                                |
| `unit_price` / `_incl` / `_excl`    | number | 할인 후 단가                                |
| `line_subtotal` / `_incl` / `_excl` | number | 할인 전 항목 소계                           |
| `discounts` / `_incl` / `_excl`     | number | 양수 값으로 표시된 할인 금액                |
| `line_total` / `_incl` / `_excl`    | number | 최종 항목 합계                              |
| `total_refunded`                    | number | 해당 항목의 총 환불 금액(양수 값)           |
| `taxes`                             | array  | 해당 항목의 세율별 세금 행                  |
| `meta`                              | array  | `{key, value}` 쌍으로 구성된 주문 항목 메타 |
| `attributes`                        | array  | `{key, value}` 쌍으로 구성된 상품/옵션 속성 |

서식이 적용된 변형에는 `unit_subtotal_display`, `unit_price_display`, `line_subtotal_display`, `discounts_display`, `line_total_display` 및 세금 포함/제외 `_display` 변형이 포함됩니다.

fees 및 shipping

### fees 및 shipping[​](#fees-and-shipping "fees 및 shipping으로 직접 링크")

`{{#fees}}...{{/fees}}` 및 `{{#shipping}}...{{/shipping}}`으로 반복합니다.

| 필드                        | 타입   | 설명                              |
| --------------------------- | ------ | --------------------------------- |
| `label`                     | string | 수수료 라벨 또는 배송 방법 이름   |
| `method_id`                 | string | 배송 방법 ID (배송에만 해당)      |
| `total` / `_incl` / `_excl` | number | 표시용, 세금 포함, 세금 제외 합계 |
| `taxes`                     | array  | 세율별 세금 행                    |
| `meta`                      | array  | `{key, value}` 메타 쌍            |

서식 적용 변형: `total_display`, `total_incl_display`, `total_excl_display`.

discounts — 쿠폰/할인 항목

### discounts[​](#discounts "discounts으로 직접 링크")

`{{#discounts}}...{{/discounts}}`로 반복합니다.

| 필드                        | 타입   | 설명                             |
| --------------------------- | ------ | -------------------------------- |
| `label`                     | string | 쿠폰 설명 또는 코드 대체값       |
| `code`                      | string | 쿠폰 코드                        |
| `codes`                     | string | 결합된 코드의 레거시/표시 대체값 |
| `total` / `_incl` / `_excl` | number | 양수 값으로 표시된 할인 금액     |

서식 적용 변형: `total_display`, `total_incl_display`, `total_excl_display`. 할인을 음수 행으로 표시하려면 템플릿에 직접 마이너스 기호를 추가하십시오.

totals — 주문, 결제, 환불 및 항목 합계

### totals[​](#totals "totals으로 직접 링크")

| 필드                                        | 타입   | 설명                                      |
| ------------------------------------------- | ------ | ----------------------------------------- |
| `totals.subtotal` / `_incl` / `_excl`       | number | 할인 적용 전 주문 소계                    |
| `totals.discount_total` / `_incl` / `_excl` | number | 양수 값으로 표시된 주문 할인 합계         |
| `totals.tax_total`                          | number | 총 세금 금액                              |
| `totals.total` / `_incl` / `_excl`          | number | 주문 총합계                               |
| `totals.paid_total`                         | number | 결제/적용된 금액                          |
| `totals.change_total`                       | number | 고객에게 반환된 거스름돈                  |
| `totals.refund_total`                       | number | 양수 값으로 표시된 총 환불 금액           |
| `totals.net_total`                          | number | `total - refund_total`, 최솟값 0으로 제한 |
| `totals.total_qty`                          | number | 품목 수량의 합계                          |
| `totals.line_count`                         | number | 상품 품목 행의 수                         |

서식이 적용된 변형에는 `subtotal_display`, `discount_total_display`, `tax_total_display`, `total_display`, `paid_total_display`, `change_total_display`, `refund_total_display`, `net_total_display`가 포함되며, 해당하는 경우 포함/제외 변형도 제공됩니다.

tax 및 tax\_summary — 표시 가드 및 세율별 행

### tax 및 tax\_summary[​](#tax-and-tax_summary "tax 및 tax_summary으로 직접 링크")

표시 모드 조건에는 `tax`를, 항목별 세율 행에는 `tax_summary`를 사용하십시오.

| 세금 필드                | 타입    | 설명                                       |
| ------------------------ | ------- | ------------------------------------------ |
| `tax.display`            | string  | `incl` 또는 `excl`                         |
| `tax.display_incl`       | boolean | 가격이 세금 포함으로 표시될 때 True        |
| `tax.display_excl`       | boolean | 가격이 세금 별도로 표시될 때 True          |
| `tax.breakdown`          | string  | `hidden`, `single`, 또는 `itemized`        |
| `tax.breakdown_hidden`   | boolean | 세금 행이 숨겨져야 할 때 True              |
| `tax.breakdown_single`   | boolean | 단일 세금 합계가 선호될 때 True            |
| `tax.breakdown_itemized` | boolean | 세율별 행이 선호될 때 True                 |
| `has_tax_summary`        | boolean | `tax_summary`에 행이 포함되어 있을 때 True |

`tax_summary`를 `{{#tax_summary}}...{{/tax_summary}}`로 반복합니다.

| 필드                  | 타입        | 설명                     |
| --------------------- | ----------- | ------------------------ |
| `code`                | string      | 세율 ID/코드             |
| `rate`                | number/null | 확인된 세율 백분율       |
| `label`               | string      | 세율 라벨                |
| `compound`            | boolean     | 복합 세율 여부           |
| `taxable_amount_excl` | number/null | 세금 제외 과세 기준 금액 |
| `tax_amount`          | number      | 징수된 세액              |
| `taxable_amount_incl` | number/null | 세금 포함 과세 기준 금액 |

서식이 적용된 변형: `taxable_amount_excl_display`, `tax_amount_display`, `taxable_amount_incl_display`.

payments — 결제 항목

### payments[​](#payments "payments으로 직접 링크")

`{{#payments}}...{{/payments}}`로 반복합니다.

| 필드             | 타입   | 설명                      |
| ---------------- | ------ | ------------------------- |
| `method_id`      | string | 결제 방법 식별자          |
| `method_title`   | string | 결제 방법 표시 이름       |
| `amount`         | number | 주문에 적용된 금액        |
| `transaction_id` | string | 게이트웨이 거래 ID        |
| `tendered`       | number | 현금 지불 금액(있는 경우) |
| `change`         | number | 현금 거스름돈(있는 경우)  |

서식 적용 변형: `amount_display`, `tendered_display`, `change_display`.

refunds — 환불 내역

### refunds[​](#refunds "refunds으로 직접 링크")

`{{#refunds}}...{{/refunds}}`로 반복합니다. 환불 금액은 양수 절대값이며, 마이너스 기호를 앞에 붙이거나 별도의 반품 항목 블록을 렌더링할지는 템플릿에서 결정합니다.

| 필드               | 타입        | 설명                                            |
| ------------------ | ----------- | ----------------------------------------------- |
| `id`               | number      | 환불 레코드 ID                                  |
| `date`             | date object | 환불 생성 날짜                                  |
| `amount`           | number      | 환불 합계                                       |
| `subtotal`         | number      | 환불된 항목 소계                                |
| `tax_total`        | number      | 환불된 세금                                     |
| `shipping_total`   | number      | 환불된 배송비                                   |
| `shipping_tax`     | number      | 환불된 배송 세금                                |
| `reason`           | string      | 환불 사유                                       |
| `refunded_by_id`   | number/null | 환불을 처리한 사용자 ID                         |
| `refunded_by_name` | string      | 환불을 처리한 사용자 표시 이름                  |
| `refunded_payment` | boolean     | 결제 게이트웨이를 통해 결제가 환불되었는지 여부 |
| `destination`      | string      | `original_method`, `cash`, 또는 `manual`        |
| `gateway_id`       | string      | 환불에 사용된 게이트웨이 ID                     |
| `gateway_title`    | string      | 게이트웨이 표시 제목                            |
| `processing_mode`  | string      | 공급자/수동 처리 모드                           |
| `lines`            | array       | 환불된 상품 행                                  |
| `fees`             | array       | 환불된 수수료 행                                |
| `shipping`         | array       | 환불된 배송 행                                  |

환불 항목 필드에는 `name`, `sku`, `qty`, `total`, `total_incl`, `total_excl`, `line_total`, `unit_total`, `taxes`가 포함됩니다. 환불 수수료 및 배송 행은 `label`, `total`, `total_incl`, `total_excl`, `taxes`를 사용합니다. 합계 및 세액에 대해 표시 변형이 추가됩니다.

fiscal — 재정 통합 스냅샷

### fiscal[​](#fiscal "fiscal으로 직접 링크")

fiscal 필드는 기본적으로 비어 있으며, 재정 통합 또는 WCPOS Pro 스냅샷 보강을 통해 채워집니다.

| 필드                       | 타입         | 설명                       |
| -------------------------- | ------------ | -------------------------- |
| `fiscal.immutable_id`      | string       | 불변 재정 식별자           |
| `fiscal.receipt_number`    | string       | 재정 영수증 번호           |
| `fiscal.sequence`          | number/null  | 시퀀스 카운터              |
| `fiscal.hash`              | string       | 해시/서명 값               |
| `fiscal.qr_payload`        | string       | 세금 검증용 QR 페이로드    |
| `fiscal.tax_agency_code`   | string       | 세무 당국 코드             |
| `fiscal.signed_at`         | string       | 세금 서명 타임스탬프       |
| `fiscal.signature_excerpt` | string       | 표시용 서명 발췌           |
| `fiscal.document_label`    | string       | 문서 라벨 (예: 세금계산서) |
| `fiscal.is_reprint`        | boolean      | 재인쇄 여부                |
| `fiscal.reprint_count`     | number       | 재인쇄 횟수                |
| `fiscal.extra_fields`      | array/object | 관할권별 고유 값           |

presentation\_hints — 서식 및 렌더러 힌트

### presentation\_hints[​](#presentation_hints "presentation_hints으로 직접 링크")

이 필드들은 주로 렌더러와 포매터에서 사용됩니다. 필요 시 템플릿에서도 사용할 수 있습니다.

| 필드                                          | 타입    | 설명                                               |
| --------------------------------------------- | ------- | -------------------------------------------------- |
| `presentation_hints.display_tax`              | string  | `incl`, `excl`, `hidden`, `itemized` 또는 `single` |
| `presentation_hints.prices_entered_with_tax`  | boolean | 카탈로그 가격에 세금이 포함되어 있는지 여부        |
| `presentation_hints.rounding_mode`            | string  | WooCommerce 세금 반올림 설정                       |
| `presentation_hints.locale`                   | string  | 서식 지정에 사용되는 로케일                        |
| `presentation_hints.timezone`                 | string  | 영수증 시간대                                      |
| `presentation_hints.currency_position`        | string  | 통화 기호 위치                                     |
| `presentation_hints.currency_symbol`          | string  | 통화 기호                                          |
| `presentation_hints.price_thousand_separator` | string  | 천 단위 구분 기호                                  |
| `presentation_hints.price_decimal_separator`  | string  | 소수점 구분 기호                                   |
| `presentation_hints.price_num_decimals`       | number  | 소수 자릿수                                        |
| `presentation_hints.price_display_suffix`     | string  | WooCommerce 가격 표시 접미사                       |
| `presentation_hints.order_barcode_type`       | string  | 갤러리 템플릿에서 사용하는 바코드 유형             |

i18n — 번역된 레이블

### i18n[​](#i18n "i18n으로 직접 링크")

가능한 경우 텍스트를 하드코딩하는 대신 `i18n` 라벨을 사용하세요:

```
{{i18n.order}} #{{order.number}}

{{i18n.cashier}}: {{cashier.name}}

{{i18n.total}}: {{totals.total_display}}
```

일반적인 키에는 `order`, `date`, `cashier`, `customer`, `item`, `sku`, `qty`, `unit_price`, `discount`, `subtotal`, `total`, `tax`, `paid`, `tendered`, `change`, `tax_summary`, `refunded`, `net_total`, `customer_note`, `thank_you_purchase`, `opening_hours` 및 `store_tax_id_label_eu_vat`, `customer_tax_id_label_other`와 같은 세금 ID 라벨 키가 포함됩니다. 확장 기능을 통해 추가 키가 추가될 수 있습니다.