VibeFox EasyPost for PrestaShop — 도움말

요구 사항

PrestaShop: 8.0 ~ 9.x.

PHP: cURL 확장이 포함된 8.0 이상. 이 조건이 충족되지 않으면 모듈 설치가 거부됩니다.

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

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

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

설치

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

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

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

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

5. 기본 통화가 USD가 아니라면 USD exchange rate를 입력합니다. 원하면 대체 가격도 입력합니다(설정 참조). Save를 클릭합니다.

설치 시 모듈은 배송 시간 텍스트 Live carrier rate (EasyPost)를 갖는 EasyPost Shipping 운송업체를 만듭니다. 이 운송업체는 모든 구역과 모든 고객 그룹에 할당됩니다. 구역, 고객 그룹, 배송 시간, 로고, 크기 제한은 Shipping > Carriers에서 변경할 수 있습니다. 가격은 여기서 설정하지 마십시오. 가격은 항상 모듈에서 가져옵니다.

설정

모든 설정은 모듈 페이지에 있습니다: Modules > Module Manager > VibeFox EasyPost > Configure. 각 섹션에는 전체 페이지를 저장하는 자체 Save 버튼이 있습니다. 저장할 때마다 캐시된 EasyPost 요금도 지워집니다.

페이지 상단에는 실시간 요금을 사용할 수 없을 때 경고가 표시됩니다. API 키가 없는 경우(대체 가격 유무와 관계없이), 출발지 우편번호나 국가가 없는 경우, 또는 기본 통화가 환율 없이 USD가 아닌 경우입니다. 테스트 API 키가 설정되어 있으면 참고 문구가, 모듈의 운송업체가 삭제되었으면 오류가, 쇼핑몰의 무게 또는 치수 단위(International > Localization)가 모듈이 인식하지 못하는 단위이면(kg, g, lb, oz; cm, mm, m, in) 경고가 표시됩니다.

저장할 때 숫자가 아니거나(또는 음수인) 값은 저장되지 않습니다. 경고에 해당 필드가 표시되고 이전 값이 유지됩니다. USD exchange rate가 0이거나 Minimum weight가 Maximum weight보다 큰 경우에도 같은 방식으로 처리됩니다.

일반

Enable EasyPost shipping: 운송업체를 켜거나 끕니다. Shipping > Carriers의 운송업체 상태와 같은 스위치입니다. 기본값: on.

Name: 체크아웃에서 고객에게 표시되는 운송업체 이름이며, 최대 64자입니다(더 긴 이름은 거부되고 아무것도 저장되지 않습니다). 기본값: EasyPost Shipping. 이름이 비어 있거나 PrestaShop이 운송업체 이름에 허용하지 않는 문자를 포함하면 기본 이름이 사용됩니다.

EasyPost 계정

API key: EasyPost Dashboard > Account Settings > API Keys의 EasyPost API 키입니다. 운영용 키(EZAK로 시작)는 실제 요금을 반환합니다. 테스트 키(EZTK로 시작)는 EasyPost 테스트 요금을 반환하므로 테스트 용도로만 사용하십시오. 저장한 뒤에는 필드가 비어 있고, 저장된 키가 EZAK******abcd처럼 마스킹되어 표시됩니다. 키를 유지하려면 필드를 비워 두십시오. 키를 바꾸려는 경우에만 새 값을 입력하십시오.

Remove the saved API key: 이 상자를 선택하고 Save를 클릭하면 저장된 키가 삭제됩니다.

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

출발지

소포를 보내는 주소입니다. Country가 쇼핑몰 국가이면, 빈 필드는 Shop Parameters > Contact > Stores의 쇼핑몰 주소에서 채워집니다(보내는 사람 이름은 쇼핑몰 이름에서 가져옵니다).

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

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

City: 출발지 도시입니다.

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

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

Country: 발송하는 국가입니다. 기본값: United States.

요금

Parcels: 장바구니를 EasyPost에 보내는 방식입니다.

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

USD exchange rate: EasyPost 요금은 USD 기준입니다. 기본 통화로 1 USD의 가격을 입력하십시오(예: 0.92). 이 값이 없으면 실시간 요금은 사용되지 않고 대체 가격만 사용됩니다. 기본 통화가 USD이면 필요하지 않습니다. USD 및 CAD 쇼핑몰은 EasyPost가 자체 통화로 견적을 내도록 요청합니다. 소수점 구분자로 점과 쉼표를 모두 사용할 수 있습니다.

Tax: 운송업체의 세금 규칙 또는 No tax입니다. EasyPost 요금에는 판매세가 포함되지 않습니다. 배송에 적용되는 세금 규칙을 선택하십시오.

대체 가격

실시간 요금이 없을 때 사용됩니다. API 키가 없거나, EasyPost에 연결할 수 없거나, 키가 거부되었거나, 어떤 운송업체도 해당 주소의 요금을 제공하지 않을 때입니다. 가격은 기본 통화로 표시되며 세금은 제외됩니다. 이 경우 운송업체를 숨기려면 두 필드를 모두 비워 두십시오.

Country prices: 국가당 한 줄입니다. 두 글자 국가 코드, 콜론, 가격 순으로 입력합니다(예: US:9.99). 다른 형식의 줄은 무시되며, 저장할 때 경고에 나열됩니다.

Other countries: 위 목록에 없는 국가의 가격입니다. 비워 두면 해당 국가에서는 운송업체가 숨겨집니다.

조건

Free shipping from: 이 금액 이상이면 배송이 무료가 되는 장바구니 소계입니다(배송 대상 상품, 할인 후, 세금 전, 기본 통화 기준). 이 경우 EasyPost에 요청하지 않습니다. 비워 두면 기능이 꺼집니다.

Minimum subtotal: 장바구니 소계(배송 대상 상품, 할인 후, 세금 전)가 이 금액 이상일 때만 운송업체를 표시합니다. 비워 두면 항상 표시합니다.

Minimum weight: 장바구니가 이보다 가벼우면 운송업체를 숨깁니다. 단위는 쇼핑몰의 무게 단위입니다(필드 라벨에 표시됩니다). 0은 제한 없음을 뜻합니다.

Maximum weight: 장바구니가 이보다 무거우면 운송업체를 숨깁니다. 단위는 쇼핑몰의 무게 단위입니다. 0은 제한 없음을 뜻합니다.

배송 구역 없이 제공하기

보통 운송업체는 Shipping > Carriers에서 할당된 구역에 제공됩니다. 또는 구역과 무관하게 국가별로 제공할 수도 있습니다.

Ignore shipping zones: 아래에 지정한 국가에 대해, 해당 구역이 운송업체에 할당되어 있는지와 관계없이 운송업체를 제공합니다. 이 옵션을 켜고 저장하면 운송업체는 나중에 만든 구역을 포함한 모든 구역에 할당됩니다. 끄면 운송업체는 이전 구역을 되돌려 받습니다.

Countries: 이 모드에서 배송할 목적지 국가입니다. Ctrl+클릭으로 여러 개를 선택할 수 있습니다. 비워 두면 쇼핑몰의 활성 국가가 모두 사용됩니다. 이 필드는 Ignore shipping zones가 켜져 있을 때만 사용됩니다.

고급

Debug log: EasyPost 요청을 modules/vfd_easypost/logs/vfd_ep.log.php에 기록합니다. 이 파일은 웹에서 열 수 없으며 5 MB에 도달하면 교체됩니다. API 오류는 이 옵션이 꺼져 있어도 항상 기록됩니다. API 키와 고객 주소는 절대 기록되지 않습니다.

Remove data on uninstall: 켜져 있으면 모듈을 제거할 때 설정, 테이블, 로그가 삭제됩니다. 모듈을 비활성화해도 설정은 삭제되지 않습니다.

Log: 설정 아래 패널에 로그의 최근 100줄이 표시됩니다. Clear log를 클릭하면 비워집니다.

체크아웃에서의 동작

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

그렇지 않으면 모듈은 출발지 주소, 배송 주소, 소포 정보를 EasyPost에 보내고, 모든 운송업체 계정의 요금을 받습니다. 허용된 요금 중 가장 저렴한 요금을 고르고, 이를 기본 통화로 환산한 뒤 고객의 장바구니 통화로 표시합니다. 우편번호가 필요한 국가의 경우, 배송 주소에 우편번호가 있을 때만 요청합니다. 고객이 주소를 입력하기 전에는 방문자의 국가만 알 수 있으므로, 우편번호가 필요한 국가는 주소를 입력할 때까지 대체 가격을 받습니다.

각 응답은 같은 주소와 같은 소포에 대해 1시간 동안 캐시됩니다. 사용 가능한 요금이 없는 주소는 10분 동안 기억됩니다. 시간 초과, 키 거부, 요청 제한, EasyPost 서버 오류가 발생하면 5분 동안 요청을 보내지 않습니다. API 시간 초과는 10초입니다. 이 모든 경우 고객에게 오류는 표시되지 않습니다. 대체 가격이 사용되거나, 대체 가격이 없으면 운송업체가 숨겨집니다. 이유는 로그에 기록됩니다.

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

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

주문

EasyPost 운송업체로 주문이 들어오면, 체크아웃에 표시된 요금이 주문과 함께 저장됩니다. 관리자 페이지의 주문 화면에는 EasyPost shipping 블록이 표시됩니다:

Carrier / service: 요금에 해당하는 EasyPost 운송업체와 서비스입니다(예: USPS Priority). 상품별 소포 모드에서는 사용된 모든 서비스가 나열됩니다.

Estimated delivery days: EasyPost가 반환한 배송일입니다(주문당 소포 한 개 모드에서, EasyPost가 값을 반환한 경우에만 표시됩니다).

Price source: Live EasyPost rate, Fallback price (no live rate) 또는 Free shipping threshold입니다.

Calculated price (excl. tax): 기본 통화로 된 가격입니다.

관리자 페이지에서 이후에 장바구니를 변경해도 이 값은 바뀌지 않습니다. 이 정보를 사용해 EasyPost 계정에서 라벨을 구매하십시오. 포기된 장바구니의 요금은 30일 후에 삭제됩니다.

라이선스 키

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

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

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

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

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

문제 해결

체크아웃에 EasyPost가 나타나지 않음: 라이선스가 활성 상태인지, Enable EasyPost shipping이 켜져 있는지 확인하십시오. Shipping > Carriers에서 운송업체가 활성화되어 있고 고객 국가의 구역과 고객 그룹을 포함하는지 확인하십시오(또는 Ignore shipping zones가 켜져 있고 국가가 선택되어 있는지 확인하십시오). 무게 제한과 Minimum subtotal도 확인하십시오. 실시간 요금이 없으면 운송업체에는 해당 국가 또는 Other countries에 대한 대체 가격이 필요합니다. 상품 페이지에서 상품을 특정 운송업체로만 제한했을 수도 있습니다.

실시간 요금이 나타나지 않음: 모듈 페이지 상단의 경고를 읽은 뒤 Debug log를 켜고, 체크아웃을 새로 고침한 다음 Log 패널을 확인하십시오. 흔한 원인: API 키 또는 출발지 우편번호가 없음, USD가 아닌 쇼핑몰에서 USD exchange rate가 없음, 배송 주소에 아직 우편번호가 없음, EasyPost 계정의 어떤 운송업체도 해당 주소를 담당하지 않음, 또는 Allowed carriers / services가 모든 요금을 걸러 냄.

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

몇 분 동안 요금 조회가 중단됨: 시간 초과, 키 거부, EasyPost 서버 오류 후 모듈은 5분 동안 요청을 중지하고 대체 가격을 사용합니다. API 키와 로그를 확인하십시오.

세금이 포함되어 있나요? EasyPost 요금에는 판매세가 포함되지 않습니다. 배송에 세금을 추가하려면 Tax에서 세금 규칙을 선택하십시오.

변경 후 요금이 오래된 것 같음: 모듈 페이지에서 Save를 클릭하십시오. 캐시된 EasyPost 요금이 지워집니다.

페이지에 모듈의 운송업체를 찾을 수 없다고 표시됨: Shipping > Carriers에서 운송업체가 삭제되었습니다. Modules > Module Manager에서 모듈을 초기화하면 다시 만들어집니다.

개발자용 훅: actionVfdEpShipmentRequest(요청 본문), actionVfdEpSelectedRate(선택된 요금), actionVfdEpApiUrl(API 기본 URL) 훅으로 모듈을 조정할 수 있습니다.

제거

Modules > Module Manager로 이동하여 VibeFox EasyPost 옆의 메뉴를 열고 Uninstall을 선택하십시오. 라이선스 키와 라이선스 상태는 항상 삭제됩니다. 운송업체는 체크아웃에서 제거됩니다(주문 이력은 유지됩니다). 캐시된 요금은 항상 삭제됩니다. Remove data on uninstall이 켜져 있으면 설정, 저장된 주문 요금, 로그도 삭제됩니다. 꺼져 있으면 설정과 주문의 EasyPost 데이터는 다시 설치할 수 있도록 유지됩니다. 모듈을 설치하거나 초기화하면 새 운송업체가 만들어집니다. 설정이 유지되었다면 이전 운송업체의 상태(활성 또는 비활성)를 이어받습니다.

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