VibeFox Jadlog for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块拒绝在更早的 PHP 版本上安装。
Jadlog 合同（用于实时运费和取件点）：实时运费和取件点列表来自 Jadlog Embarcador API。合同签署后，您的 Jadlog 特许经销商会提供访问权限。您需要 Embarcador API 令牌、合同中登记的发货人 CNPJ（或 CPF）、经常账户（conta corrente），以及如果有的话，合同编号。如果您只使用固定运费，则无需 Jadlog 合同。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或稍后在模块列表中找到 VibeFox Jadlog，然后点击 Configure。
3. 在 Configure 页面顶部的许可证区块中的 License key 字段输入您的 VibeFox 许可证密钥，然后点击 Activate（参见许可证密钥）。
4. 粘贴 API 令牌，填写 CNPJ、经常账户、合同编号和始发 CEP，选择 Jadlog 服务；如果店铺默认货币不是 BRL，请输入 BRL 汇率。如需要，可添加固定运费或备用运费（参见“配置”）。点击 Save。
5. 如需同时提供 Jadlog Pickup 取件点，请开启 Enable Jadlog Pickup，然后点击 Save。
安装时，模块会创建两个承运商：Jadlog（送货上门，默认开启，配送时效文字为 Jadlog delivery to your address）和 Jadlog Pickup（默认关闭，配送时效文字为 Pickup at a Jadlog Pickup point）。两者均关联巴西区域和所有顾客组。您可以在 Shipping > Carriers 中修改区域、顾客组、配送时效、Logo 和尺寸限制。请勿在那里设置运费：运费始终由模块提供。
配置
所有设置都在模块页面：Modules > Module Manager > VibeFox Jadlog > Configure。设置对两个 Jadlog 承运商同时生效。每个部分都有自己的 Save 按钮，会保存整个页面。每次保存还会清除缓存的 Jadlog 运费和取件点列表。
页面顶部，模块会对不完整的设置显示警告：没有 API 令牌（仅使用固定运费，无法列出取件点）；既没有 API 令牌也没有固定运费（从不显示该方式）；没有 CNPJ 或经常账户；没有始发 CEP；店铺不以 BRL 销售却没有 BRL 汇率；店铺的重量或尺寸单位是模块无法识别的（此时重量按 kg、尺寸按 cm 处理；请在 International > Localization 的 Local units 中设置单位）；或某个 Jadlog 承运商已被删除。保存时，会提示错误的值：不足 8 位的 CEP、不足 14 位的 CNPJ（CPF 为 11 位）、无效数字、最低重量高于最高重量（两个重量都保留已保存的值）、未知国家，或运费表中的无效运费。
General
Enable/Disable：开启或关闭 Jadlog 送货上门。这与 Shipping > Carriers 中承运商的状态是同一个开关。
Method title：购物车和结账时显示的送货上门承运商名称。默认：Jadlog。必填。
Tax status：None，或 Taxable 并选择您的一条税务规则。它会同时保存到两个 Jadlog 承运商。Jadlog 运费是最终的承运商运费。如果 PrestaShop 不应对这些运费加税，请选择 None。
Jadlog live prices
仅对巴西地址且 CEP 为完整 8 位数字时请求实时运费。
API token：Jadlog 提供的 Embarcador 令牌。您可以粘贴带或不带 “Bearer” 一词的令牌。如果只使用固定运费，请留空。保存后，该字段会保持为空，并显示 Saved - leave empty to keep it. 只有需要更改时才输入新值。
Remove the saved API token：勾选并点击 Save，即可删除已保存的令牌。
CNPJ：Jadlog 合同中登记的发货人 CNPJ（14 位）或 CPF（11 位）。允许使用点、斜杠和短横线。
Current account (conta corrente)：您的 Jadlog 经常账户号码。如果没有它且没有 CNPJ，Jadlog 无法报价，只会使用固定运费。
Contract number：如果您的特许经销商为您提供了合同编号，请在此填写。
Origin CEP：包裹寄出的邮政编码，8 位数字。保存格式为 00000-000。如果店铺地址在巴西，可留空，以使用 Shop Parameters > Contact > Stores 中的店铺邮政编码。
Jadlog service：您合同中用于送货上门的服务（modalidade）：.Package（3，默认）、.Com（9）、Expresso（0）、Rodoviário（4）、Econômico（5）、Doc（6）、Corporate（7）、Internacional（10）、Cargo（12）或 Emergencial（14）。Jadlog Pickup（40）是第二个承运商。
Insurance type：Normal (N)（默认），或按您 Jadlog 合同约定选择 Own insurance policy (A - apolice)。
Volumetric weight：Jadlog 按实际重量与体积重量中的较大者计费。
BRL exchange rate：Jadlog 以巴西雷亚尔报价。如果店铺默认货币是 BRL，则无需此字段。否则，请输入 1 BRL 等于您默认货币的金额，例如 0.16。Jadlog 运费将乘以该汇率，发送给 Jadlog 的申报订单金额会换算回 BRL。没有汇率时，不使用实时运费，只适用固定运费。小数点和逗号都可以作为小数分隔符。
Delivery time：在结账时，于 Jadlog 承运商下方以及每个取件点旁边显示 Jadlog 返回的配送时效，例如 "Delivery time: 3 business days"。默认开启。配送时效始终会随订单保存。
Jadlog Pickup
第二个承运商，使用 Jadlog Pickup 服务（40）。需要 API 令牌。没有取件点时，该承运商会被隐藏。
Enable Jadlog Pickup：开启或关闭 Jadlog Pickup 承运商。这与 Shipping > Carriers 中它的状态是同一个开关。安装后默认关闭。
Jadlog Pickup carrier name：此选项在结账时的名称。默认：Jadlog Pickup。必填。
Points to show：提供多少个取件点，范围 1 至 10。默认：5。
Fixed prices（在没有 API 令牌时、针对 Jadlog 不服务的国家，以及 Jadlog 未返回运费时使用）
Price per country：一个表格，包含 Country、Price、XS、S、M、L 和 XL 列，金额以店铺默认货币计。点击 + Add country 添加一行，点击垃圾桶图标删除一行。尺寸列根据购物车重量选择：XS 为 1 kg 以内，S 为 2 kg 以内，M 为 3 kg 以内，L 为 5 kg 以内，XL 为超过 5 kg。尺寸列为空时使用 Price。运费为 0 表示该国家免运费。所有其他国家请使用 * Default (other countries)。保存时，没有任何运费的行会被删除。
Fallback cost：在 Jadlog 和表格都未提供运费时使用。留空则在这种情况下隐藏该承运商。
Fixed price applies：Per order 按订单收取一次运费。Per item (price x quantity) 则按购物车中的商品数量乘以运费。这仅适用于固定运费和备用运费。Jadlog 运费已涵盖整个购物车。
Conditions
Minimum weight (kg)：购物车重量低于此值时隐藏承运商。0 表示不限制。
Maximum weight (kg)：购物车重量高于此值时隐藏承运商。默认：150。0 表示不限制。
Minimum order amount：仅当购物车小计（需要配送的商品，扣除折扣后、税前）达到此金额时才显示承运商。留空则始终显示。
Free shipping from：购物车小计（扣除折扣后、税前）达到此金额时免运费。留空则不提供免运费。
Availability without shipping zones
Ignore shipping zones：即使 Jadlog 承运商未关联其所在区域，也会为下方列出的国家提供 Jadlog。开启后，两个承运商都会关联到所有活跃区域，之后创建的区域也会自动关联。再次关闭时，承运商会恢复为之前拥有的区域。
Countries：此模式下的目的地国家，位于承运商自身区域之外。留空则允许所有国家。此字段仅在 Ignore shipping zones 开启时使用。
Advanced
Debug log：将每个 Jadlog 请求和响应记录到模块文件夹中的 logs/vfd_jdlg_debug.log.php。该文件无法通过网页打开。即使此选项关闭，API 错误也始终会被记录。令牌、CNPJ 和账户从不记录，顾客的 CEP 会被缩短。完成后请关闭日志。
Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。
Remove data on uninstall：开启后，卸载模块会删除所有 Jadlog 设置及其承运商。关闭时，卸载只会关闭承运商。缓存的运费始终会被删除。订单永远不会被修改。
结账时的工作方式
在配送步骤，PrestaShop 会向模块请求每个 Jadlog 承运商的运费。只计算实物商品：虚拟商品不增加重量，也不计入订单金额。模块首先检查条件：购物车重量和最低订单金额，以及在开启 Ignore shipping zones 时允许的国家。如果购物车小计达到 Free shipping from，则免运费，且不会向 Jadlog 发出运费请求。
对于巴西的配送地址且 CEP 为完整 8 位数字，模块会向 Jadlog 发送始发和目的地 CEP、重量、您的 CNPJ、经常账户、合同、服务、保险类型和申报订单金额。返回的运费会换算为店铺默认货币，并以顾客购物车的货币显示。没有重量的购物车按 0.1 kg 报价。如果没有实时运费（没有令牌、地址在巴西以外、CEP 不完整、没有 BRL 汇率、Jadlog 错误），模块会使用 Price per country 表格，然后是 Fallback cost。如果都无法提供运费，该购物车的承运商会被隐藏。
每个运费缓存 1 小时，因此同一购物车不会触发新的请求。失败的请求缓存 10 分钟。如果 Jadlog 无响应、返回服务器错误或拒绝令牌，则 10 分钟内不会再次调用 API。API 超时为 10 秒。顾客永远不会看到 API 错误。原因会写入日志。
如果您在订单产生后，在 Shipping > Carriers 中编辑承运商，PrestaShop 会将其保存为新的承运商版本。模块会自动跟随新版本。
模块仅计算运费并列出取件点。它不会创建 Jadlog 运单、打印面单、预约上门取件、取消运单或追踪包裹。它不显示取件点地图，也不向 Jadlog 请求国际报价。其他国家请使用固定运费。
取件点
Jadlog Pickup 承运商仅对巴西地址提供，且只有在已保存 API 令牌时才提供。顾客输入完整的 8 位 CEP 后，模块会向 Jadlog 请求距离最近的活跃取件点，并在承运商下方最多列出 Points to show 个取件点，每个都带有运费，例如 "取件点名称 — 运费 (3 business days) — 地址"。如果列表尚未缓存，会在顾客选择承运商时加载，因此配送步骤不必等待 Jadlog。
每个取件点的运费都向 Jadlog 请求。如果 Jadlog 没有为某个取件点提供运费，则使用固定运费；没有任何运费的取件点会被略过。取件点列表缓存 12 小时。承运商的运费是所选取件点的运费。在选择取件点之前，显示的是有运费的最近取件点的运费。只要其他取件点有运费，没有运费的取件点就不会隐藏承运商。顾客选择取件点后，配送步骤会以新的运费刷新。
必须选择取件点。没有取件点，顾客无法继续，并会看到 Please select a Jadlog Pickup point. 模块会检查该取件点是否在配送 CEP 的 Jadlog 列表中。如果不在，顾客会看到 The selected Jadlog Pickup point is not in the Jadlog list for this CEP. Please choose the point again. 当 CEP 不完整、附近没有取件点或 Jadlog 不可用时，承运商下方会显示提示信息。
没有 API 令牌、没有 8 位 CEP、Jadlog 不可用或附近没有活跃取件点时，Jadlog Pickup 承运商会被隐藏。没有取件点的订单无法发货。
订单
使用 Jadlog 承运商下单时，模块会保存 Jadlog 服务；如果 Jadlog 返回了配送时效，也会保存以工作日计的配送时效。对于 Jadlog Pickup 订单，还会保存取件点的名称、地址和 ID。
后台订单页面会显示一个 Jadlog 区块，包含 Jadlog service、Delivery time，对于 Jadlog Pickup 还包括 Pickup point、Pickup point address 和 Pickup point ID。顾客可在订单确认页面和订单详情中看到所选取件点。取件点会添加到订单确认邮件中的承运商名称里。店铺的新订单邮件（如果您使用邮件提醒模块）也会包含取件点 ID。
请自行在 Jadlog 系统中预约发货。订单会显示您所需的服务和取件点 ID。
许可证密钥
模块需要使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox Jadlog 是 Modules > Module Manager > VibeFox Jadlog > Configure 页面上的第一个区块，位于设置上方。请将密钥输入 License key，然后点击 Activate。之后，该区块会以隐藏方式显示密钥、状态（例如许可证有效期截止日期和您的域名），并提供以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从此店铺移除密钥）。其下方是 Product: presta-shipping-jadlog 一行，以及 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 账户中释放该名额。
没有有效密钥时，结账时不会向顾客显示 Jadlog 承运商，也不会计算任何运费。PrestaShop 前台无法得知您已登录后台，因此承运商对您也是隐藏的：您可以在购买密钥之前设置模块，但无法在结账时进行测试。Modules > Module Manager 的 Alerts 选项卡中会显示提醒。现有订单不受影响。
许可证到期后，模块仍会继续运行，但更新和支持需要续订。在后台工作时，状态会自动重新检查：输入密钥后的前 14 天每天一次，之后每周一次。无需设置 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
结账时没有显示 Jadlog：请检查许可证是否有效，以及 Enable/Disable（或 Enable Jadlog Pickup）是否已开启。在 Shipping > Carriers 中，检查承运商是否覆盖顾客所在国家的区域和顾客组，或开启 Ignore shipping zones。查看模块页面顶部的警告、重量限制和 Minimum order amount。如果顾客尚未输入完整的 8 位 CEP，则只能使用固定运费，请添加 Price per country 的一行或设置 Fallback cost。此外，还可以在商品页面中将商品限制为特定承运商。
只显示固定运费：开启 Debug log，重新加载结账页面，然后查看模块页面上的 Log 字段。它会显示原因：没有 CNPJ 或经常账户、没有始发 CEP、目的地 CEP 不完整、没有 BRL 汇率，或 Jadlog 的错误信息。
日志中出现 HTTP 401 或 403：Jadlog 拒绝了 API 令牌。请与您的 Jadlog 特许经销商核实。出现此错误后，API 会暂停 10 分钟。保存设置会清除暂停，因此您可以立即重试。
取件点不显示：Jadlog Pickup 承运商需要 Enable Jadlog Pickup、API 令牌，以及巴西的完整 8 位 CEP。如果 Jadlog 在该 CEP 附近没有活跃取件点，承运商会被隐藏。请查看日志了解原因。
运费显示为雷亚尔而不是我的货币：请输入 BRL exchange rate（1 BRL 等于店铺默认货币的金额）。
运费看起来过低或过高：请填写商品的重量和尺寸。没有重量的购物车按 0.1 kg 报价，而体积重量需要尺寸。
Jadlog 运费被加了税：将 Tax status 设为 None。
修改后运费看起来已过时：在模块页面点击 Save。这会清除缓存的 Jadlog 运费和取件点列表。
页面提示未找到 Jadlog 承运商：该承运商已在 Shipping > Carriers 中被删除。请在 Modules > Module Manager 中重置模块以重新创建。
卸载
进入 Modules > Module Manager，打开 VibeFox Jadlog 旁边的菜单，选择 Uninstall。许可证密钥和许可证状态始终会被删除。缓存的运费和取件点列表始终会被清除。如果 Remove data on uninstall 已开启，两个承运商都会被删除（订单保留其历史记录），设置和日志也会被移除。如果关闭，承运商只会被停用，所有设置都会保留。重新安装模块后，承运商会恢复为之前的状态。随订单保存的 Jadlog 服务、配送时效和取件点始终会保留。
Jadlog 是其各自所有者的商标。本模块与 Jadlog 无关联，也未获得 Jadlog 的认可。