15 · PrestaShop 集成

◀ 返回目录

与 PrestaShop 的集成允许 Factuzam 在明确授权同步后，成为网上商店 价格与库存的数据源。变更会写入队列，并通过 PrestaShop 的直接 API 在后台发送。

集成还可以在商店中创建尚不存在的商品，包括类别、商品、尺码与颜色组合、 价格和主图。Factuzam 创建的所有商品在 PrestaShop 中最初都处于停用状态。 只有当配置明确授权，并且创建或同步流程正确完成后，才可在最后一步自动启用； 也可以之后手工启用。

发布规则：在 Factuzam 中勾选 En web，表示商品可参与已配置的集成。 如果未勾选 Activar artículos en PrestaShop al marcar En web， 商品可见性不会改变。勾选后，Factuzam 也只会在获授权的创建或同步流程 正确完成后，作为最后一步请求启用。

取消 En web 的规则：Factuzam 会询问如何处理。选择 Sí 会停用 PrestaShop 商品并停止同步；选择 No 只停止同步，保留远端可见状态； 选择 Cancelar 则不保存更改。任何选项都不会删除商品、更改价格或发送零库存。

1. 集成状态

本章会随着集成逐步完成而更新。应区分已经可用的功能，以及仍需实施和测试的功能。

集成会更新远端目录，但不会把在 PrestaShop 商品资料中手工完成的变更 自动导回 Factuzam。启用前必须确定每项数据由哪个系统负责。

Ventas Mayor ▸ Pedidos ▸ Importar de PrestaShop 会读取 Parámetros del entorno 中有效的 URL 和 API 密钥。窗口没有自己的凭据， 也不会显示密钥。公司和仓库取自当前会话。如果窗口打开后更改了配置， 必须重新连接并列出订单后才能导入。

这种复用目前仍不完整：导入器查询 orders 时不会传递 Id. tienda。 必须使用只允许访问单一目标的密钥，且当前不适用于多店环境。操作步骤、列、 客户和商品创建、GASTOS_T 服务以及全部操作限制，详见 Ventas Mayor ▸ Pedidos ▸ 导入 PrestaShop 订单。

验证现状：目前尚未作出允许完整集成用于生产环境的 GO 决定。 实验室中已有商品目录和队列的部分证据，但订单、导入、并发、服务、 全量扫描以及直至开票的完整周期测试仍待完成。请保持绝对库存写入停用， 并只针对受控安装进行测试。

2. 总体概览

Cambio en artículo, tarifa o stock
               |
               v
      Cola de PrestaShop
               |
               +---- reference única ----> verifica; actualiza si se autoriza
               |
               +---- ninguna reference --> alta inicialmente inactiva, si se autoriza
               |
               `---- varias reference ---> ERROR inmediato, sin POST

Tras completar sin error el alta o la sincronización
               |
               `---- activación final, solo si N->S y el perfil la autoriza

各复选框彼此独立。Sincronizar stock y precios 授权修改现有商品； Crear artículos en PrestaShop al darlos de alta 在商品不存在时请求创建； Activar artículos en PrestaShop al marcar En web 只允许在 En web 由 No 变为 Sí 所触发流程的最后一步，把 active 改为 1。 Factuzam 会在第一个 POST 前验证全部本地数据，所有新商品均以 active=0 创建。 有歧义的参考始终作为故障处理，绝不会触发另一次创建或启用。

事件是主要机制。即使未勾选 Hacer barrido periódicamente， 系统也始终每 60 至 120 秒检查一次待处理恢复。该复选框只启用每隔若干小时执行的 完整对账，用于发现因故障或旧版导入而没有进入队列的变更。

队列中的一行代表完整商品。如果某个 SKU 的价格发生变化，Factuzam 会重新计算 商品及其全部组合，但只向远端值确实不同的资源发送修改。

3. 按范围配置

配置位于 Otros ▸ Parámetros del entorno 的 PrestaShop 部分。 其保存方式与其他参数相同：可以针对用户、组或 Todos 定义。 有效值按以下顺序取得：

按范围生效的 PrestaShop 配置；API 密钥和 URL 均保持隐藏。

1. 用户专用值。
2. 如果用户未定义，则使用其组的值。
3. 如果组也没有值，则使用 Todos 的值。

更具体的配置会覆盖通用配置。因此，两家公司可以使用不同用户或组，分别关联 不同公司、价目表、仓库和 PrestaShop 商店。每个会话只处理自己的有效配置， 不会遍历其他配置文件。

授权维护商品目录的两个复选框初始均未勾选，可按下表组合。 Activar artículos en PrestaShop al marcar En web 和 Hacer barrido periódicamente 也默认未勾选，但不会改变此矩阵： 前者决定流程结束时的可见性，后者决定何时查找完整差异。

如果 En web 从 No 变为 Sí 且勾选了启用选项，则只有在正确完成矩阵中对应的 操作后，才会加入 active=1 请求。如果之前发生错误，商品不会启用。 启用选项未勾选时，新商品保持停用，现有商品保持原有可见性。

勾选 Sincronizar stock y precios 前，必须明确配置并检查 URL。 全新安装不会预设任何目标。

旧键 appPrestaShopActivo 和 appPrestaShopStockActivo 即使在升级后仍有保存， 也不再控制工作器或隐式启用任何功能。必须使用上表中的明确控件。

如果多个兼容配置共享同一安装和商店，但请求不同的扫描间隔，实际采用最频繁的节奏。 它们共享同一个远端标记，以避免重复遍历商品目录。

队列按标准化 URL 和商店标识符隔离目标。从测试商店切换到生产商店时， 不会复用旧安装的远端标识符。两家公司使用不同商店时必须配置不同目标。

多个启用配置可以共享相同的标准化 URL 和 Id. tienda，前提是其公司、价目表和 同步选项完全相同。每个配置可自行决定是否参加定期扫描。如果工作器发现任一业务数据 不同，会把该目标视为冲突，停止处理并记录警告。必须修正配置使其兼容， 或分配不同目标后，处理才会恢复。

API 密钥权限

密钥应只拥有必要权限：

订单权限均为只读。不使用该功能时不应授予。只要 orders 查询尚未应用 id_shop，导入器所用密钥就必须限定到单一商店。

除非专门设计并授权某项管理操作，否则不应授予删除权限。自动恢复绝不能删除 与其他商品共享的类别、尺码或颜色。

4. 选择商品与仓库

商品（Artículos）

在 Archivo ▸ Artículos 中，En web 复选框决定商品是否参加集成。

• 勾选后，会把商品完整检查加入队列。
• Factuzam 按 reference 精确匹配查找主商品。
• 如果只有一个匹配项，会进行验证；只有勾选 Sincronizar stock y precios 时才更新商品及其 SKU。
• 如果没有匹配项且授权 Crear artículos，则验证并执行完整创建，保持停用。
• 如果未授权创建，不存在商品会以故障结束。
• 如果有多个匹配项，会直接记录 ERROR，既不选择任何一个，也不创建第三个。
• 如果标记从 No 变为 Sí，并授权 Activar artículos en PrestaShop al marcar En web， 只有在适用的创建或同步正确完成后才请求启用。
• 取消勾选时，Factuzam 会在保存前显示对话框。

更改 En web 需要 Permisos ▸ Artículos ▸ Activar/desactivar web 权限。没有该权限时复选框为只读，保存操作也不能改变标记。

取消 En web 时，对话框提供三个选择：

• Sí：保存 En web = No、停止同步，并请求远端停用（active=0）。
• No：保存 En web = No，仅停止同步；商品保留其在 PrestaShop 中 已有的可见状态。
• Cancelar：不保存更改；商品继续保持 En web。

前两种情况都会取消待处理的价格和库存变更。移除标记不会执行其他修改：

• 不发送零库存；
• 不更改最后发送的价格；
• 不删除商品；
• 不删除组合、类别或图片。

如果再次勾选 En web，Factuzam 会加入一次完整检查。只有有效配置勾选 Sincronizar stock y precios 时，才会发送当前价格和库存。 只有同时勾选 Activar artículos en PrestaShop al marcar En web 时， 才会请求最后启用。

网店商品的 SKU 不会被物理删除，而会在 Factuzam 中标记为停用，以保留其参考。 集成停止发送其价格；启用同步时会发送零数量。PrestaShop 的组合没有独立的 active 字段，因此该操作既不会在远端“停用”SKU，也不会删除它。

仓库（Almacenes）

在 Archivo ▸ Almacenes 中，En web 复选框选择哪些仓库的库存 要汇总到网上商店。可以选择一个或多个，但每个配置只使用属于其所配置公司的仓库。 其他公司的已勾选仓库不会参加该目标。

除标记外，仓库还必须：

• 已启用；
• 为实体仓库；
• 用途类型为 ESTANDAR。

即使尝试勾选，瑕疵品仓、寄存仓和其他非标准用途仓库也会被排除。 新建仓库时，该复选框初始未勾选。

勾选或取消仓库时，会把受影响商品加入队列，重新计算网店库存合计。 无需从界面手工逐个处理商品。

5. 队列、事件、恢复与可选扫描

Factuzam 主要流程中的价格和库存变更会尽可能在同一工作单元中调用入队器。 同一商品的多次调用会合并为一行。操作确认后，生成待处理项的流程本身会唤醒消费者。 信号是累积的：一个批次的一百次变更只触发一次队列排空，而不是一百个独立周期。 这些信号不会重置或推迟恢复机制的单调截止时间。即使变更持续到达，安全检查仍会 每 60–120 秒到期，不会被正常队列活动无限阻塞。

如果发送过程中商品发生变化，新变更会递增版本，但不会释放当前认领。 前一版本发送结束后，该行重新回到 PENDIENTE。这样可防止两个工作器 以相反顺序写入新旧版本。

取消 En web 并选择 No 时，同一版本控制会清空两个变更指示器。 选择 Sí 时，还会请求远端停用。已经进行中的请求可以完成；之后会按需执行 可见性决定，并且不再认领新的价格或库存版本。选择 Cancelar 不保存更改， 也不改变队列。

系统始终每 60 至 120 秒执行一次恢复检查，以处理进程在入队后关闭或认领中断的情况。 数据库会针对每个目标，只允许一个 Factuzam 实例执行该检查。获胜进程会恢复过期认领 并排空待处理项，其他实例不会重复工作。取消 Hacer barrido periódicamente 不会停用此机制。两次轮次之间收到的信号也不会推迟下一截止时间。

勾选 Hacer barrido periódicamente 且已过配置小时数时， 只由一个启用会话执行完整对账，并重新把需要处理的 En web 商品加入队列。 该仲裁独立于恢复检查的获胜者，因此某个未勾选扫描的配置不会阻止另一个兼容配置 所请求的扫描。未勾选时不会遍历完整目录，但仍每 60–120 秒恢复并处理队列。 完整对账失败也不会妨碍继续处理事件。

每个会话只认领其有效配置对应目标的队列。目标按标准化 URL 和商店标识符隔离。

排空队列前，工作器会根据用户 → 组 → Todos 的继承关系，重新从数据库读取 有效配置。因此，保存到用户、其组或 Todos 的更改或停用，可以传播到已经打开的 终端，而无需重启应用程序。

监控窗口

可以从 Otros ▸ Colas de envíos ▸ PrestaShop 查看队列。 列表显示商店、商品代码和名称、待处理或已认领的价格/库存指示器、状态、尝试次数、 下次尝试时间、最后变更和最后发送时间，以及该行的总体错误。

商品目录任务及其状态，以及所选商品的 HTTP 操作历史。

选择一行后，会显示 HTTP 操作历史，包括尝试次数、顺序、方法、相对资源、 HTTP 状态代码和文本、结果、开始时间和持续时间。选择某次操作后，系统按需加载 其 Petición、Respuesta del servidor 和 Error 标签页。 因此，打开或浏览主列表时不会读取较大的正文。

“Respuesta del servidor”标签页显示为所选 HTTP 操作安全记录的响应正文。

从安装此版本开始保留历史记录。此前执行的操作不会追溯重建。

历史记录用于诊断。它不保存 API 密钥、授权请求头、二进制内容、base64 数据 或完整本地路径。上传图片时只保留安全说明，例如名称、大小和指纹。 超过存储限制的文本会截断，并显示清晰的截断标记。

该窗口为只读，不能编辑、删除或重试某一行。它只允许刷新查询、 在有权限时导出，以及转到关联商品。独立权限 Consultar、Excel 和 Ver petición/respuesta 分别控制列表访问、导出和明细访问。 管理员可以查看所有目标；其他用户只能看到其有效配置解析出的商店。

表格显示 Id. tienda，但不显示安装标签。如果监控多个安装，而它们复用了 相同商店标识符，仅凭该数据无法区分；解释或导出行之前，应核对实际目标。

发送过程中关闭 Factuzam

当此实例正在处理商品时尝试关闭 Factuzam，系统会先阻止新的认领，并提供三个选项：

• Esperar：只完成当前商品，然后关闭。
• Cerrar de todos modos：不会中断已经进行中的 HTTP 请求。等待请求返回后， 将商品重新置为待处理且不消耗一次尝试，然后关闭。
• Cancelar cierre：保持 Factuzam 打开，解除认领阻止并恢复队列消费。

强制关闭可能需要等待当前网络操作结束。被释放的行会保留价格、库存或可见性变更， 并可在下一周期由本实例或其他实例重新认领。

6. 商品与 SKU 价格

PrestaShop 保存未税价格：

• products.price 是商品基础价格；
• combinations.price 是组合相对于基础价格的差额；
• SKU 实际价格是两者之和。

Factuzam 根据有效配置的价目表和公司取得当前最终价格。如果价目表含增值税， 发送前会除以 1 + tipo de IVA / 100。 对于已经存在的商品，当前集成不会更改或验证 id_tax_rules_group： 管理员必须检查远端税务规则是否正确。新建时使用针对本地增值税类型配置的标识符； 两个系统显示相同百分比并不足够。

采用 21% 增值税的示例：

不应把 29,95 直接作为 combinations.price 发送，否则 PrestaShop 会再次把它加到基础价格上。

只有一个 SKU 发生变化时，PrestaShop 9 可以只修改其组合。 不过 Factuzam 仍会重新计算和验证商品的全部组合。如果基础价格变化， 会重新计算全部差额，确保其他 SKU 的实际价格保持正确。

此行为已在本地 PrestaShop 9.1.4 商店中用一个包含三个组合的商品验证。 仅修改一个差额时，基础价格和其他两个组合仍保持原值。测试也确认 combinations.price 是差额，而不是 SKU 的最终价格。

7. 创建不存在的商品

Crear artículos en PrestaShop al darlos de alta 复选框已可用， 初始未勾选，并且独立于 Sincronizar stock y precios。 只有勾选该复选框时，不存在的 reference 才会启动创建。 有歧义的参考会以 ERROR 结束，绝不会触发创建。

创建过程不是单个请求。工作器会针对多个 PrestaShop 资源依次执行：

1. 验证全部本地数据，此时不创建任何内容。
2. 在配置根类别下解析或创建商品类别路径。
3. 解析或创建 Color、Talla 等属性组。
4. 解析或创建各 SKU 使用的属性值。
5. 以 active=0 创建主商品。
6. 为每个启用 SKU 创建一个组合，并以确定性方式选择唯一默认组合。
7. 如果商品尚无任何图片，则上传一张真实的通用照片。
8. 只有获授权时才继续同步价格和库存。
9. 如果流程由勾选 En web 触发且配置允许，则仅在上述步骤全部正确完成后启用商品。

商品始终以完整且初始停用的方式创建。当 appPrestaShopActivarArticulosAlMarcarWeb=False 时，会保持停用，等待人工检查。 参数为 True 时，同一作业可在最后一步启用。部分创建或带错误的同步绝不能 使商品变为可见。

预先验证

首次 POST 前至少必须检查：

• 商品代码和 SKU 参考不为空且不重复；
• 商品、类别、价目表和属性均已启用；
• 类别层级完整且没有循环；
• 名称和说明符合 PrestaShop 限制；
• 当前基础价格和每个 SKU 的实际价格；
• 增值税与远端税务组的映射；
• 每个所需变体维度都有一个有效值；
• 已登记真实照片，且文件存在并可读取；
• 能明确确认 PrestaShop 中不存在该商品及其参考。

任何要求不满足时，商品会以具体原因进入 ERROR，本地验证会阻止创建开始。

管理员检查

管理员进入 PrestaShop 后台检查：

1. 名称、说明和类别。
2. 增值税类型和规则。
3. 尺码、颜色和默认组合。
4. 多个组合的最终价格，包括负差额组合。
5. 封面照片和按颜色的图片。
6. 库存政策和订单可用性。

只有检查完成后，才启用所需的新类别。如果未勾选自动启用，也要手工启用商品。 如果已经勾选，则确认作业无错误完成，且商品只在最后一步变为可见。

8. 商品类别与网店类别

创建时，Factuzam 商品类别会转换为 PrestaShop 类别。可继承参数 Niveles de familia a crear (0 = todos) （appPrestaShopNivelesFamiliaAlta）决定导出本地层级的哪一部分：

• 0：从根到叶类别的全部本地层级；
• N > 0：从叶类别向上计算的最后 N 层。

选定子集会按根 → 叶顺序保留和创建：父级先于子级。配置的 PrestaShop 根类别 只是承载该子集的远端起点，不计入这些本地层级。例如，DEMO-CAMISA 仅属于本地类别 ROPA；因此 0、1 或任何更大值都只会导出这一层本地类别。

已经存在的类别保留其状态。当前实现会把新类别创建为启用状态。 商品以 active=0 创建，之后只能根据启用参数在最后一步启用。

身份不能只依据名称。两个分支可能包含同名类别。创建前，实现会查找父级与 标准化链接的组合：

tienda + categoría padre + enlace normalizado -> id_category remoto

商品使用叶类别作为 id_category_default，并将其加入商品的类别关联。 用于导出本地类别的根类别必须可针对每家商店配置。

9. 尺码、颜色与组合

本地变体属性转换如下：

每个组合会以本地 SKU 的精确代码作为 reference，并关联其全部值， 例如 Color: Azul 和 Talla: L。只创建启用的 SKU。 之后会将唯一一个组合标记为默认组合：按稳定的属性和参考排序取第一个。

尺码和颜色是共享资源。创建前会查找对应的远端组或值。如果存在多个匹配项， 且无法判断哪个才正确，创建会停止并等待检查，不会随机选择。

10. 真实照片

Factuzam 按商品、SKU 前缀（通常代表颜色）或完整 SKU 登记照片。 集成使用 real 分辨率文件：

<appDirFotos>\real\<nombre registrado>.png

数据库保存的源扩展名仅供参考；Factuzam 生成的实际工作文件为 PNG。

当前实现会选择通用主图，并且只在远端商品没有任何图片时上传。 PrestaShop 会自动生成派生尺寸。图库、替换已经上传的照片，以及按颜色关联照片 不在当前流程内，必须手工处理。

在 fza_articulos_fotos 为空的安装中，照片文件只是散落在目录里并不足够。 必须先将照片与商品或 SKU 关联。系统不会根据文件名猜测这种关系。

11. 库存安全

网店库存只汇总符合条件的仓库，并将结果下限限制为零。瑕疵品仓绝不参与。

但是，PrestaShop 标准 Webservice 接收的是绝对数量。如果网店销售尚未在 Factuzam 中自动预留，之后的本地移动可能再次写入一个数量，从而补回网店 已经卖出的件数。

因此：

• Sincronizar stock y precios 默认保持未勾选；
• 当前复选框同时授权价格和库存，现有工作器没有独立的库存授权；
• 在具备自动接收或预留网店订单、并完成并发测试前，不应在生产环境勾选；
• 服务、瑕疵品仓、寄存仓和非标准仓库均被排除。

目前也不支持商店之间共享库存。客户端要求 stock_available 行必须精确属于 所配置商店；如果 PrestaShop 对商店组使用 id_shop=0，会安全失败。 该模式需要先验证 share_stock 和实际商店组。

这一谨慎策略不会阻止创建类别、商品、组合、价格或主图。 同步未勾选时，新商品会准备完整并保持停用，不发布本地库存。

12. 重试与防止重复

API 无法用一个事务创建整个商品目录。创建过程按可恢复序列处理：

VALIDAR -> CATEGORIAS -> ATRIBUTOS -> PRODUCTO_INACTIVO
        -> SKU -> IMAGEN_PRINCIPAL -> SINCRONIZACION_AUTORIZADA
        -> ACTIVACION_FINAL_OPCIONAL

每次创建前都会按身份查找远端资源。网络中断后，下一次尝试会重新查找并复用 已经存在的内容。功能测试组必须验证这种幂等性，尤其要覆盖两个工作器并发的情况， 因为查找与 POST 并不属于同一个事务。

安全规则：

• 有歧义的参考绝不触发新建；
• 商品和 SKU 按精确参考及父级关系解析；
• 类别和属性在其父类别或组内查找；
• 商品已有图片时不会再次上传；
• 失败绝不会启用商品；
• 共享资源不会作为自动补偿被删除。

13. 故障诊断

错误消息和日志绝不能包含 API 密钥。

14. 部署检查清单

1. 应用数据库迁移，并检查 En web 标记。
2. 先配置与真实商店相同版本的测试商店；不要用生产环境进行初始验证。
3. 创建最小权限 API 密钥。如需导入订单，只为 orders、customers、 addresses、states、carriers、order_states、customer_threads 和 customer_messages 添加读取权限。
4. 配置正确范围（用户、组或 Todos）、URL、商店、公司和价目表， 并保持四个复选框未勾选。
5. 在导入尚未按 id_shop 筛选时，使用只面向一家商店的专用密钥， 不要在多店安装中启用该流程。
6. 检查 Niveles de familia a crear (0 = todos)：使用 0 导出全部本地层级， 或使用从叶类别起算的正数。
7. 只勾选会提供网店库存的标准仓库。
8. 检查类别、增值税、SKU、属性、价格和真实照片。
9. 使用一个包含多种颜色、尺码和不同 SKU 价格的商品进行测试。
10. 确认有歧义的 reference 会立即进入 ERROR，且不创建资源。
11. 在通过实验室功能测试组前，保持 Crear artículos en PrestaShop al darlos de alta 未勾选。
12. 使用正确公司和仓库登录；在实验室分别导入一个有运费和一个无运费的订单。 检查客户、商品、SKU、增值税、合计和 GASTOS_T 服务行。
13. 重复同一 ID PS，制造中途错误并确认订单不会重复，且后续选中订单继续处理。 不要并发导入同一订单。
14. 将测试订单处理到送货单和发票：GASTOS_T 必须保留 SERVICIO 类型、 计税基础和增值税，且不移动库存；实体商品行必须正常移动库存。
15. 使用受控真实发送测试关闭选项 Esperar、Cerrar de todos modos 和 Cancelar cierre。
16. 在授权绝对数量前，验证区别于手工导入的网店订单自动接收或预留机制。
17. 在完整测试组没有形成有记录的 GO 决定前，保持 Sincronizar stock y precios 未勾选。
18. 自动启用未勾选时，重复创建，确认保留 ID、不产生重复，并让商品保持完整但停用。
19. 在实验室勾选 Activar artículos en PrestaShop al marcar En web， 确认 active=1 只在正确流程最后请求；制造之前的错误并确认不会启用。
20. 测试取消 En web 时的三种回答：Sí 停用、No 只停止同步、 Cancelar 不保存。

开发测试只针对当前本地 PrestaShop 安装执行。不会在生产商店中创建或修改测试数据。

15. 官方技术参考

• 使用 Webservice 完整创建商品
• products 资源
• combinations 资源
• 属性组
• 属性值
• 图片管理

◀ 架构与开发 · 目录