VibeFox PostNL for PrestaShop — 도움말

요구 사항

PrestaShop: 8.0부터 9.x까지, Classic 또는 Hummingbird 테마(또는 이들을 기반으로 한 테마).

PHP: 8.0 이상. 모듈은 이전 PHP 버전에는 설치되지 않습니다.

PostNL API 키(픽업 포인트 전용): 픽업 포인트는 PostNL Checkout API에서 불러옵니다. PostNL 비즈니스 고객은 Mijn PostNL의 My account > API beheren에서 API 키를 찾을 수 있습니다. PostNL 샌드박스에는 별도의 샌드박스 키가 필요합니다. 자택 배송 배송업체는 키가 필요하지 않습니다.

VibeFox 라이선스 키: vibefox.net에서 구매합니다. 키 하나는 도메인 하나에서 작동합니다.

설치

1. 백오피스에서 Modules > Module Manager로 이동하여 Upload a module을 클릭합니다. 모듈의 ZIP 파일을 선택합니다.

2. 업로드가 끝나면 Configure를 클릭하거나, 나중에 모듈 목록에서 VibeFox PostNL을 찾아 Configure를 클릭합니다.

3. Configure 페이지 상단의 라이선스 블록에 있는 License key 필드에 VibeFox 라이선스 키를 입력하고 Activate를 클릭합니다(라이선스 키 참조).

4. 요금을 입력합니다. 픽업 포인트의 경우 PostNL API key와 Ship from (postcode)도 입력합니다(설정 참조). Save를 클릭합니다.

설치 시 모듈은 두 개의 배송업체를 만듭니다. PostNL pickup point는 배송 시간 문구 Delivery to a PostNL pickup point를, PostNL은 PostNL delivery to the home address를 가집니다. 둘 다 네덜란드와 벨기에의 지역, 그리고 모든 고객 그룹에 연결됩니다. 지역을 추가하거나 고객 그룹, 배송 시간, 로고, 크기 제한을 바꾸려면 Shipping > Carriers를 이용하세요. 그곳에서는 요금을 설정하지 마세요. 요금은 항상 모듈에서 가져옵니다.

설정

모든 설정은 모듈 페이지에 있습니다: Modules > Module Manager > VibeFox PostNL > Configure. 각 섹션에는 별도의 Save 버튼이 있으며, 이 버튼은 페이지 전체를 저장합니다. WooCommerce에서는 배송 유형마다 한 번씩, 하나의 방법을 지역에 두 번 추가합니다. PrestaShop에서는 배송 유형마다 고유한 이름, 상태, 지역을 가진 별도의 배송업체가 됩니다.

설정 위쪽에는 경고가 표시됩니다. 픽업 포인트의 API 키 또는 발송지 우편번호 누락, 샌드박스 켜짐, 설정된 요금 없음, 날짜와 오류가 포함된 마지막 실패 PostNL 요청, 모듈이 인식하지 못하는 쇼핑몰 무게 단위, 삭제된 배송업체가 포함됩니다.

일반

PostNL pickup point: 픽업 포인트 배송업체를 켜거나 끕니다. 고객은 체크아웃에서 PostNL 포인트를 선택해야 합니다. 네덜란드와 벨기에 주소에만 제공되며, API 키가 있을 때만 제공됩니다. Shipping > Carriers의 배송업체 상태와 같은 스위치입니다.

Pickup point carrier name: 고객이 체크아웃에서 보는 이름입니다. 기본값: PostNL pickup point. 필수입니다.

PostNL home address: 자택 배송 배송업체를 켜거나 끕니다. 포인트는 선택되지 않습니다. 요금이 설정된 모든 국가에서 작동합니다. 배송업체 상태와 같은 스위치입니다.

Home delivery carrier name: 고객이 체크아웃에서 보는 이름입니다. 기본값: PostNL. 필수입니다.

Tax status: 두 배송업체의 세금 규칙입니다. Taxable 규칙은 해당 규칙의 배송세를 요금에 더합니다. None은 요금이 최종 가격임을 뜻합니다.

PostNL API(픽업 포인트)(자택 배송에는 필요 없음)

API key: Mijn PostNL(My account > API beheren)에서 받은 PostNL API 키입니다. "apikey" 헤더로 PostNL에 전송되며, 고객에게 표시되거나 로그에 기록되지 않습니다. 저장 후 이 필드는 비어 있고 Saved - leave empty to keep it.가 표시됩니다. 변경하려는 경우에만 새 값을 입력하세요.

Remove the saved API key: 체크한 뒤 Save를 클릭하면 저장된 키가 삭제됩니다. 그 후에는 픽업 포인트 배송업체가 제공되지 않습니다.

Sandbox: PostNL 샌드박스(api-sandbox.postnl.nl)와 샌드박스 API 키를 사용합니다. 이 경우 고객에게 테스트용 픽업 포인트가 표시됩니다. 실제 운영 쇼핑몰에서는 끈 상태로 두세요.

Ship from (country): 택배를 PostNL에 넘기는 국가입니다. Netherlands 또는 Belgium. 기본값: Netherlands. PostNL은 수거일 계산에 발송자 주소를 사용합니다.

Ship from (postcode): 발송자의 우편번호입니다. 예: 네덜란드 1234AB, 벨기에 1000. 쇼핑몰이 같은 국가에 있으면 비워 두어 Shop Parameters > Contact > Stores의 쇼핑몰 우편번호를 사용할 수 있습니다. 잘못된 우편번호는 경고와 함께 비어 있는 상태로 저장됩니다. API 키, 샌드박스 설정 또는 발송 주소를 바꾸면 캐시된 픽업 포인트 목록과 마지막 API 오류가 지워집니다.

요금(쇼핑몰 기본 통화, 세금 제외)

요금은 두 배송업체 모두에 적용됩니다. PostNL에는 공개 요금 API가 없으므로 이 모듈은 실시간 요금을 조회하지 않습니다. 다른 통화로 결제하는 고객의 경우 PrestaShop이 쇼핑몰의 환율로 요금을 환산합니다.

Price per country: 배송 대상 국가당 한 행입니다. + Add country를 클릭하면 행이 추가되고, 휴지통 아이콘을 클릭하면 행이 삭제됩니다. 자체 행이 없는 모든 국가를 포함하는 행은 * All other countries를 선택하세요. 각 행에는 Price와, 장바구니 무게에 따른 선택적 무게 등급이 있습니다. XS는 1kg까지, S는 2kg까지, M은 3kg까지, L은 5kg까지, XL은 5kg 초과입니다. 무게 등급 요금은 Price보다 우선합니다. 비워 두면 Price를 사용합니다. Price가 0이면 무료 배송을 뜻합니다. "6.95", "6,95", 그리고 "1.234,50" 또는 "1,234.50"처럼 천 단위 구분 기호가 있는 금액도 허용됩니다. 빈 행과 잘못된 국가 코드는 저장할 때 삭제됩니다. 같은 국가가 두 번 나오면 첫 번째 행이 유지됩니다. 잘못된 요금은 경고와 함께 무시됩니다.

Calculation: Per order는 요금을 한 번만 청구합니다. Per item (price x quantity)는 배송이 필요한 상품 수를 곱합니다.

Price for other countries: 표에 해당 국가도, * 행도 없을 때 사용됩니다. 비워 두면 그 국가에서는 배송업체가 숨겨집니다.

조건

Free shipping from: 무료 배송이 적용되는 장바구니 소계입니다(배송이 필요한 상품, 세금 제외, 할인 후). 요금이 찾아진 경우에만 적용됩니다. 무료 배송을 제공하지 않으려면 비워 두세요.

Minimum subtotal: 장바구니 소계가 이 금액 이상일 때만 배송업체를 표시합니다. 비워 두면 항상 표시합니다.

Minimum weight (kg): 장바구니 무게가 이보다 가벼우면 배송업체를 숨깁니다. 상품 무게는 쇼핑몰의 무게 단위에서 환산됩니다. 비워 두면 제한이 없습니다.

Maximum weight (kg): 더 무거운 장바구니에 대해 배송업체를 숨깁니다. 기본값: 30(PostNL 소포는 베네룩스에서 최대 30kg). 0은 제한 없음을 뜻합니다. 비워 두면 배송업체의 지역에서는 30kg이 적용되고, 제한 없음은 Ignore zones로 도달하는 국가에만 적용됩니다. 최소 무게가 최대 무게보다 크면 배송업체가 전혀 표시되지 않으므로 오류와 함께 거부됩니다.

모든 금액과 무게는 천 단위 구분 기호가 있어도 소수점 쉼표를 허용합니다. 잘못되었거나 음수인 숫자는 경고와 함께 무시되며, 해당 필드는 비어 있는 상태로 저장됩니다.

배송 지역 없이 이용 가능 여부

보통 배송업체는 Shipping > Carriers에서 연결된 배송 지역에서 제공됩니다.

Ignore zones: PostNL의 지역에 포함되지 않은 아래 국가에서도 PostNL을 제공합니다. 그러면 배송업체는 활성화된 모든 지역에 연결되며, 나중에 만드는 지역도 포함됩니다. 다시 끄면 배송업체는 이전에 가졌던 지역을 되돌려받습니다.

Countries: 이 모드의 배송 대상 국가입니다. 모든 국가를 허용하려면 비워 두세요. 이 필드는 Ignore zones가 켜져 있을 때만 사용됩니다. 이 국가들에서는 두 배송업체 모두 제공될 수 있습니다. 다만 픽업 포인트 배송업체는 네덜란드와 벨기에에만 제공됩니다.

고급

Debug log: 모듈 폴더의 logs/vfd_ptnl_debug.log.php에 디버그 메시지를 기록합니다. 이 파일은 웹에서 열 수 없습니다. API 오류는 항상 기록됩니다. API 키나 고객 데이터는 기록되지 않습니다. 작업이 끝나면 로그를 끄세요.

Log: 로그의 크기와 최근 항목을 표시합니다. Clear log를 클릭하면 비워집니다.

Remove data on uninstall: 켜져 있으면 모듈을 제거할 때 PostNL 설정과 배송업체가 삭제됩니다. 꺼져 있으면 제거 시 배송업체만 꺼집니다. 주문에 저장된 픽업 포인트는 항상 유지됩니다.

체크아웃에서의 동작

배송 단계에서 PrestaShop은 각 PostNL 배송업체의 요금을 모듈에 요청합니다. 실물 상품만 계산에 포함됩니다. 가상 상품은 무게를 더하지 않으며 소계에도 포함되지 않습니다. 모듈은 장바구니 무게와 최소 소계 조건을 확인합니다. 그런 다음 국가와 무게 등급에 맞는 요금표의 요금, 또는 그 밖의 국가 요금을 가져옵니다. 요금이 없으면 배송업체는 숨겨집니다. 장바구니 소계가 Free shipping from에 도달하면 요금은 0입니다.

픽업 포인트 배송업체는 네덜란드와 벨기에 주소에만, 그리고 API 키가 있을 때만 제공됩니다. 배송 주소에 유효한 우편번호가 있으면 모듈은 PostNL Checkout API에 가장 가까운 픽업 포인트 3곳을 요청합니다. 고객의 우편번호, 도로명, 건물 번호, 도시, 국가와 귀하의 발송 주소를 보냅니다. 자택 배송 배송업체에는 아무것도 보내지 않습니다. PostNL에 연결할 수 없거나 해당 주소에 포인트가 없으면 픽업 포인트 배송업체는 숨겨지고, 자택 배송 배송업체는 계속 이용할 수 있습니다. API 제한 시간은 12초입니다.

포인트 목록은 우편번호당 6시간, "포인트 없음" 응답은 1시간 캐시됩니다. 실패한 요청은 10분 동안 캐시되므로, 장애가 있어도 체크아웃 새로고침마다 느려지지 않습니다. 마지막 오류는 모듈 페이지에 표시됩니다.

주문이 있는 배송업체를 Shipping > Carriers에서 편집하면 PrestaShop은 이를 새 배송업체 버전으로 저장합니다. 모듈은 새 버전을 자동으로 따릅니다.

모듈은 PostNL 실시간 요금을 조회하지 않으며, 배송 라벨, 바코드, track and trace, 반품, 사전 알림을 생성하지 않습니다. 배송일, 저녁 또는 아침 배송 옵션도 없습니다. 저장된 픽업 포인트를 사용해 Mijn PostNL이나 다른 PostNL 도구에서 발송을 생성하세요.

픽업 포인트

고객이 픽업 포인트 배송업체를 선택하면, 그 아래에 가장 가까운 포인트 3곳의 PostNL pickup point 목록이 나타납니다. 회사 이름, 주소, 거리가 표시됩니다. 페이지는 PostNL을 기다리지 않습니다. 목록이 아직 캐시되지 않았다면 배송업체를 선택하는 즉시 불러옵니다. 전체 우편번호를 입력하기 전에는 고객에게 "PostNL 픽업 포인트를 보려면 우편번호(예: 1234 AB)를 입력하세요."라는 문구가 표시됩니다(벨기에는 4자리). 선택한 포인트는 장바구니에 저장되며, 체크아웃이 새로 고쳐져도 유지됩니다.

포인트 선택은 필수입니다. 선택하지 않으면 고객은 다음 단계로 진행할 수 없고 "PostNL 픽업 포인트를 선택하세요."라는 문구를 보게 됩니다. 고객이 Continue를 클릭하면, 서버가 배송 주소에 대한 PostNL 목록과 포인트를 대조합니다. 목록에 없으면 고객에게 "선택한 PostNL 픽업 포인트는 이 주소에서 사용할 수 없습니다. 다시 선택하세요."라는 문구가 표시됩니다. PostNL에 연결할 수 없으면 "지금은 PostNL 픽업 포인트를 불러올 수 없습니다. 몇 분 후 다시 시도하거나 다른 배송 방법을 선택하세요."라는 문구가 표시됩니다. 다른 주소를 위해 선택한 포인트는 주문에 절대 사용되지 않습니다. 주문과 함께 저장되는 이름과 주소는 브라우저가 아니라 PostNL에서 가져옵니다.

관리자 주문 페이지: 이름과 주소, Location code, Partner ID가 포함된 PostNL pickup point 블록입니다.

주문 접수 페이지와 주문 상세 페이지: 이름과 주소가 포함된 PostNL pickup point입니다.

주문 이메일: 주문 확인 이메일의 배송업체 이름에 포인트의 이름과 주소가 추가됩니다. 쇼핑몰의 새 주문 이메일(Mail alerts 모듈)에는 위치 코드도 표시됩니다.

라이선스 키

이 모듈은 vibefox.net에서 받은 VibeFox 라이선스 키로 작동합니다. 라이선스 블록 License — VibeFox PostNL은 Modules > Module Manager > VibeFox PostNL > Configure 페이지에서 설정 위에 있는 첫 번째 블록입니다. 키를 License key에 입력하고 Activate를 클릭하십시오. 이후 블록에는 마스킹된 키, 상태(예: 라이선스 유효 기간 종료일과 도메인)가 표시되며, Check now(상태 다시 확인), Change key(다른 키 입력), Remove key(이 쇼핑몰에서 키 제거) 버튼이 나타납니다. 그 아래에는 Product: presta-shipping-postnl 줄과 Manage licenses and domains in your account 링크가 있으며, 이 링크는 vibefox.net 계정을 엽니다. 모듈의 Configure 권한이 있는 직원만 키를 변경할 수 있습니다. 블록의 문구는 백오피스 언어를 따릅니다(영어와 러시아어 포함).

키가 승인되지 않으면 블록에 이유가 표시됩니다(예: Key not found, This key belongs to another product, Domain limit reached, 또는 날짜와 함께 표시되는 License expired on). 쇼핑몰 주소를 변경하거나 계정에서 도메인 슬롯을 해제한 후에는 Check now를 클릭하십시오. 라이선스 서버에 연결할 수 없으면 모듈은 마지막으로 확인된 상태로 계속 작동합니다.

키 하나는 도메인 하나에서 작동합니다. 기본 쇼핑몰의 도메인이며, 멀티스토어 설정에서도 마찬가지입니다. 쇼핑몰에서 키를 제거해도 도메인 슬롯은 해제되지 않습니다. vibefox.net 계정에서 슬롯을 해제하십시오.

활성 키가 없으면 체크아웃에서 고객에게 PostNL 배송업체가 표시되지 않으며 배송 요금도 계산되지 않습니다. PrestaShop 스토어프런트는 백오피스에 로그인되어 있다는 것을 알지 못하므로, 배송업체는 관리자에게도 숨겨집니다. 키를 구매하기 전에 모듈을 설정할 수는 있지만 체크아웃에서 테스트할 수는 없습니다. Modules > Module Manager의 Alerts 탭에 알림이 표시됩니다. 기존 주문은 영향을 받지 않습니다.

라이선스가 만료되어도 모듈은 계속 작동하지만, 업데이트와 지원을 받으려면 갱신이 필요합니다. 백오피스에서 작업하는 동안 상태는 자동으로 다시 확인됩니다. 키를 입력한 후 처음 14일 동안은 하루에 한 번, 그 이후에는 일주일에 한 번입니다. cron 작업은 필요하지 않습니다. 모듈을 제거하면 라이선스 키와 라이선스 상태는 항상 삭제됩니다. Reset은 데이터를 삭제하지 않으므로 키와 상태는 유지됩니다.

문제 해결

체크아웃에 PostNL이 나타나지 않음: 라이선스가 활성 상태이고 배송업체 스위치가 켜져 있는지 확인하세요. Shipping > Carriers에서 배송업체가 고객 국가의 지역과 고객 그룹을 포함하는지 확인하세요(또는 Ignore zones가 켜져 있고 해당 국가가 허용되었는지 확인). 해당 국가의 요금, 무게 제한, Minimum subtotal이 설정되어 있는지 확인하세요. 상품 페이지에서 특정 배송업체로 제한된 상품일 수도 있습니다.

픽업 포인트 배송업체가 나타나지 않음: 네덜란드와 벨기에 주소에만, API 키, 발송지 우편번호, 요금이 있을 때만, 그리고 PostNL이 고객의 우편번호에 대해 포인트를 반환할 때만 표시됩니다. 모듈 페이지 상단의 경고와 Log 필드를 확인하세요. 오류는 항상 기록되며, 자세한 내용은 Debug log를 켜서 확인하세요.

"PostNL pickup points cannot be loaded right now": PostNL에 연결할 수 없었거나 API 키가 거부되었거나 발송지 우편번호가 없다는 뜻입니다. 모듈 페이지에 마지막 오류가 표시됩니다. 샌드박스 키는 Sandbox가 켜져 있을 때만, 실제 운영 키는 꺼져 있을 때만 작동합니다.

고객에게 테스트 픽업 포인트가 보임: Sandbox를 끄세요.

상품 무게가 잘못된 것으로 보임: 모듈 페이지에 쇼핑몰 무게 단위를 알 수 없다는 경고가 표시되면, International > Localization의 Local units에서 표준 단위(kg, g, lb 또는 oz)를 설정하세요. 그때까지 상품 무게는 kg으로 읽힙니다.

페이지에 PostNL 배송업체를 찾을 수 없다고 표시됨: Shipping > Carriers에서 배송업체가 삭제되었습니다. Modules > Module Manager에서 모듈을 재설정하면 다시 생성됩니다. 재설정은 설정과 배송업체의 상태를 유지합니다.

제거

Modules > Module Manager로 이동해 VibeFox PostNL 옆의 메뉴를 열고 Uninstall을 선택하세요. 라이선스 키와 라이선스 상태는 항상 삭제됩니다. 캐시된 픽업 포인트 목록과 마지막 API 오류는 항상 삭제됩니다. Remove data on uninstall이 켜져 있으면 배송업체가 삭제되고(주문은 기록을 유지함), 설정과 로그도 제거됩니다. 꺼져 있으면 배송업체만 꺼지고 모든 설정이 유지됩니다. 모듈을 다시 설치하면 배송업체는 이전의 상태를 되찾습니다. 기존 주문은 배송 항목과 저장된 픽업 포인트를 유지합니다.

PostNL은 각 소유자의 상표입니다. 이 모듈은 PostNL과 제휴하거나 PostNL의 승인을 받지 않았습니다.