VibeFox Packeta for WooCommerce — 도움말

요구 사항

WordPress: 5.8 이상.

WooCommerce: 7.0 이상이 설치되어 있고 활성화되어 있어야 합니다. WooCommerce가 없으면 플러그인을 활성화할 수 없습니다.

PHP: 8.0 이상.

Packeta API 키: Packeta 클라이언트 영역(client.packeta.com)의 Client support에서 찾을 수 있습니다. 16자의 문자와 숫자로 되어 있습니다. 위젯이 체크아웃에서 열리려면 이 키가 필요하므로, API 키를 입력하기 전에는 고객에게 이 배송 방법이 표시되지 않습니다.

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

설치

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

2. Activate를 클릭합니다.

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

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

5. Packeta API key와 요금을 입력합니다. Country prices의 행을 최소 하나(예: * Default) 또는 Fallback cost를 설정하세요. 저장하면 Packeta가 키를 승인했는지 페이지에 표시됩니다.

6. WooCommerce > Settings > Shipping > Shipping zones에서 체코, 슬로바키아, 헝가리 또는 루마니아의 배송 지역에 VibeFox Packeta를 추가하거나 Ignore shipping zones를 켭니다.

구성

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

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

이 방법은 Packeta 자체 픽업 포인트 네트워크의 국가인 CZ, SK, HU, RO에만 제공됩니다. 설정 위에는 API 키 확인 결과와, API 키 없음, 요금 없음, 선택한 국가가 Packeta 네트워크 밖에 있음 등의 문제에 대한 경고가 표시됩니다.

모든 요금과 한도는 소수점 구분자로 쉼표 또는 마침표를 받습니다(4,99 또는 4.99). 잘못된 숫자는 메시지와 함께 거부되며, 이전 값이 유지됩니다.

일반

Enable/Disable: 모든 지역에서 이 방법을 한 번에 켜거나 끕니다.

Name: 고객에게 표시되는 배송 방법 이름입니다. 지역은 자체 Title로 이를 덮어쓸 수 있습니다. 기본값: Packeta pickup point.

API key: client.packeta.com > Client support에서 확인한 Packeta API 키입니다. 32자의 API 비밀번호를 붙여넣을 수도 있습니다. 이때는 처음 16자, 즉 API 키만 저장됩니다. API 키는 공개 정보입니다. 위젯을 열기 위해 고객의 브라우저로 전송됩니다. 새 키를 저장하면 Packeta 운송사 피드로 확인되며, 페이지에 Packeta API key verified가 표시되거나 Packeta가 키를 거부했다고 표시됩니다. 확인을 실행할 수 없으면 키는 저장되고, 다음 저장 때 다시 확인됩니다.

Widget language: 픽업 포인트 위젯의 언어입니다. Store / visitor language(기본값)는 페이지 언어를 따릅니다. 체코어, 슬로바키아어, 헝가리어, 루마니아어, 영어, 독일어, 폴란드어, 우크라이나어 중 하나로 고정할 수도 있습니다.

Pickup point types: 위젯에 표시할 Packeta 포인트입니다.

Tax status: Taxable은 WooCommerce 세금을 배송비에 더하고, None은 더하지 않습니다.

요금

Packeta에는 공개된 요금 API가 없습니다. 요금은 이 표에서 가져오며 쇼핑몰 통화로 입력합니다.

Calculation type: Per order는 요금을 한 번만 부과합니다. Per item (price x quantity)는 요금에 장바구니의 배송 가능한 상품 수를 곱합니다.

Country prices: 배송 국가와 소포 무게별 요금입니다. + Add country를 클릭하면 행이 추가되고, 엑스 표시를 클릭하면 행이 삭제됩니다. 각 행에는 Price와 무게 열이 있습니다: XS는 1 kg까지, S는 1–2 kg, M은 2–3 kg, L은 3–5 kg, XL은 5 kg 초과입니다. 무게 열을 0으로 두면 Price 열이 사용됩니다. 자체 행이 없는 국가에는 * Default 행이 사용됩니다. 새 행은 모든 요금이 0인 * Default로 시작하며, 이는 무료 배송을 뜻합니다. 저장하기 전에 국가를 선택하고 요금을 입력하거나 행을 삭제하세요. 같은 국가가 두 행에 있으면 저장 시 첫 번째 행만 남습니다.

Fallback cost: 국가 표에 배송지용 행이 없고 * Default 행도 없을 때 사용됩니다. 비워 두면 그 지역에는 이 방법을 제공하지 않습니다.

Free shipping from: Packeta 배송이 무료가 되는 장바구니 소계(할인 후, 세금 제외)입니다. 요금이 설정된 곳에만 적용됩니다: 국가 행, * Default 행 또는 대체 요금. 비워 두면 무료 배송을 제공하지 않습니다.

제공 조건

Minimum weight (kg): 장바구니 무게가 이보다 가벼우면 이 방법을 숨깁니다. 장바구니 무게는 쇼핑몰의 무게 단위에서 변환됩니다. 비워 두거나 0이면 제한이 없습니다.

Maximum weight (kg): 장바구니 무게가 이보다 무거우면 이 방법을 숨깁니다. 기본값: 15. Packeta 픽업 포인트와 Z-BOX는 보통 15 kg까지의 소포를 받습니다. Packeta 계약을 확인하세요. 비워 두거나 0이면 제한이 없습니다.

Minimum cart subtotal: 장바구니 소계(할인 후, 세금 제외)가 이 금액에 도달해야만 이 방법을 제공합니다.

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

Ignore shipping zones: 켜면, 해당 배송 지역에 추가되어 있지 않아도 아래에서 선택한 국가에 이 방법을 제공합니다. 끄면 추가된 지역에서만 제공합니다.

Countries (ignore zones mode): 이 모드에서 사용하는 배송 국가입니다. 비워 두면 Packeta의 모든 국가를 사용합니다. Packeta 픽업 포인트 네트워크 밖의 국가는 건너뜁니다. 이 필드는 Ignore shipping zones가 켜져 있을 때만 사용됩니다.

고급

Debug log: 요금 계산과 픽업 포인트 선택 내역을 WooCommerce > Status > Logs(출처 "vfd-packeta")에 기록합니다. 고객의 개인 정보와 API 키는 기록되지 않습니다. API 키 확인에 실패하면 항상 기록됩니다. 작업이 끝나면 로그를 끄세요.

Remove data on uninstall: 켜면 플러그인을 삭제할 때 이 방법의 설정과 지역 인스턴스가 제거됩니다. 플러그인을 비활성화해도 아무것도 삭제되지 않습니다. 주문에 저장된 픽업 포인트는 항상 유지됩니다.

체크아웃에서의 동작

고객이 배송지 주소를 입력하면 WooCommerce가 플러그인에 요금을 요청합니다. 플러그인은 조건을 확인합니다: 배송 국가가 Packeta 네트워크에 있는지, API 키, 장바구니 무게, 장바구니 최소 소계, 제외된 배송 클래스. 요금은 국가 표에서 가져오고, 없으면 대체 요금을 사용합니다. 요금이 없으면 이 방법은 숨겨집니다. 무료 배송이 적용되면 고객은 비용 없이 이 방법을 봅니다.

고객이 Packeta 방법을 선택하면, 그 아래에 Choose pickup point 버튼이 나타납니다. 이 버튼은 고객의 브라우저에서 배송 국가, 장바구니 무게, 선택한 포인트 유형, 위젯 언어와 함께 Packeta 공식 위젯을 엽니다. 고객이 포인트를 선택하면 그 이름과 주소가 방법 아래에 표시되고, 버튼은 Change pickup point로 바뀝니다. 선택 내용은 체크아웃이 새로 고쳐지거나 페이지를 다시 불러와도 고객의 세션에 기억됩니다.

체크아웃 중에는 쇼핑몰 서버가 Packeta에 아무것도 요청하지 않습니다. 위젯 스크립트는 widget.packeta.com에서 로드됩니다. 광고 또는 개인정보 차단기, 콘텐츠 보안 정책, Packeta 장애 때문에 차단되면 고객에게 다음 메시지가 표시됩니다: “The Packeta pickup point widget could not be loaded. Please reload the page or choose another shipping method.”

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

Packeta 요금은 실시간으로 조회하지 않으며, 쇼핑몰의 요금표에서 가져옵니다. 이 플러그인은 Packeta 배송 건을 생성하거나, 운송장을 인쇄하거나, 소포를 추적하지 않습니다. 또한 기본적으로 자택 배송이나 협력 운송사의 픽업 포인트를 제공하지 않습니다. 주문의 픽업 포인트 ID는 평소 방식대로 Packeta에 전달하세요. 예를 들어 client.packeta.com에서 가져오기로 전달할 수 있습니다.

픽업 포인트

픽업 포인트는 필수입니다. 고객이 포인트를 선택하지 않고 주문하면, 체크아웃은 “Please choose a Packeta pickup point.” 메시지와 함께 중단됩니다. 선택한 포인트가 배송지와 다른 국가에 있으면, 체크아웃은 “The selected Packeta pickup point is not in your shipping country. Please choose a pickup point again.” 메시지와 함께 중단됩니다. 두 검사는 모두 서버에서 실행되며, 클래식 체크아웃과 블록 체크아웃 모두에 적용됩니다. 플러그인은 포인트 ID를 Packeta에서 검증하지 않습니다. 포인트가 선택되었는지, 그리고 그 국가가 일치하는지만 확인합니다.

포인트는 주문이 생성될 때 주문과 함께 저장됩니다:

관리자 주문 화면: 배송지 주소 아래에 Packeta pickup point로 이름, 주소, Pickup point ID, 국가가 표시됩니다. Packeta 주문에 포인트가 없으면 화면에 “No pickup point was selected for this order.”가 표시됩니다.

주문 완료 페이지 및 주문 보기: Packeta pickup point:와 함께 이름과 주소가 표시됩니다.

주문 이메일: HTML 및 일반 텍스트 이메일에 포인트 이름과 주소가 포함됩니다. 관리자 이메일에는 Pickup point ID도 포함됩니다.

데이터베이스에서 포인트는 주문 메타데이터 _vfd_pckt_point_id, _vfd_pckt_point_name(이름과 주소), _vfd_pckt_point_country에 저장됩니다.

라이선스 키

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

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

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

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

문제 해결

체크아웃에 Packeta가 나타나지 않음: 라이선스가 활성 상태인지, Enable/Disable이 켜져 있는지, API key가 입력되어 있는지, 배송 국가가 CZ, SK, HU, RO 중 하나인지 확인하세요. 해당 국가에 요금이 설정되어 있는지(국가 행, * Default 행 또는 Fallback cost), 무게 및 소계 한도, Excluded shipping classes, 그리고 이 방법이 해당 배송 지역에 추가되어 있는지(또는 Ignore shipping zones가 켜져 있는지)를 확인하세요. 설정 페이지 상단에 구성 문제가 나열됩니다. 이유를 확인하려면 Debug log를 켜고 WooCommerce > Status > Logs를 보세요.

Packeta가 API 키를 거부함: client.packeta.com > Client support에서 API 키를 다시 복사하여 저장하세요. 그 전까지는 체크아웃에서 위젯을 열 수 없습니다.

위젯이 열리지 않음: Packeta 스크립트가 광고 또는 개인정보 차단기, 콘텐츠 보안 정책, 또는 Packeta 장애로 차단되었습니다. 콘텐츠 보안 정책에서 widget.packeta.com을 허용하세요. 개발자는 vfd_pckt_widget_url 필터로 스크립트 URL을 변경할 수 있습니다.

배송이 실수로 무료로 표시됨: Country prices에서 Price가 0인 행을 확인하세요. 특히 + Add country로 추가하고 채우지 않은 * Default 행을 확인하세요.

다른 국가 또는 운송사: 기본적으로 이 방법은 CZ, SK, HU, RO에서 작동합니다. 개발자는 vfd_pckt_countries 필터로 국가를 추가하고, vfd_pckt_widget_options 필터로 운송사 ID를 위젯에 전달할 수 있습니다.

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

제거

플러그인을 비활성화하면 모든 데이터가 유지됩니다. 완전히 제거하려면 비활성화한 뒤 Plugins 페이지에서 삭제하세요. 이 플러그인의 라이선스 키와 라이선스 상태는 저장된 API 키 확인 기록과 함께 항상 삭제됩니다. 설정과 지역별 방법은 Remove data on uninstall이 켜져 있을 때만 삭제됩니다. 그렇지 않으면 나중에 다시 설치할 때를 위해 남아 있습니다. 기존 주문은 배송 항목과 저장된 픽업 포인트를 유지합니다.

Packeta는 각 소유자의 상표입니다. 이 플러그인은 Packeta와 제휴 관계가 아니며 Packeta의 승인을 받지 않았습니다.