README

描述

实现了发票、订单、价格和库存的集成流程，适用于 Vtex 平台。此外，还实现了 v3 Feed 配置以接收订单。

安装

composer require vega/connector-vtex

配置

• site：对应 Vtex 商店代码。通常从 Vtex 提供的 https://.vtexcommercestable.com.br url 中提取。默认无值。
• app_key：用于身份验证令牌的识别密钥。默认无值。
• app_token：用于身份验证的秘密令牌。默认无值。
• base_uri：环境 URL 模板。变量 {{site}} 将被替换为在 site 设置中定义的值。默认值 'https://{{site}}.vtexcommercestable.com.br'。
• orders_mode：在此集成中获取订单的方式。默认值：pagination，通过分页 Vtex 的 List orders API 获取订单的配置。另一个可能的值：feed，通过 feed v3 API 获取订单的值。要配置此获取方式，至少需要成功执行一次 Feed - Config 集成。
• mongo_composite_keys：用于在 MongoDB 中存储的唯一键的数组。这些字段有助于在集成中键（sku 等）重复时正确计数记录。可以包含在数组中的可能字段：seller，warehouse。
• subaccounts.subaccount_key：用于 sellers 的字段名称。默认值：seller。
• subaccounts.marketplace_value：在集成中 "seller" 字段中用作市场值的值。默认值：marketplace。
• entities：连接器可用的实体为 orders、order、invoices、stock、catalog、sku、price、log、rules、email 和 feed。
• entities.orders.get.confirm：控制集成后 Orders - Get 下载后的订单确认的选项行为。默认值：false。
• entities.orders.get.use_subaccounts：控制订单处理过程是否查找配置的可能的卖家订单。默认值：false
• entities.invoices.create.status_ready：表示订单可以准备的状态的订单状态。目前未使用。默认值 'ready-for-handling'。
• entities.invoices.create.status_start_handling：表示正在准备订单的订单状态。默认值 'start-handling'。
• entities.invoices.create.status_handling：表示正在准备订单的订单状态。默认值 'handling'。
• entities.invoices.create.status_invoiced：表示已开票的订单状态的订单。默认值 'invoiced'。
• entities.invoices.get.use_subaccounts：控制 invoices 处理过程是否查找配置的可能的卖家订单。默认值：false
• entities.invoices.create.validations：可选。记录字段验证的文件名称。见下文。
• entities.feed.config.data：包含配置订单 feed v3 所需的值集
  • type：类型过滤器。我们使用默认值 FromWorkflow，表示我们将接收状态更改的订单。
  • status：要获取的订单状态的数组。默认配置为接收ready-for-handling。
  • expression：未使用的字段，仅用于在未使用的FromOrders类型中进行过滤。
  • disableSingleFire：在“false”中发送的字段，实际上仅用于未使用的FromOrders类型。
  • visibilityTimeoutInSeconds：订单发送后在feed中不可用的秒数，等待处理确认。默认值：250
  • MessageRetentionPeriodInSeconds：订单在feed中的生存时间（秒），之后将不再可用。默认值：345600
• entities.feed.get.maxcalls：订单处理过程中对“Get Feed”的最大调用次数。默认值：15
• entities.stock.update.use_subaccounts：控制库存处理过程是否包括配置的可能卖家产品。默认值：false
• entities.stock.update.validations：可选。注册字段验证文件的名称。请参阅以下内容。
• entities.price.update.use_subaccounts：控制价格处理过程是否查找配置的可能卖家产品。默认值：false
• entities.price.update.validations：可选。注册字段验证文件的名称。请参阅以下内容。

集成

发票 - 创建

这是一个出站方向流程，它读取存储在Data Layer中的订单标识符，以确定和执行在Vtex环境中处理订单所需的操作。

流程

遍历Data Layer中的订单标识符。对于每个标识符，通过查询Get order端点来获取订单详情，并应用Order Item模型以简化订单行，以及应用Order模型以简化订单结构。然后还应用Order Item和Order的转换以规范金额和日期值的格式。

评估订单是否已被开具发票，如果是，则将记录标记为未更改并中断相同订单的处理。

如果订单之前未被开具发票，则确定是否需要将其标记为start-handling，并在必要时通过使用Confirm负载调用Start handling order端点来更新订单。

最后，通过应用Invoice负载调用生成发票的端点Order invoice notification。

订单 - 获取

这是一个入站方向流程，它从Vtex环境获取订单，处理它们并将它们存储在Vega的Data Layer中。

流程

根据orders_mode配置，如果设置了feed模式，则执行一系列查询（最多为entities.feed.get.maxcalls配置的值）到Get Feed API，否则查询List orders端点上的可用订单，并对所有结果页面进行迭代。在这一阶段，应用模型以将结果简化到最小表达式，并应用转换以标准化数值和日期。

每个获取到的订单都会单独查询Get order端点以获取订单详情，并应用Order Item模型简化订单行，并应用Order模型简化订单结果的总体结构。然后，也应用Order Item和Order转换以标准化金额和日期的格式。

可选地，对于订单内的每个项目，可以通过设置布尔参数entities.orders.get.get_sku_data_by_id为true来获取产品详情。对产品数据应用Skudata模型以简化结构，并将其保存在项目数据中。

最后，使用未记录的Conversation Tracker服务将Vtex生成的电子邮件别名映射到客户的真实电子邮件账户。使用Email模型处理结果。

结果信息存储在Data Layer中。

可选地，通过调用Start handling order服务并使用Confirm负载进行修改，确认订单到Vtex。

在feed模式下，过程将存储订单id和从feed关联到订单的handle哈希，并将正确存储在data layer中的那些放入handles数组中。在此点，通过调用APICommit Feed并使用Feed负载来发送Vtex处理过的handles确认。

价格 - 更新

这是一个方向为outbound的流程，其中读取由RefId（SKU代码）指定的产品，并更新价格表中的现有定义。

流程

遍历Data Layer中的条目，并消费Get SKU by RefId服务以获取Vtex的SKU标识符，并将其映射到Skudata模型。

使用此标识符通过调用 根据skuId获取价格（旧版 - v1） 来查询当前价格信息，并使用 价格 模型处理结果。

最终，使用从价格列表中获得的ID，通过 保存价格（旧版 - v1） 调用，并使用 价格 负载进行修改来发送更新。

库存 - 更新

这是一个 出站 流程，它读取由RefId（SKU代码）指定的产品，并更新这些产品的物理库存。

流程

遍历Data Layer中的条目，并消费Get SKU by RefId服务以获取Vtex的SKU标识符，并将其映射到Skudata模型。

使用此标识符通过调用未记录的方法 库存设置平衡 并使用 库存 负载来更新每个产品的库存。

数据流 - 配置

此集成用于配置将在 订单 - 获取 集成中接收的数据流，如果将 orders_mode 设置为 feed 模式。应仅为此初始化数据流或想要修改要接收的订单状态列表或订单保留/生命周期时间时执行。

流程

调用Vtex的 配置数据流 API，取 entities.feed.config.data 的配置，并通过 数据流配置 负载传递。

验证

如配置部分所述，存在在发票、库存和价格集成中验证接收到的记录的可能性，以避免处理缺少在验证中期望的字段的记录。为此，使用 vega/validation 模块。如果想要进行验证，需要配置文件中文件的名称，其中包含验证配置。如果在这些配置中配置了 validations 键，则将验证该文件。文件路径为：Connectors/Vtex/[实体]/Validations（其中实体将是：Stock、Price或Invoices）。示例文件 在此

另请参阅 CHANGELOG.md