VibeFox Canada Post for PrestaShop — 도움말

요구 사항

PrestaShop: 8.0 ~ 9.x.

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

Canada Post Developer Program (실시간 요금에만 필요): 실시간 요금은 Canada Post Rating API를 사용합니다. Canada Post 웹사이트에서 Canada Post Developer Program에 가입하고 API 키와 고객 번호를 복사하십시오. API 키는 username:password 형식이며, Canada Post는 개발(샌드박스) 환경과 운영 환경에 대해 각각 별도의 키를 제공합니다. 또한 발송지인 캐나다 우편번호도 필요합니다. 고정 요금만 사용하는 경우에는 API 키가 필요하지 않습니다.

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

설치

1. 관리자 페이지에서 Modules > Module Manager로 이동한 뒤 Upload a module을 클릭합니다. 모듈의 ZIP 파일을 선택합니다.

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

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

4. 실시간 요금을 사용하려면 API 사용자 이름과 비밀번호, 고객 번호, 발송지 우편번호를 입력합니다. 쇼핑몰의 기본 통화가 CAD가 아니라면 CAD 환율을 입력합니다. 고정 요금이나 대체 요금이 필요하면 Country prices를 작성합니다(설정 참조). Save를 클릭합니다.

설치 시 모듈은 배송 기간 문구 Canada Post parcel delivery를 가진 Canada Post 배송사를 생성합니다. 이 배송사는 모든 지역과 모든 고객 그룹에 할당됩니다. 지역, 고객 그룹, 배송 기간, 로고, 크기 제한은 Shipping > Carriers에서 변경할 수 있습니다. 그곳에서는 가격을 설정하지 마십시오. 가격은 항상 모듈에서 가져옵니다.

설정

모든 설정은 모듈 페이지에 있습니다: Modules > Module Manager > VibeFox Canada Post > Configure. 각 섹션에는 별도의 Save 버튼이 있으며, 이 버튼은 페이지 전체를 저장합니다. 저장할 때마다 캐시된 Canada Post 요금도 지워집니다. 저장하려면 모듈의 구성 권한이 필요합니다.

값이 잘못되면 페이지에 오류가 표시되고 아무것도 저장되지 않습니다: 숫자 필드나 Country prices의 가격이 0 이상의 숫자가 아닌 경우(예: -1 또는 12abc), CAD 환율이 0인 경우, Min cart weight (kg)가 Max cart weight (kg)보다 큰 경우, 또는 Method title이 64자를 넘는 경우입니다. 쇼핑몰의 무게 또는 치수 단위를 모듈이 인식하지 못하면, 페이지는 무게를 kg(치수는 cm)로 읽는다고 경고합니다. International > Localization의 Local units 섹션에서 kg, g, lb 또는 oz(cm, mm, m 또는 in)를 설정하십시오.

저장 후 설정이 의도대로 작동할 수 없는 경우 페이지에 경고가 표시됩니다: API 사용자 이름과 비밀번호 중 하나만 입력된 경우, 발송지 우편번호가 캐나다 우편번호 형식(A1A 1A1)이 아닌 경우, 다른 통화의 쇼핑몰에 CAD 환율이 없는 경우, 또는 API 자격 증명도 고정 요금도 없는 경우입니다. 경고에는 그 사이에 무슨 일이 일어나는지도 나와 있습니다: 국가별 고정 요금이 사용되거나, Country prices 표가 비어 있으면 체크아웃에서 배송사가 숨겨집니다.

일반

Enable Canada Post: 배송사를 켜거나 끕니다. 이는 Shipping > Carriers의 배송사 상태와 같은 스위치입니다.

Method title: 체크아웃에서 고객에게 표시되는 배송사 이름입니다. 필드를 비워 두어도 기본값은 Canada Post입니다. 최대 64자이며, PrestaShop이 배송사 이름에 허용하지 않는 문자는 사용할 수 없습니다.

Tax: PrestaShop이 배송비에 추가하는 세금 규칙, 또는 No tax(비과세)입니다.

Canada Post API (실시간 요금)

API 사용자 이름과 비밀번호를 입력하면 요금은 Canada Post Rating API에서 가져옵니다. API가 요금을 반환하지 않으면(API 중단, 잘못된 우편번호, 서비스 제공 불가), Country prices의 고정 요금이 사용되며, 고정 요금이 없으면 배송사가 숨겨집니다. 이 섹션에는 Canada Post Developer Program으로 가는 링크가 있으며, 그곳에서 API 키와 고객 번호를 확인할 수 있습니다. 오류 상세 정보는 로그에 기록되며, 고객에게는 절대 표시되지 않습니다.

API username: API 키에서 콜론 앞부분입니다. 개발용 키는 Sandbox와 함께, 운영 쇼핑몰에서는 운영용 키를 사용하십시오.

API password: API 키에서 콜론 뒷부분입니다. 저장한 후에는 이 필드가 비워지고 A password is saved. Leave empty to keep it; clear the username and save to remove both.라고 표시됩니다. 변경하려는 경우에만 새 값을 입력하십시오. 비밀번호는 입력한 그대로 저장되며, 로그에는 절대 기록되지 않습니다.

Customer number: 고객 번호를 입력하면 Canada Post가 계정의 상업(할인) 요금을 반환합니다. 일반(창구) 요금을 원하면 비워 두십시오. 공백은 제거됩니다.

Contract number: 계약 고객을 위한 선택 사항입니다. 고객 번호와 함께 사용할 때만 쓰입니다.

Sandbox: 개발용 API 키로 테스트하기 위해 Canada Post 개발 환경을 사용합니다. 요금은 테스트 데이터입니다. 운영 쇼핑몰에서는 끄십시오.

Ship-from postal code: 소포를 발송하는 캐나다 우편번호입니다(예: K1A 0B1). 실시간 요금에 필요합니다.

Service in Canada: 캐나다 주소에 대한 서비스입니다: Cheapest available, Regular Parcel(DOM.RP, 기본값), Expedited Parcel(DOM.EP), Xpresspost(DOM.XP), Priority(DOM.PC).

Service to the USA: Cheapest available(기본값), Expedited Parcel USA(USA.EP), Tracked Packet USA(USA.TP), Small Packet USA Air(USA.SP.AIR), Xpresspost USA(USA.XP), Priority Worldwide parcel USA(USA.PW.PARCEL).

International service: Cheapest available(기본값), International Parcel Surface(INT.IP.SURF), International Parcel Air(INT.IP.AIR), Tracked Packet International(INT.TP), Small Packet International Surface(INT.SP.SURF), Small Packet International Air(INT.SP.AIR), Xpresspost International(INT.XP), Priority Worldwide parcel International(INT.PW.PARCEL).

선택한 서비스가 주소나 소포에 제공되지 않으면 이용 가능한 가장 저렴한 서비스가 사용됩니다.

Use Canada Post prices without GST/HST/PST: 캐나다 주소의 경우 Canada Post 요금에 이러한 세금이 포함됩니다. PrestaShop이 배송비에 세금을 직접 부과하는 경우(위의 Tax) 이 옵션을 켜서 세금이 이중으로 부과되지 않도록 하십시오.

CAD to … rate: 필드 이름은 쇼핑몰의 기본 통화를 보여줍니다(예: CAD to USD rate). Canada Post 요금은 CAD로 표시됩니다. 기본 통화가 CAD가 아니라면 1 CAD가 쇼핑몰 통화로 몇 단위인지 입력하십시오(예: 0.68). 이 값이 없으면 실시간 요금은 사용되지 않습니다. 기본 통화가 CAD라면 비워 두십시오. 환율은 0보다 커야 합니다. 소수점 구분자로 점과 쉼표 모두 허용됩니다.

Default product weight (kg): 무게가 없는 각 상품에 대해 Canada Post로 전송되는 무게입니다. 기본값: 0.5. 상품 무게(쇼핑몰의 무게 단위 기준)와 치수는 변환되며, 장바구니는 하나의 소포로 계산됩니다.

고정 요금(API 자격 증명 없이 사용하거나 API가 요금을 반환하지 않을 때의 대체 요금으로 사용됩니다)

Country prices: 국가 표입니다. 쇼핑몰의 기본 통화로, 세금 제외, 장바구니 무게별 요금과 Base 요금을 설정합니다: XS 1 kg까지, S 1–2 kg, M 2–3 kg, L 3–5 kg, XL 5 kg 초과. 크기별 요금이 비어 있거나 0이면 Base 요금이 사용됩니다. Add country를 클릭하면 행이 추가되고, 십자 표시를 클릭하면 행이 삭제됩니다. * Default (all other countries) 행은 자체 행이 없는 모든 국가의 요금을 설정합니다. 행이 없는 국가(그리고 *도 없는 경우)는 고정 요금을 받지 않습니다. 기본 요금이 0이면 해당 국가는 무료 배송입니다. 어떤 요금도 입력되지 않은 행은 저장되지 않습니다.

Fixed price per: Order는 요금을 한 번만 청구합니다. Item (price x quantity)은 장바구니의 상품 수량을 곱합니다. 이는 고정 요금에만 적용됩니다. 실시간 요금은 항상 소포 전체를 기준으로 계산됩니다.

조건

Min cart weight (kg): 장바구니 무게가 이 값보다 작으면 배송사를 숨깁니다. 0은 제한 없음을 뜻합니다.

Max cart weight (kg): 장바구니 무게가 이 값보다 크면 배송사를 숨깁니다. 기본값: 25(필드가 비어 있어도 적용됩니다). 0은 제한 없음을 뜻합니다. Canada Post 소포는 최대 30 kg까지 가능합니다. Min cart weight (kg)보다 작을 수 없습니다.

Minimum order amount: 장바구니 소계(할인 후 상품 금액, 세금 제외)가 이 금액에 도달한 경우에만 배송사를 표시합니다. 항상 표시하려면 비워 두십시오.

Free shipping: 아래 금액 이상일 때 무료 배송을 켭니다.

Free shipping from: 배송비가 무료가 되는 장바구니 소계입니다. 이 경우 API 요청은 이루어지지 않습니다. Free shipping이 켜져 있을 때만 사용됩니다.

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

일반적으로 배송사는 Shipping > Carriers에서 할당된 지역에 표시됩니다.

Ignore shipping zones: 어느 지역이 일치하든 관계없이, 아래 국가에 대해 배송사를 제공합니다. 저장하면 배송사는 모든 지역에 추가되며, 나중에 만드는 지역에도 추가됩니다. 이 옵션을 끄고 저장하면 모듈이 추가한 지역은 다시 제거되고, 배송사는 자체 지역을 유지합니다.

Countries: 이 모드의 목적지 국가입니다. 여러 국가를 선택하려면 Ctrl(Cmd)을 누른 채로 클릭하십시오. 활성 상태의 모든 국가를 허용하려면 비워 두십시오. 이 필드는 Ignore shipping zones가 켜져 있을 때만 사용됩니다.

고급

Debug log: 요금 계산을 var/logs/vfd_canada_post.log.php에 기록합니다. 이 파일은 웹에서 열 수 없으며, 5 MB에 도달하면 교체됩니다. 이 옵션이 꺼져 있어도 API 오류는 항상 기록됩니다. API 키, 고객 번호, 고객 우편번호는 기록되지 않습니다.

Remove data on uninstall: 켜져 있으면 모듈을 제거할 때 설정, 저장된 주문 서비스, 캐시된 요금, 로그가 삭제됩니다. 제거할 때 배송사는 항상 체크아웃에서 삭제됩니다. 주문은 절대 변경되지 않습니다.

Log: 설정 아래의 패널에는 파일 이름과 최근 50개 항목이 표시됩니다. Clear log를 클릭하면 삭제됩니다.

체크아웃에서의 작동 방식

배송 단계에서 PrestaShop은 모듈에 Canada Post 요금을 요청합니다. 실물 상품만 계산에 포함됩니다. 가상 상품은 무게를 더하지 않으며 주문 금액에도 포함되지 않습니다. 모듈은 먼저 조건을 확인합니다: 허용된 국가(Ignore shipping zones 사용 시), 장바구니 무게, 최소 주문 금액. 무료 배송이 적용되면 요금은 0이 되며, Canada Post로 요청이 전송되지 않습니다.

API 자격 증명이 있으면, 모듈은 Canada Post에 발송지 우편번호, 목적지, 소포 무게, 그리고 모든 상품에 치수가 있는 경우 추정 소포 크기를 보냅니다. 캐나다의 경우 목적지는 우편번호이고, 미국의 경우 ZIP 코드이며, 그 밖의 모든 국가는 국가만 보냅니다. 실시간 요금은 캐나다 또는 미국 주소에 유효한 우편번호 또는 ZIP 코드가 있을 때만 요청됩니다. Canada Post는 소포에 대한 모든 서비스를 반환합니다. 모듈은 목적지 그룹에서 선택된 서비스를 고르거나, 가장 저렴한 서비스를 고릅니다. Use Canada Post prices without GST/HST/PST가 켜져 있으면 캐나다 판매세(GST/HST/PST)를 제외하고, CAD 요금을 설정한 환율로 환산합니다. 요금은 쇼핑몰의 기본 통화로 계산된 후, 고객의 장바구니 통화로 표시됩니다.

각 응답은 1시간 동안 캐시되므로, 같은 장바구니와 주소에 대해 새 요청이 발생하지 않습니다. 실패한 요청은 10분 동안 캐시되므로, Canada Post 장애가 체크아웃 새로 고침을 매번 느리게 만들지 않습니다. API 제한 시간은 10초입니다. 30 kg을 넘는 소포는 API로 전송되지 않습니다.

API가 요금을 반환하지 않으면 고정 요금이 사용되며, 고정 요금이 없으면 배송사가 숨겨집니다. 고객은 API 오류 상세 정보를 보지 않으며, 이는 로그에 기록됩니다.

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

모듈은 요금만 계산합니다. 배송 건 생성, 라벨 인쇄, 송장이나 반품 생성, 소포 추적은 하지 않습니다. 고객은 우체국이나 픽업 장소를 선택할 수 없습니다. 배송일, 보험, 서명 옵션 없이 Canada Post 요금 하나만 표시합니다. 장바구니는 항상 하나의 소포로 계산되며, 통화 환율은 자동으로 업데이트되지 않습니다.

주문

Canada Post 배송사로 주문이 이루어지면, 모듈은 해당 요금이 어떻게 계산되었는지를 저장합니다. 관리자 페이지의 주문 화면(Orders > Orders, 주문 열기)에서 Canada Post 블록에 다음 내용이 표시됩니다:

Canada Post service: 실시간 요금의 서비스 이름과 코드(예: Regular Parcel (DOM.RP)).

Price source: Live rate (Canada Post Rating API), Fixed price, Free shipping 중 하나.

라이선스 키

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

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

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

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

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

문제 해결

체크아웃에 Canada Post가 나타나지 않음: 라이선스가 활성 상태인지, Enable Canada Post가 켜져 있는지 확인하십시오. Shipping > Carriers에서 배송사가 고객 국가의 지역과 고객의 그룹을 포함하는지 확인하십시오(또는 Ignore shipping zones가 켜져 있고 해당 국가가 허용되어야 합니다). 무게 제한과 Minimum order amount를 확인하십시오. 요금이 있어야 합니다. API 자격 증명을 사용하는 경우 주소에 유효한 우편번호(캐나다) 또는 ZIP 코드(미국)가 있어야 하며, 그렇지 않으면 해당 국가 또는 *에 대한 고정 요금이 있어야 합니다. 또한 상품 페이지에서 상품이 특정 배송사로만 제한되어 있을 수도 있습니다.

실시간 요금이 표시되지 않음: Debug log를 켜고 체크아웃을 새로 고친 후, 모듈 페이지의 Log 패널을 확인하십시오. 원인이 표시됩니다: API 사용자 이름 또는 비밀번호 누락, 잘못된 발송지 또는 목적지 우편번호, CAD 환율 누락, 30 kg을 넘는 소포, 또는 Canada Post 오류 메시지. 그 사이 고정 요금이 있으면 고객은 고정 요금을 받게 됩니다.

요금이 Canada Post 웹사이트와 다름: 고객 번호를 입력하면 계정의 상업(할인) 요금을 받게 되고, 입력하지 않으면 일반(창구) 요금을 받게 됩니다. 캐나다 주소의 경우 Canada Post 요금에는 GST/HST/PST가 포함됩니다. 요금은 CAD 환율로 환산됩니다.

배송비에 세금이 이중으로 부과됨: Use Canada Post prices without GST/HST/PST를 켜거나, Tax를 No tax로 설정하십시오.

운영 쇼핑몰에서 요금 테스트: Sandbox를 끄고 운영용 API 키를 사용하십시오.

변경 후 요금이 오래된 것처럼 보임: 모듈 페이지에서 Save를 클릭하십시오. 캐시된 Canada Post 요금이 지워집니다.

페이지에 Canada Post 배송사가 없다고 표시됨: Shipping > Carriers에서 배송사가 삭제되었습니다. Modules > Module Manager에서 모듈을 초기화하면 다시 생성됩니다.

이 모듈을 구성할 권한이 없음: 직원 프로필은 모듈 페이지를 열 수는 있지만 저장할 수는 없습니다. 관리자에게 프로필에 모듈 구성 권한을 부여해 달라고 요청하십시오.

제거

Modules > Module Manager로 이동하여 VibeFox Canada Post 옆의 메뉴를 열고 Uninstall을 선택합니다. 라이선스 키와 라이선스 상태는 항상 제거됩니다. 배송사는 항상 체크아웃에서 제거됩니다(주문은 배송사와 이력을 유지합니다). Remove data on uninstall이 켜져 있으면 설정, 저장된 주문 서비스, 캐시된 요금, 로그가 삭제됩니다. 꺼져 있으면 캐시된 요금만 제거되고 모든 설정은 유지됩니다. 모듈을 다시 설치하면(또는 Reset) 이전 배송사가 이전 상태로 복원됩니다. 비활성화했던 배송사는 계속 비활성 상태로 남습니다.

Canada Post는 해당 소유자의 상표입니다. 이 모듈은 Canada Post와 제휴하거나 Canada Post의 승인을 받은 것이 아닙니다.