VibeFox EasyPost for WooCommerce — 도움말

요구 사항

WordPress: 5.8 이상.

WooCommerce: 7.0 이상, 설치 및 활성화되어 있어야 합니다. WooCommerce가 없으면 플러그인이 활성화되지 않습니다.

PHP: 8.0 이상.

EasyPost 계정(실시간 요금에만 필요): EasyPost 웹사이트에서 계정을 만들고, EasyPost 대시보드에서 운송사 계정(USPS, UPS, FedEx 등)을 연결한 뒤, EasyPost Dashboard > Account Settings > API Keys에서 API 키를 복사합니다. EasyPost는 요금 조회가 아니라 구매한 라벨에 대해 요금을 청구합니다. 대체 가격만 사용한다면 EasyPost 계정은 필요하지 않습니다.

상품: 상품에는 무게가 필요하며, 가능하면 치수도 입력하는 것이 좋습니다.

VibeFox 라이선스 키: vibefox.net에서 구매합니다. 키 하나는 도메인 하나에서 사용할 수 있습니다.

설치

1. WordPress에서 Plugins > Add New > Upload Plugin으로 이동하여 플러그인 ZIP 파일을 선택한 뒤 Install Now를 클릭합니다. FTP로 vfd_easypost 폴더를 /wp-content/plugins/에 업로드할 수도 있습니다.

2. Activate를 클릭합니다.

3. 설정을 엽니다: WooCommerce > Settings > Shipping > VibeFox EasyPost. 또는 플러그인 목록 페이지에서 플러그인 이름 아래의 Settings를 클릭합니다.

4. 페이지 상단의 라이선스 블록에 VibeFox 라이선스 키를 입력하고 Activate를 클릭합니다.

5. EasyPost API 키를 붙여넣고 Ship from 주소를 입력합니다. 실시간 요금에는 우편번호가 필요합니다.

6. 쇼핑몰 통화가 USD가 아니면 USD exchange rate를 입력합니다. 필요하면 대체 가격도 입력할 수 있습니다(설정 항목 참조).

7. WooCommerce > Settings > Shipping > Shipping zones에서 배송 구역에 VibeFox EasyPost를 추가하거나, Ignore shipping zones를 켜고 국가를 선택합니다.

설정

모든 설정은 한 페이지에 있습니다: WooCommerce > Settings > Shipping > VibeFox EasyPost. 설정은 모든 배송 구역에 적용됩니다. 배송 구역에 이 방법을 추가하면 구역 창에는 다음 항목 하나만 표시됩니다:

Title (zone): 이 구역의 고객에게 표시되는 배송 방법 이름. 비워 두면 전역 Name을 사용합니다.

페이지 상단에는 실시간 요금을 사용할 수 없을 때 플러그인이 경고를 표시합니다: API 키가 없거나, 출발지 우편번호 또는 국가가 없거나, 쇼핑몰 통화가 USD가 아니면서 환율이 없는 경우입니다. 테스트 API 키가 설정되어 있으면 안내 메시지도 나타납니다. 설정을 저장할 때마다 캐시된 EasyPost 요금이 삭제됩니다.

일반

Enable/Disable: 모든 구역에서 이 방법을 한 번에 켜거나 끕니다. 기본값: 켜짐.

Name: 장바구니와 체크아웃에 표시되는 배송 방법 이름. 구역은 자체 Title로 이를 덮어쓸 수 있습니다. 기본값: EasyPost Shipping.

EasyPost 계정

API key: EasyPost Dashboard > Account Settings > API Keys에 있는 EasyPost API 키. 운영 키(EZAK로 시작)는 실제 요금을 반환합니다. 테스트 키(EZTK로 시작)는 EasyPost 테스트 요금을 반환하므로 테스트 용도로만 사용하세요.

Allowed carriers / services: 선택 사항, 쉼표로 구분합니다. EasyPost가 부르는 이름 그대로 운송사(USPS) 또는 운송사와 서비스(USPS:Priority, UPS:Ground)를 입력합니다. 허용된 것 중 가장 저렴한 요금이 표시됩니다. 비워 두면 어떤 운송사든 가장 저렴한 요금을 표시합니다.

출발지

소포를 발송하는 주소입니다. Country가 쇼핑몰 국가이면, 빈 항목은 WooCommerce > Settings > General의 쇼핑몰 주소에서 채워집니다(보내는 사람 이름은 사이트 제목에서 가져옵니다).

Sender name / company: 보내는 사람 이름 또는 회사명.

Street address: 출발지 주소의 도로명.

City: 출발지 도시.

State: 두 글자 주 코드(예: CA 또는 NY).

ZIP code: 출발지 우편번호. 실시간 요금에 필요합니다.

Country: 발송 국가. 기본값: United States.

요금

Parcels: 장바구니를 EasyPost로 보내는 방식.

One parcel per order (the cart is packed into one box): 모든 수량을 하나의 상자에 담아 한 번에 요금을 계산합니다. 기본값입니다.

One parcel per item (every unit ships in its own box): 상품마다 별도의 소포로 요금을 계산하며, 요금은 수량마다 청구됩니다. 대체 가격도 수량마다 청구됩니다.

무게는 쇼핑몰의 무게 단위에서 온스(최소 1 oz)로, 치수는 인치로 변환됩니다. 상품에 치수가 없으면 소포는 무게로만 계산됩니다.

USD exchange rate: EasyPost 요금은 USD 기준입니다. 1 USD에 해당하는 쇼핑몰 통화 금액을 입력합니다(예: 0.92). 이 값이 없으면 실시간 요금은 사용되지 않고 대체 가격만 사용됩니다. 쇼핑몰 통화가 USD이면 필요하지 않습니다. USD 및 CAD 쇼핑몰은 EasyPost에 자국 통화로 견적을 요청합니다. 소수점 구분자는 점(.)과 쉼표(,) 모두 허용됩니다.

Tax status: Taxable을 선택하면 WooCommerce가 세금 규칙에 따라 배송비에 세금을 추가하고, None을 선택하면 추가하지 않습니다. EasyPost 요금에는 판매세가 포함되지 않습니다. 기본값: Taxable.

대체 가격

실시간 요금이 없을 때 사용됩니다. API 키가 없거나, EasyPost에 연결할 수 없거나, 키가 거부되었거나, 어떤 운송사도 해당 주소의 요금을 제공하지 않는 경우입니다. 가격은 쇼핑몰 통화로 입력합니다. 이런 경우 방법을 숨기려면 두 항목을 모두 비워 두세요.

Country prices: 국가당 한 줄: 두 글자 국가 코드, 콜론, 가격 순서입니다(예: US:9.99). 형식이 다른 줄은 무시되며, 저장할 때 오류 메시지에 나열됩니다.

Other countries: 위 목록에 없는 국가의 가격. 비워 두면 해당 국가에서는 방법이 숨겨집니다.

조건

Free shipping from: 이 소계 금액 이상일 때 배송이 무료가 되는 장바구니 소계. 이 경우 EasyPost에 요청하지 않습니다. 비워 두면 기능이 꺼집니다.

Minimum subtotal: 장바구니 소계가 이 금액 이상일 때만 방법을 표시합니다. 비워 두면 항상 표시합니다.

Minimum weight: 장바구니 무게가 이보다 가벼우면 방법을 숨깁니다(쇼핑몰 무게 단위 기준). 0은 제한 없음을 뜻합니다.

Maximum weight: 장바구니 무게가 이보다 무거우면 방법을 숨깁니다(쇼핑몰 무게 단위 기준). 0은 제한 없음을 뜻합니다.

Disabled shipping classes: 장바구니에 이 WooCommerce 배송 클래스 중 하나에 속한 상품이 있으면 방법을 숨깁니다.

배송 구역 없이 사용 가능 여부

Ignore shipping zones: 방법이 구역에 추가되었는지와 관계없이, 아래 국가에 대해 방법을 제공합니다.

Countries: 이 모드의 배송 대상 국가. 비워 두면 쇼핑몰이 배송하는 모든 국가를 사용합니다. 이 항목은 Ignore shipping zones가 켜져 있을 때만 사용됩니다.

고급

Debug log: EasyPost 요청을 WooCommerce > Status > Logs에 기록합니다(소스: vfd-easypost). 이 옵션이 꺼져 있어도 API 오류는 항상 기록됩니다. API 키와 고객 주소는 절대 기록되지 않습니다.

Remove data on uninstall: 켜면 플러그인을 삭제할 때 설정과 구역 방법도 함께 제거됩니다. 플러그인을 비활성화해도 설정은 절대 삭제되지 않습니다.

체크아웃에서의 동작

고객이 배송 주소를 입력하면 WooCommerce가 플러그인에 요금을 요청합니다. 플러그인은 먼저 조건을 확인합니다: 배송 국가, 장바구니 무게, 최소 소계, 비활성화된 배송 클래스. 무료 배송이 적용되면 방법이 0원으로 표시되고 EasyPost에는 요청하지 않습니다.

그렇지 않으면 플러그인은 출발지 주소, 배송 주소, 소포 정보를 EasyPost에 보내고, 모든 운송사 계정의 요금을 받습니다. 허용된 것 중 가장 저렴한 요금을 고르고, 쇼핑몰 통화로 환산하여 방법 이름 아래에 표시합니다. 우편번호가 필요한 국가에서는 고객이 우편번호를 입력한 후에만 요청이 전송됩니다.

같은 주소와 같은 소포에 대한 응답은 1시간 동안 캐시됩니다. 사용 가능한 요금이 없는 주소는 10분 동안 기억됩니다. 시간 초과, 키 거부, 요청 제한(rate limit), EasyPost 서버 오류가 발생하면 5분 동안 요청하지 않습니다. API 시간 초과는 10초입니다. 이러한 경우 고객에게 오류는 표시되지 않습니다. 대체 가격이 사용되거나, 대체 가격이 없으면 방법이 숨겨집니다.

선택된 운송사와 서비스, 그리고 하나의 소포 모드에서는 예상 배송일이 주문의 배송 항목에 저장됩니다. 관리자 주문 화면에서 확인할 수 있습니다.

이 방법은 클래식 체크아웃과 장바구니 및 체크아웃 블록에서 작동합니다. WooCommerce 고성능 주문 저장소(HPOS)와 호환됩니다.

플러그인은 요금만 계산합니다. 라벨을 구매하거나, 소포를 추적하거나, 주소를 검증하거나, 픽업·드롭오프 장소를 제공하지 않으며, 보험이나 서명 옵션도 추가하지 않습니다. 하나의 옵션(허용된 것 중 가장 저렴한 요금)만 표시하며, 서비스 목록은 표시하지 않습니다. 상품을 하나의 소포에 담는 것 외에는 상자 포장 최적화가 없으며, 요금 마크업이나 취급 수수료도 없습니다.

라이선스 키

플러그인은 vibefox.net에서 받은 VibeFox 라이선스 키로 작동합니다. 라이선스 블록은 WooCommerce > Settings > Shipping > VibeFox EasyPost 페이지 상단에 있습니다. 키를 License key에 붙여넣고 Activate를 클릭하세요. 블록에는 상태(예: 라이선스가 유효한 날짜)와 도메인이 표시됩니다. Check now로 상태를 다시 확인하고, Change key로 다른 키를 입력하고, Remove key로 이 사이트에서 키를 제거할 수 있습니다. Manage licenses and domains in your account 링크는 vibefox.net 계정을 엽니다.

키 하나는 도메인 하나에서 작동합니다. 사이트에서 키를 제거해도 도메인 슬롯은 해제되지 않습니다. vibefox.net 계정에서 슬롯을 해제하세요.

유효한 키가 없으면 체크아웃에서 고객에게 EasyPost가 표시되지 않습니다. 로그인한 쇼핑몰 관리자에게는 (unlicensed — visible to admins only) 표시와 함께 보이므로, 키를 구매하기 전에 플러그인을 설정하고 테스트할 수 있습니다. 플러그인 목록 페이지와 WooCommerce 페이지에 알림이 나타납니다. 기존 주문에는 영향이 없습니다.

라이선스가 만료되어도 플러그인은 계속 작동하지만, 업데이트와 지원에는 갱신이 필요합니다. 상태는 백그라운드에서 자동으로 다시 확인됩니다.

문제 해결

체크아웃에 EasyPost가 표시되지 않음: 라이선스가 활성 상태인지, Enable/Disable이 켜져 있는지, 고객 국가의 구역에 방법이 추가되어 있는지(또는 Ignore shipping zones가 켜져 있고 해당 국가가 허용되어 있는지) 확인하세요. 무게 제한, Minimum subtotal, Disabled shipping classes도 확인하세요. 실시간 요금이 없으면 이 방법에는 해당 국가 또는 Other countries의 대체 가격이 필요합니다.

실시간 요금이 표시되지 않음: 설정 페이지 상단의 경고를 읽은 다음, Debug log를 켜고 체크아웃을 새로 고친 뒤 WooCommerce > Status > Logs를 열어 소스 vfd-easypost를 확인하세요. 흔한 원인: API 키 또는 출발지 우편번호 없음, USD가 아닌 쇼핑몰에 USD exchange rate 없음, 고객이 아직 우편번호를 입력하지 않음, EasyPost 계정의 어떤 운송사도 해당 주소를 담당하지 않음, 또는 Allowed carriers / services가 모든 요금을 걸러냄.

요금이 테스트 가격처럼 보임: 테스트 키(EZTK...)가 설정되어 있습니다. 실제 쇼핑몰에서는 운영 키(EZAK...)를 사용하세요.

요금이 몇 분 동안 중단됨: 시간 초과, 키 거부 또는 EasyPost 서버 오류 후 플러그인은 5분 동안 요청을 중단하고 대체 가격을 사용합니다. API 키와 로그를 확인하세요.

세금이 포함되어 있나요? EasyPost 요금에는 판매세가 포함되지 않습니다. Tax status가 Taxable이면 WooCommerce가 세금 설정에 따라 배송비에 세금을 추가합니다.

변경 후 요금이 오래된 것처럼 보임: 설정 페이지를 저장하세요. 캐시된 EasyPost 요금이 삭제됩니다.

개발자 훅: 필터 vfd_ep_shipment_request(요청 본문), vfd_ep_selected_rate(선택된 요금), vfd_ep_api_url(API 기본 URL), woocommerce_shipping_vfd_easypost_is_available로 플러그인을 조정할 수 있습니다.

라이선스 블록에 오류가 표시됨: 블록의 메시지를 따르세요. 예를 들어 키가 다른 도메인에서 이미 사용 중이면 vibefox.net 계정에서 슬롯을 해제하고 Check now를 클릭하세요. 사이트 주소가 바뀌었다면 Check now를 클릭하여 새 도메인에서 키를 활성화하세요. 라이선스 서버에 연결할 수 없으면 플러그인은 마지막으로 확인된 상태로 계속 작동합니다.

제거

플러그인을 비활성화하면 모든 설정은 유지되고 캐시된 요금만 삭제됩니다. 완전히 제거하려면 비활성화한 뒤 Plugins 페이지에서 삭제하세요. 이 플러그인의 라이선스 키와 라이선스 상태, 캐시된 요금, 오래된 로그 파일은 항상 제거됩니다. 설정과 구역 방법은 Remove data on uninstall이 켜져 있었던 경우에만 제거됩니다. 그렇지 않으면 나중에 다시 설치할 때를 위해 남겨집니다. 기존 주문은 배송 항목을 유지합니다.

EasyPost는 해당 소유자의 상표입니다. 이 플러그인은 EasyPost와 제휴하거나 EasyPost의 승인을 받지 않았습니다.