VibeFox Correos CityPaq for PrestaShop — 도움말

요구 사항

PrestaShop: 8.0 ~ 9.x.

PHP: 8.0 이상. 이전 PHP 버전에서는 모듈 설치가 거부됩니다.

스페인 배송: CityPaq 사물함은 스페인에만 있으므로, 운송업체는 스페인의 배송 주소에만 제공됩니다.

Correos API 자격 증명(실시간 사물함 목록에만 필요): Correos CityPaq 목록은 Correos "terminals" API에서 활성 사물함을 읽어옵니다. Correos 개발자 포털에서 "terminals" API를 열고, 애플리케이션에 대해 Request access를 사용하세요. Correos는 법인 고객의 요청을 승인하고 client ID와 client secret을 보내 줍니다. 이 값들은 포털의 My applications에도 표시됩니다. 고객이 사물함을 직접 입력하거나 쇼핑몰의 목록에서 선택한다면 API 자격 증명은 필요하지 않습니다.

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

설치

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

2. 업로드가 끝나면 Configure를 클릭하세요. 나중에 모듈 목록에서 VibeFox Correos CityPaq를 찾아 Configure를 클릭해도 됩니다.

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

4. 요금표를 작성하고, 고객이 사물함을 선택하는 방식을 고른 다음(설정 항목 참조) Save를 클릭하세요.

설치 시 모듈은 배송 시간 문구가 Delivery to a Correos CityPaq parcel locker인 Correos CityPaq 운송업체를 만듭니다. 운송업체는 모든 고객 그룹과 스페인 지역에 할당됩니다. 지역, 고객 그룹, 배송 시간, 로고, 크기 제한은 Shipping > Carriers에서 변경할 수 있습니다. 그곳에서는 요금을 설정하지 마세요. 요금은 항상 모듈에서 가져옵니다.

설정

모든 설정은 모듈 페이지에 있습니다: Modules > Module Manager > VibeFox Correos CityPaq > Configure. 각 섹션에는 자체 Save 버튼이 있으며, 이 버튼은 페이지 전체를 저장합니다. 요금과 금액은 소수점 쉼표 또는 소수점 마침표를 허용합니다.

설정 위의 경고는 다음과 같은 경우를 알려 줍니다: 운송업체를 찾을 수 없을 때, 요금표에 스페인 행도 기본 행도 없을 때, 선택한 사물함 선택 방식이 작동할 수 없을 때(목록에 사물함이 없거나 API 자격 증명이 없음), 마지막 Correos API 오류가 무엇인지, 그리고 모듈이 쇼핑몰의 무게 단위를 알지 못할 때(이 경우 상품 무게는 kg로 읽힙니다. International > Localization에서 kg, g, lb 또는 oz를 설정하세요). 이름이 비어 있거나, 잘못되었거나, 64자를 넘는 경우, 무게나 금액이 0 이상의 올바른 숫자가 아닌 경우, 또는 Min weight (kg)가 Max weight (kg)보다 큰 경우에는 페이지에 오류가 표시되며 아무것도 저장되지 않습니다. 요금표의 잘못된 요금과 My lockers의 잘못되었거나 중복된 줄은 경고로 표시되며, 나머지는 저장됩니다.

일반

CityPaq 사물함은 스페인에만 있으므로, 운송업체는 다른 국가에는 절대 표시되지 않습니다.

Enable/Disable: Correos CityPaq 배송을 켜거나 끕니다. Shipping > Carriers의 운송업체 상태와 같은 스위치입니다.

Name: 체크아웃에서 고객에게 표시되는 배송 방법의 이름입니다. 운송업체 이름이기도 합니다. 기본값: Correos CityPaq. 필수 항목이며 최대 64자입니다.

Tax: 운송업체의 세금 규칙입니다. PrestaShop은 요금표의 요금에 이 세금을 추가합니다. No tax는 요금이 최종 금액임을 뜻합니다.

요금(섹션 제목에는 쇼핑몰의 기본 통화가 표시됩니다)

Correos가 CityPaq용 요금 API를 공개하지 않으므로, 요금은 이 표에서 가져옵니다. Correos 계약 요금을 세금을 제외하고 쇼핑몰 기본 통화로 입력하세요.

Price table: Spain (ES) 행 및/또는 기본 행 * Default. 각 행에는 기본 Price와, 포장 크기 XS(1 kg 이하), S(2 kg 이하), M(3 kg 이하), L(5 kg 이하), XL(5 kg 초과)에 대한 선택적 요금이 있습니다. 크기 요금이 0이거나 비어 있으면 기본 요금을 사용합니다. 행을 추가하려면 + Add row를, 행을 삭제하려면 휴지통 아이콘을 클릭하세요. 일치하는 행이 없으면 운송업체는 숨겨집니다. 같은 국가가 두 번 나타나면 첫 번째 행만 사용됩니다.

Calculation type: 포장 크기를 결정하는 방식입니다.

Per order (size by the total cart weight): 장바구니 전체에 대해 하나의 요금을 총 무게에 따라 선택합니다. 기본값입니다.

Per item (size by each item weight, multiplied by quantity): 각 상품은 자신의 크기에 해당하는 요금을 받고, 그 요금에 수량을 곱한 뒤 모두 더합니다.

상품 무게는 쇼핑몰의 무게 단위(예: kg, g, lb 또는 oz)에서 kg으로 변환됩니다.

조건

Min weight (kg): 장바구니가 이보다 가벼우면 운송업체를 숨깁니다. 0은 제한 없음을 뜻합니다.

Max weight (kg): 장바구니가 이보다 무거우면 운송업체를 숨깁니다. 기본값: 30. CityPaq는 최대 30 kg 소포를 받기 때문입니다. 0은 제한 없음을 뜻합니다.

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

무료 배송

Free shipping: 아래 금액부터 CityPaq 배송을 무료로 제공합니다.

Free shipping from: 이 운송업체의 요금이 0이 되는 장바구니 소계(할인 후, 세금 전)입니다. Free shipping이 켜져 있을 때만 사용됩니다.

CityPaq 사물함 선택

이 섹션에는 Correos CityPaq 공식 찾기 페이지로 가는 링크가 있습니다.

Locker selection: 고객이 주문 전에 사물함을 선택하는 방식입니다. 기본값: 고객이 사물함을 입력합니다.

Customer chooses from the Correos CityPaq list (Correos API, credentials below): 고객은 배송 주소의 우편번호에 있는 활성 CityPaq 사물함을 보고, 다른 5자리 우편번호를 검색할 수 있습니다. 우편번호에 사물함이 없으면 같은 지역의 사물함을, 그다음 같은 도(道)의 사물함을 가까운 우편번호순으로 나열합니다(최대 50개). 각 사물함에는 이름, 주소, 우편번호, 도시, 영업시간이 표시됩니다. 목록을 불러올 수 없거나 아무것도 찾지 못하면 고객이 대신 사물함을 입력합니다.

Customer enters the locker (code or address from the Correos finder): 사물함 코드(예: S0000213D) 또는 주소를 입력하는 필수 항목입니다. 3자 이상 120자 이하이며, Correos CityPaq 찾기 페이지로 가는 링크가 있습니다.

Customer chooses from my list of lockers (below): My lockers의 사물함에서 선택하는 필수 드롭다운입니다. 고객의 우편번호와 가까운 사물함이 먼저 나열됩니다.

Do not ask for a locker: 체크아웃에서 사물함에 대해 묻지 않습니다.

API 자격 증명 없이 Correos 목록을 선택했거나, My lockers가 비어 있는데 쇼핑몰의 목록을 선택한 경우, 고객에게는 사물함을 입력하라는 안내가 나타납니다.

My lockers: Locker selection이 쇼핑몰의 목록으로 설정되어 있을 때 사용됩니다. 한 줄에 사물함 하나를 입력합니다: CODE | Name | Address | Postal code | City. 코드와 이름은 필수입니다. 같은 코드가 두 번 나오면 첫 번째 줄만 사용됩니다.

Correos CityPaq 목록(API)(Correos CityPaq 목록을 사용할 때만 적용됩니다)

이 섹션에는 Correos 개발자 포털의 "terminals" API 페이지로 가는 링크가 있습니다. 사물함 목록만 읽어옵니다. 요금은 항상 요금표에서 가져옵니다.

API client ID: Correos 개발자 포털에 있는 애플리케이션의 client_id입니다.

API client secret: Correos 개발자 포털에 있는 애플리케이션의 client_secret입니다.

저장한 후에는 두 입력란이 비어 있고 Saved - leave empty to keep it이 표시됩니다. 값을 바꾸고 싶을 때만 새 값을 입력하세요. 저장된 client ID와 client secret을 삭제하려면 Remove the saved client ID and client secret을 선택하고 Save를 클릭하세요. 아무것도 저장되어 있지 않으면 이 섹션에 No credentials saved가 표시됩니다. 자격 증명이나 사물함 선택 방식을 변경하면 캐시된 사물함 목록이 지워집니다.

배송 지역 없이 제공하기

Ignore shipping zones: 주소의 지역이 운송업체에 연결되어 있지 않더라도 스페인 내 모든 주소에 CityPaq를 제공합니다. 켜면 운송업체가 나중에 만든 지역을 포함한 모든 활성 지역에 연결됩니다. 다시 끄면 운송업체는 이전에 가지고 있던 지역을 되돌려 받습니다. 꺼져 있음(권장)은 Shipping > Carriers에서 설정한 지역을 사용한다는 뜻입니다.

고급

Debug log: 모듈 폴더의 logs/vfd_cpq_debug.log.php에 디버그 줄을 기록합니다. 이 파일은 웹에서 열 수 없습니다. 이 옵션이 꺼져 있어도 Correos API 오류는 항상 기록됩니다. 자격 증명과 개인정보는 로그에 기록되지 않습니다.

Log: 로그의 크기와 최근 항목을 보여 줍니다. Clear log를 클릭하면 로그를 비울 수 있습니다.

Remove data on uninstall: 켜면 모듈을 제거할 때 설정, 운송업체, 캐시된 목록, 로그가 삭제됩니다. 주문에 저장된 사물함은 유지됩니다. 끄면 재설치를 위해 모든 항목이 유지됩니다.

체크아웃에서 작동하는 방식

배송 단계에서 PrestaShop은 모듈에 CityPaq 요금을 요청합니다. 실물 상품만 계산에 포함됩니다. 가상 상품은 무게를 더하지 않으며 주문 금액에도 포함되지 않습니다. 모듈은 배송 주소가 스페인인지, 장바구니 무게와 최소 주문 금액을 확인하고, 스페인의 요금 행(또는 * 행)과 포장 크기를 찾아 요금을 반환합니다. 무료 배송이 적용되면 요금은 0입니다. 요금은 쇼핑몰의 기본 통화로 계산된 뒤 고객의 장바구니 통화로 표시됩니다. 세금은 운송업체의 세금 규칙에 따라 추가됩니다.

고객이 CityPaq를 선택하면 운송업체 아래에 CityPaq locker 상자가 나타납니다. 선택 내용은 고객이 선택하는 즉시 장바구니에 저장됩니다. 허용되지 않는 사물함은 메시지와 함께 거부되며, 이전 선택은 그대로 유지됩니다. Correos 목록을 사용하는 경우, 사물함 코드는 Correos가 검색한 우편번호에 대해 제공한 경우에만 허용되며, 이름과 주소는 Correos에서 가져옵니다. 고객은 장바구니당 최대 30개의 서로 다른 우편번호를 검색할 수 있습니다. 그 이후에는 Too many searches. Please enter the CityPaq locker you found on the Correos map.가 표시됩니다.

배송 단계의 Continue 버튼은 유효한 사물함이 없으면 진행되지 않습니다. 이 확인은 서버에서도 이루어집니다. 고객에게는 예를 들어 Please choose the CityPaq locker where you want to collect your parcel.이 표시됩니다. 주문이 완료되면 장바구니의 사물함이 주문에 저장됩니다.

Correos 목록은 배송 단계를 방문한 모든 사람에게 요청하는 것이 아니라, 고객이 CityPaq를 선택했을 때만 요청합니다. 목록은 우편번호별로 12시간 동안 캐시됩니다. 실패한 요청은 10분 동안 캐시되므로, 체크아웃이 새로 고침할 때마다 Correos를 기다리지 않습니다. API 제한 시간은 12초입니다. 고객은 기술적인 오류를 보지 않으며, 짧은 메시지와 직접 입력하는 칸만 보게 됩니다. 사물함 상자는 Classic 및 Hummingbird 테마에서 작동합니다.

모듈은 Correos에서 실시간 요금을 가져오지 않으며, 지도를 표시하지 않고, 배송을 미리 등록하거나, 송장을 인쇄하거나, 집화를 요청하거나, 택배를 추적하지 않습니다. 주문에 저장된 사물함을 사용하여 Correos 계정에서 배송을 생성하세요.

수령 지점

선택한 사물함은 주문에 저장됩니다. 고객은 주문 확인 페이지와 고객 계정의 주문 상세 페이지에서 CityPaq locker:로 확인할 수 있습니다. 주문 확인 이메일과 Mail alerts 모듈의 신규 주문 이메일에는 운송업체 행에 사물함이 추가됩니다. 예: Correos CityPaq - CityPaq locker: ....

백오피스의 주문 페이지에서 CityPaq locker 블록은 사물함을 보여 주며, 목록에서 선택한 경우 Locker code:도 함께 표시합니다. 변경하려면 Change CityPaq locker 입력란을 사용하고 Save를 클릭하세요. 쇼핑몰의 목록을 사용한다면 드롭다운에서 다른 사물함을 고르고, Correos 목록을 사용한다면 사물함 코드(Correos에서 조회됩니다) 또는 주소를 입력하고, 그 밖의 경우에는 새 코드나 주소를 입력하세요. 현재 사물함을 유지하려면 입력란을 비워 두세요. 변경할 때마다 주문에 비공개 주문 메시지가 추가됩니다: CityPaq 사물함이 변경됨: .... 사물함을 변경하려면 주문을 편집할 수 있는 권한이 필요합니다. Modules 페이지에 접근할 권한은 필요하지 않습니다.

라이선스 키

본 모듈은 vibefox.net에서 받은 VibeFox 라이선스 키로 작동합니다. License — VibeFox Correos CityPaq 라이선스 블록은 Modules > Module Manager > VibeFox Correos CityPaq > Configure 페이지에서 설정 위에 있는 첫 번째 블록입니다. 키를 License key에 입력하고 Activate를 클릭하세요. 그러면 블록에 마스킹된 키, 상태(예: 라이선스가 유효한 날짜와 도메인), 그리고 상태를 다시 확인하는 Check now, 다른 키를 입력하는 Change key, 이 쇼핑몰에서 키를 제거하는 Remove key 버튼이 표시됩니다. 그 아래에는 Product: presta-shipping-correos-citypaq 줄과, 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 계정에서 슬롯을 해제하세요.

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

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

문제 해결

Correos CityPaq가 체크아웃에 나타나지 않습니다: 라이선스가 활성 상태인지, Enable/Disable이 켜져 있는지, 배송 주소가 스페인인지 확인하세요. Shipping > Carriers에서 운송업체가 스페인 지역과 고객의 그룹을 포함하는지 확인하세요(또는 Ignore shipping zones을 켜세요). 요금표에 스페인 행이나 * 행이 있는지, 장바구니가 무게 제한과 Minimum order amount 범위 안에 있는지 확인하세요. 또한 상품 페이지에서 상품이 특정 운송업체로 제한되어 있을 수도 있습니다.

Correos 목록을 선택했는데도 고객이 사물함을 직접 입력해야 합니다: API client ID와 API client secret이 저장되어 있는지 확인하고, 설정 위의 경고를 살펴보세요. 경고에는 마지막 Correos API 오류가 표시됩니다. HTTP 401/403은 Correos가 자격 증명을 거부했다는 뜻입니다. 자격 증명을 확인하고, 애플리케이션이 "terminals" API에 접근할 수 있는지 확인하세요. 오류가 발생하면 다음 시도는 10분 후에 이루어집니다.

우편번호에 사물함이 없습니다: Correos가 해당 우편번호, 그 지역, 또는 그 도에서 활성 사물함을 찾지 못했습니다. 고객은 다른 우편번호를 검색하거나, Correos CityPaq 찾기 페이지에서 확인한 사물함을 입력할 수 있습니다.

내 사물함 드롭다운이 나타나지 않습니다: My lockers가 비어 있거나 그 줄이 잘못되었습니다. 각 줄에는 최소한 CODE | Name이 있어야 합니다.

고객이 사물함 코드를 찾는 곳: 사물함 입력란 아래에 연결된 Correos CityPaq 찾기 페이지입니다.

페이지에 운송업체를 찾을 수 없다거나 운송업체를 업데이트할 수 없다고 나옵니다: Shipping > Carriers에서 운송업체가 삭제되었습니다. Modules > Module Manager에서 모듈을 재설정하면 다시 만들어집니다. 재설정은 설정과 운송업체 상태를 유지합니다.

개발자 참고: 장바구니와 주문의 사물함은 vfd_cpq_locker 테이블(데이터베이스 접두사 포함)에 저장됩니다. 모듈은 Correos의 실서비스 "terminals" API를 사용합니다.

제거

Modules > Module Manager로 이동하여 VibeFox Correos CityPaq 옆의 메뉴를 열고 Uninstall을 선택하세요. 라이선스 키, 라이선스 상태, 캐시된 Correos 사물함 목록과 마지막 API 오류는 항상 삭제됩니다. Remove data on uninstall이 켜져 있으면 운송업체가 삭제되고(주문은 기록을 유지합니다), 설정, 로그, 주문이 없는 장바구니의 사물함도 삭제됩니다. 꺼져 있으면 운송업체는 비활성화되기만 하고 모든 설정은 유지됩니다. 모듈을 다시 설치하면 운송업체는 이전 상태로 복원됩니다. 주문에 저장된 사물함은 절대 삭제되지 않습니다.

Correos와 CityPaq는 각 소유자의 상표입니다. 본 모듈은 Correos와 제휴하거나 Correos의 승인을 받지 않았습니다.