VibeFox EasyPost for OpenCart — 도움말

요구 사항

OpenCart: 3.0.x(3.0.5.0에서 테스트됨) 또는 4.0.2 이상(4.1.0.3에서 테스트됨).

PHP: cURL을 포함한 8.0 이상.

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

상품: 상품에는 무게가 필요하며, 가능하면 치수도 있어야 합니다.

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

설치

다운로드는 두 OpenCart 버전용 패키지가 들어 있는 zip 파일 하나입니다. 컴퓨터에서 압축을 푸세요. 여기에는 README.txt, OpenCart 3 패키지 vfd_easypost-oc3-(version).ocmod.zip, OpenCart 4 패키지 vfd_easypost.ocmod.zip이 들어 있습니다. 사용 중인 OpenCart 버전의 패키지만 설치하세요. 라이선스 키는 두 버전에서 같습니다.

OpenCart 3

1. 관리자 화면에서 Extensions > Installer로 이동하고, Upload를 클릭한 뒤 vfd_easypost-oc3-(version).ocmod.zip 파일을 선택합니다. 이 확장 프로그램은 OCMOD 수정 사항을 추가하지 않으므로 Extensions > Modifications를 새로 고칠 필요가 없습니다. Installer 대신, 패키지의 upload 폴더 내용을 쇼핑몰의 루트 폴더에 복사할 수도 있습니다.

2. Extensions > Extensions로 이동하여 확장 프로그램 유형으로 Shipping을 선택합니다. VibeFox EasyPost를 찾아 Install(녹색 + 버튼)을 클릭합니다.

3. Edit(연필 버튼)를 클릭하여 설정 페이지를 엽니다.

4. Edit 페이지 상단의 라이선스 블록에 있는 License key에 VibeFox 라이선스 키를 붙여 넣고 Activate를 클릭하세요(라이선스 키 참조).

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

6. 기본 통화가 USD가 아니라면 USD exchange rate를 입력합니다. 필요하면 대체 요금을 입력합니다(구성 참조). Enable EasyPost shipping을 켜고 Save를 클릭합니다.

OpenCart 4

1. 관리자 화면에서 Extensions > Installer로 이동하고, Upload를 클릭한 뒤 vfd_easypost.ocmod.zip 파일을 선택합니다. 파일 이름을 바꾸지 마세요. OpenCart 4는 파일 이름에서 확장 프로그램 코드를 읽으므로, 이름을 바꾼 패키지는 작동하지 않습니다.

2. 같은 페이지의 설치된 확장 프로그램 목록에 패키지가 나타납니다. 그 옆의 Install(녹색 + 버튼)을 클릭하세요.

3. Extensions > Extensions로 이동하여 확장 프로그램 유형으로 Shipping을 선택합니다. VibeFox EasyPost를 찾아 Install(녹색 + 버튼)을 클릭한 다음 Edit(연필 버튼)를 클릭하세요.

4. 라이선스 키와 설정은 OpenCart 3의 4~6단계와 같이 입력하세요. 설정 페이지와 그 필드는 두 버전에서 같습니다.

설치 후에는 Enable EasyPost shipping을 켜고 저장할 때까지 이 방법이 꺼져 있습니다. 제거한 뒤 확장 프로그램을 다시 설치하면, 보관해 둔 설정이 다시 사용됩니다.

구성

모든 설정은 확장 프로그램 페이지에 있습니다: Extensions > Extensions > Shipping > VibeFox EasyPost > Edit. 섹션은 왼쪽에 나열됩니다. Save 버튼 하나로 페이지를 다시 불러오지 않고 전체 페이지를 저장합니다. 저장할 때마다 캐시된 EasyPost 요금도 지워집니다. 이 확장 프로그램에 대한 수정 권한이 있는 관리자 사용자만 설정을 저장하거나 로그를 비울 수 있습니다.

페이지 상단에서 확장 프로그램은 실시간 요금을 사용할 수 없을 때 경고를 보여 줍니다. API 키가 없는 경우(대체 요금 유무와 관계없이), 발송지 우편번호나 국가가 없는 경우, 또는 기본 통화가 USD가 아니고 환율이 없는 경우입니다. 테스트 API 키가 설정되어 있으면 안내가 표시되고, 쇼핑몰의 무게 또는 길이 단위(System > Settings > Option)가 확장 프로그램이 인식하는 단위(kg, g, lb, oz; cm, mm, m, in)가 아니면 경고가 표시됩니다.

저장할 때, 64자를 넘는 이름, 정수가 아닌 Sort order, 알 수 없는 세금 클래스 또는 지오존이 있으면 저장이 중단되며 아무것도 저장되지 않습니다. 숫자가 아니거나 음수인 값은 저장되지 않습니다. 경고가 해당 필드를 알려 주고 이전 값이 유지되며, 나머지 설정은 저장됩니다. USD exchange rate가 0이거나 Minimum weight가 Maximum weight보다 큰 경우에도 같은 일이 일어납니다.

일반

Enable EasyPost shipping: 체크아웃에서 이 방법을 제공합니다. Extensions > Extensions > Shipping에서 확장 프로그램의 상태입니다. 기본값: 끔.

Name: 체크아웃에서 고객에게 보이는 배송 방법 이름. 최대 64자. 기본값: EasyPost Shipping. 이름이 비어 있으면 기본 이름이 사용됩니다. < > ; = # { } 문자가 포함된 이름은 경고와 함께 기본 이름으로 대체됩니다.

Sort order: 체크아웃의 배송 방법 중에서 이 방법의 위치. 정수입니다.

EasyPost 계정

API key: EasyPost Dashboard > Account Settings > API Keys에 있는 EasyPost API 키. 운영 키(EZAK로 시작)는 실제 요금을 반환합니다. 테스트 키(EZTK로 시작)는 EasyPost 테스트 요금을 반환하므로 테스트에만 사용하세요. 저장한 뒤에는 이 필드가 비어 있고, 저장된 키를 마스킹하여 보여 줍니다. 예를 들어 Saved key: EZAK******abcd. Leave the field empty to keep it. 변경하려는 경우에만 새 값을 입력하세요. 키가 없으면 대체 요금만 사용됩니다.

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

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

발송지

소포를 보내는 주소입니다. Country가 쇼핑몰의 국가이면, 비어 있는 Sender name / company는 쇼핑몰 이름에서, 비어 있는 State는 쇼핑몰의 지역(System > Settings)에서 가져옵니다. OpenCart에는 쇼핑몰 우편번호가 없으므로 우편번호는 여기에 입력해야 합니다.

Sender name / company: 보내는 사람 이름이나 회사명. 비어 있으면 쇼핑몰 이름을 사용합니다(같은 국가일 때만).

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

City: 발송지 주소의 도시.

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

ZIP code: 발송지 우편번호(예: 94105). 실시간 요금에 필요합니다.

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

요금

Parcels: 장바구니를 EasyPost에 어떻게 보낼지 정합니다.

무게는 쇼핑몰의 무게 단위에서 온스(최소 1oz)로, 치수는 쇼핑몰의 길이 단위에서 인치로 변환됩니다. 상품 중 치수가 없는 것이 하나라도 있으면 소포는 무게로만 요금이 계산됩니다.

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

Tax class: 배송에 적용되는 세금 클래스, 또는 No tax. EasyPost 요금에는 판매세가 포함되어 있지 않습니다.

대체 요금

실시간 요금이 없을 때 사용됩니다. API 키가 없거나, EasyPost에 연결할 수 없거나, 키가 거부되었거나, 어떤 운송사도 해당 주소의 요금을 갖고 있지 않을 때입니다. 요금은 쇼핑몰의 기본 통화이며 세금 제외 금액입니다. 이런 경우 방법을 숨기려면 두 필드를 모두 비워 두세요.

Country prices: 국가당 한 줄: 두 글자 국가 코드, 콜론, 요금. 예: US:9.99. 다른 형식의 줄은 무시되며, 저장할 때 경고에 나열됩니다.

Other countries: 위 목록에 없는 국가의 요금. 비워 두면 그 국가에서는 방법을 숨깁니다.

조건

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

Minimum subtotal: 장바구니 소계(배송 대상 상품, 쿠폰 할인 후, 세금 전)가 이 금액 이상일 때만 이 방법을 표시합니다. 항상 표시하려면 비워 두세요.

Minimum weight: 장바구니가 이보다 가벼우면 이 방법을 숨깁니다. 단위는 쇼핑몰의 무게 단위이며 필드 라벨에 표시됩니다. 0은 제한이 없음(기본값)을 뜻합니다.

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

이용 가능 여부

보통은 지오존이 이 방법을 제공하는 위치를 결정합니다. 대안으로, 지오존과 관계없이 국가별로 제공할 수도 있습니다.

Geo zone: 이 지오존 안의 주소에만 이 방법을 제공합니다. All zones(기본값)는 제한이 없음을 의미합니다. 지오존은 System > Localisation > Geo Zones에서 관리합니다. Ignore shipping zones와 함께 사용하지 않습니다.

Ignore shipping zones: 지오존 포함 여부와 관계없이, 아래의 국가에서 이 방법을 제공합니다.

Countries: 이 모드에서 배송 대상이 되는 국가. 쇼핑몰에서 활성화된 모든 국가를 사용하려면 비워 두세요. 이 필드는 Ignore shipping zones가 켜져 있을 때만 사용됩니다.

고급

Debug log: EasyPost 요청을 storage/logs/vfd_ep.log.php(OpenCart 4에서는 system/storage/logs/vfd_ep.log.php)에 기록합니다. 이 파일은 웹에서 읽을 수 없습니다. 5MB에 도달하면 vfd_ep.old.log.php로 옮겨지고 새 로그가 시작됩니다. 이 옵션이 꺼져 있어도 API 오류와 경고는 항상 기록됩니다. API 키와 고객 주소는 절대 기록되지 않습니다.

Log: 로그의 크기와 최신 100줄을 보여 줍니다. 비우려면 Clear log를 클릭하세요.

Remove data on uninstall: 켜면, 확장 프로그램을 제거할 때 설정과 로그가 삭제됩니다. 주문된 주문의 EasyPost 데이터는 보존됩니다. 방법을 끄는 것은 설정을 절대 삭제하지 않습니다.

가져오기 / 내보내기

Export: Download JSON을 클릭하면 설정을 JSON 파일로 저장합니다. API 키는 내보내지지 않습니다.

Import: 이전에 내보낸 JSON을 붙여 넣고 Import를 클릭하면 설정을 복원합니다. 예를 들어 다른 쇼핑몰에서 사용할 수 있습니다. 값은 일반 저장과 같은 방식으로 확인됩니다. 저장된 API 키는 변경되지 않습니다.

체크아웃에서의 작동 방식

OpenCart가 배송 방법을 표시할 때, 확장 프로그램에 EasyPost의 요금을 요청합니다. Geo zone이 설정되어 있고(그리고 Ignore shipping zones가 꺼져 있고) 주소가 그 지역 밖이면, 이 방법은 제공되지 않습니다. Requires Shipping이 Yes로 설정된 상품만 계산에 포함됩니다. 다른 상품은 무게를 더하지 않으며 소계에도 포함되지 않습니다. 확장 프로그램은 먼저 조건을 확인합니다. 목적지 국가(Ignore shipping zones 사용 시), 장바구니 무게, 최소 소계입니다. 소계는 쿠폰 할인 후, 세금 전의 배송 대상 상품 가격입니다. 기프트 카드, 적립 포인트, 스토어 크레딧은 고려하지 않습니다. 무료 배송이 적용되면 요금은 0이 되고, EasyPost로 요청이 전송되지 않습니다.

그 외의 경우, 확장 프로그램은 EasyPost에 발송지 주소, 배송지 주소, 소포 정보를 보내고, 귀하의 모든 운송사 계정에서 요금을 받습니다. 허용된 요금 중 가장 저렴한 요금을 고르고, 쇼핑몰 기본 통화로 변환한 뒤, 선택한 Tax class의 세금을 포함하여 고객의 통화로 보여 줍니다. System > Localisation > Countries에서 Postcode Required로 표시된 국가의 경우, 배송지 주소에 우편번호가 있을 때만 요청이 이루어집니다. OpenCart의 기본 데이터에서는 미국에 대해 이 표시가 꺼져 있으므로, 우편번호가 없는 미국 주소도 전송됩니다. 이때 EasyPost는 오류를 반환하고, 대체 요금이 사용됩니다.

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

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

OpenCart 4에서는 고객이 체크아웃 페이지의 배송 방법 블록에서 Choose를 클릭하고, Shipping method options 창에서 EasyPost 방법을 선택합니다. 이 방법은 OpenCart 3과 같은 방식으로 작동합니다.

주문

EasyPost 방법으로 주문이 이루어지면, 체크아웃에서 보여 준 요금이 주문과 함께 저장됩니다. 관리자 주문 페이지(Sales > Orders)는 내역 위에 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 계정에서 라벨을 구매하세요. OpenCart는 체크아웃이 확인 단계에 도달할 때마다 주문 기록을 만듭니다. 이런 미완료 주문에 저장된 요금은 30일 후에 삭제됩니다.

OpenCart 4에서는 체크아웃이 주문 하나를 유지하고, 고객이 다시 확인할 때마다 그 주문을 업데이트합니다. 저장된 요금도 함께 업데이트됩니다. 고객이 체크아웃에서 본 요금입니다. 고객이 다른 배송 방법으로 바꾸면, 그 주문에 대해서는 패널이 더 이상 표시되지 않습니다.

라이선스 키

이 확장 프로그램은 vibefox.net에서 받은 VibeFox 라이선스 키로 작동합니다. License — VibeFox EasyPost 라이선스 블록은 Extensions > Extensions > Shipping > VibeFox EasyPost > Edit 페이지에서 설정 위에 있는 첫 번째 블록입니다. License key에 키를 붙여 넣고 Activate를 클릭하세요. 그러면 블록에 키가 마스킹되어 표시되고, 상태(예: 라이선스 활성 기한과 도메인)와 함께 Check now(상태 다시 확인), Change key(다른 키 입력), Remove key(이 쇼핑몰에서 키 제거) 버튼이 나타납니다. 그 아래에는 Product: opencart-shipping-easypost 줄과, vibefox.net 계정을 여는 Manage licenses and domains in your account 링크가 있습니다. 이 확장 프로그램에 대해 Modify 권한이 있는 관리자 사용자만 키를 변경할 수 있습니다. 블록의 문구는 관리자 화면 언어를 따릅니다(영어와 러시아어 포함).

키가 허용되지 않으면 블록에 이유가 표시됩니다. 예를 들어 Key not found, This key belongs to another product, Domain limit reached 또는 날짜가 붙은 License expired on이 나타납니다. 쇼핑몰 주소를 변경한 뒤, 또는 계정에서 도메인 슬롯을 비운 뒤에는 Check now를 클릭하세요. 라이선스 서버에 연결할 수 없으면 확장 프로그램은 마지막으로 확인된 상태를 유지하며 계속 작동합니다.

키 하나는 도메인 하나에서 사용할 수 있습니다. 도메인은 OpenCart 설정의 쇼핑몰 주소입니다. 쇼핑몰에서 키를 제거해도 도메인 슬롯은 비워지지 않습니다. vibefox.net 계정에서 슬롯을 비우세요.

활성 키가 없으면 EasyPost 배송 방법은 체크아웃에서 고객에게 표시되지 않으며, 요금도 계산되지 않습니다. 같은 브라우저에서 관리자 화면에 로그인한 관리자 사용자에게는 쇼핑몰에서 이 방법이 (unlicensed — visible to admins only) 표시와 함께 계속 보입니다. 따라서 키를 구매하기 전에 확장 프로그램을 설정하고 테스트할 수 있습니다. OpenCart 4에서는 이 미리보기를 사용할 수 없습니다. 쇼핑몰은 관리자 로그인을 볼 수 없으므로, 활성 키가 없으면 모든 사용자에게 이 방법이 숨겨집니다. Edit 페이지를 한 번 열면, 관리자 Dashboard에 알림이 나타납니다. ×를 눌러 닫으면 7일 동안 숨겨집니다. 기존 주문은 영향을 받지 않습니다.

라이선스가 만료되어도 확장 프로그램은 계속 작동하지만, 업데이트와 지원에는 갱신이 필요합니다. 관리자 Dashboard 또는 Edit 페이지를 열면 상태가 자동으로 다시 확인됩니다. 키를 입력한 뒤 처음 14일 동안은 하루에 한 번, 그 후에는 일주일에 한 번입니다. cron 작업은 필요하지 않습니다. 확장 프로그램을 제거하면 라이선스 키와 라이선스 상태는 항상 삭제됩니다.

문제 해결

체크아웃에 EasyPost가 나타나지 않음: 라이선스가 활성 상태인지, Enable EasyPost shipping이 켜져 있는지 확인하세요. Geo zone(또는 Ignore shipping zones와 Countries), 무게 제한, Minimum subtotal을 확인하세요. 실시간 요금이 없으면 이 방법은 해당 국가 또는 Other countries에 대한 대체 요금이 필요합니다. 상품의 Requires Shipping이 Yes로 설정되어 있는지도 확인하세요.

실시간 요금이 나타나지 않음: 확장 프로그램 페이지 상단의 경고를 읽은 뒤, Debug log를 켜고, 체크아웃을 다시 불러와 Log 필드를 확인하세요. 흔한 원인: API 키나 발송지 우편번호가 없음, USD가 아닌 쇼핑몰에 USD exchange rate가 없음, 배송지 주소에 아직 우편번호가 없음, EasyPost 계정의 어떤 운송사도 그 주소를 담당하지 않음, 또는 Allowed carriers / services가 모든 요금을 걸러냄.

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

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

세금이 포함되어 있나요? EasyPost 요금에는 판매세가 포함되어 있지 않습니다. 배송비에 세금을 추가하려면 Tax class에서 세금 클래스를 선택하세요.

변경 후 요금이 오래된 것처럼 보임: 확장 프로그램 페이지에서 Save를 클릭하세요. 이렇게 하면 캐시된 EasyPost 요금이 지워집니다.

페이지에 "Warning: You do not have permission to modify VibeFox EasyPost!"가 표시됨: 관리자 사용자 그룹이 설정을 보기만 할 수 있는 것일 수 있습니다. System > Users > User Groups에서 그 그룹에 extension/shipping/vfd_easypost(OpenCart 3) 또는 extension/vfd_easypost/shipping/vfd_easypost(OpenCart 4)에 대한 수정 권한을 부여하세요.

개발자용: 다른 확장 프로그램은 OpenCart 이벤트 vfd_easypost/shipment_request, vfd_easypost/selected_rate, vfd_easypost/api_url을 통해 요청 본문, 선택된 요금, API 기본 URL을 조정할 수 있습니다.

제거

Extensions > Extensions로 이동하고, 유형으로 Shipping을 선택한 뒤, VibeFox EasyPost 옆의 Uninstall(빨간색 − 버튼)을 클릭하세요. 이 확장 프로그램의 라이선스 키와 라이선스 상태는 항상 제거됩니다. OpenCart는 항상 Enable EasyPost shipping, Sort order, Tax class, Geo zone을 초기화합니다. 확장 프로그램은 항상 자신의 이벤트와 캐시된 요금을 제거합니다. Remove data on uninstall이 켜져 있으면 나머지 설정과 로그도 삭제됩니다. 꺼져 있으면 설정이 보존되며, 확장 프로그램을 다시 설치할 때 다시 사용됩니다. 주문된 주문의 EasyPost 데이터는 절대 삭제되지 않으며, 기존 주문은 배송 방법과 비용을 그대로 유지합니다.

OpenCart 4에서 확장 프로그램 파일까지 제거하려면, 제거한 뒤 Extensions > Installer로 이동하여 설치된 확장 프로그램 목록에서 VibeFox EasyPost 옆의 Uninstall(주황색 − 버튼)을 클릭한 다음, 업로드한 패키지를 삭제하도록 Delete(빨간색 휴지통 버튼)를 클릭하세요.

EasyPost는 각 소유자의 상표입니다. 이 확장 프로그램은 EasyPost와 제휴하지 않으며 EasyPost의 승인을 받지 않았습니다.