免费游戏的API资讯

此部分提供了关于免费游戏的API集成的额外资讯。请参考DevPortal以了解更多免费游戏API的响应和其示例。

优惠管理API

此API允许运营商创建新的免费游戏优惠。

关于参数

此端点所需的参数是agentCode.

关于请求主体

• 优惠名称不是独一无二的，可以重复。

• durationAvailableInDaysAfterAwarded属性指的是有效期。

  • 此属性的默认值设置为7天。

  • 有效期限制在1到99天的范围内。

• numberOfRounds属性限制在1至100个回合之间。运营商设置的回合数会在玩家页面上显示。

  

• 需要注意的是，回合是在优惠中所有符合条件的游戏之间共享的。例如，如果该优惠适用于3个游戏，并且"numberOfRounds": 10，玩家在这3个游戏中总共可以玩10个回合，而不是每个游戏都可以玩10个回合。

• offerAvailableFromDateUTC和offerAvailableToDateUTC属性指的是优惠的有效期。

  • 如果未提供offerAvailableFromDateUTC，则默认设置为优惠创建的当前时间。

  • 如果未提供offerAvailableToDateUTC，则默认设置为从开始日期起的3个月后。

  • 优惠的最长有效期为1年。

关于200响应

• 无论系统中是否存在重复的优惠名称，优惠的offerGuid是独一无二的。

• 在200响应中，reuse是用来检查运营商欲创建优惠是否重复，如重复则"reuse": true。在创建新的优惠时，系统会检查是否存在具有相同参数且在最近一小时内创建的优惠。如为相同，系统将返回现有优惠的GUID。

该API允许运营商获取现有的免费游戏优惠及其资讯的列表。

关于参数

该端点的必需参数是agentCode。其他参数可视需求带入。

• offerStatus可以设置为搜索启用或结束的优惠。

关于200响应

• numberOfAssignedPlayers与numberOfInstances不相等，因为一个玩家可以被多次分配到同一个优惠中。例如，当一个玩家被分配两次时，numberOfAssignedPlayers是1，但numberOfInstances是2。

• nearestCostPerBet（也称为每个回合的价值）是游戏的最低投注额。

运营商在优惠还未被使用的情况下，可以使用此API修改免费游戏优惠的信息。

关于参数

该端点的必需参数包括offerGuid和agentCode。为了确保更新应用到正确的优惠上，需要在请求中提供准确的offerGuid。

关于请求主体

• 运营商可以从请求主体中删除他们不希望更新的属性，以更新他们所需要的属性。

使用此API将导致免费游戏优惠关闭。代理可自行选择是否要保留或移除已分配的派发。

关于参数

此端点所需的参数包括 offerGuid 和 agentCode。请求主体必须包含 cancelAwardedInstances 字段，该字段指示如何处理此优惠的现有派发。

• 若要移除现有派发，请将 cancelAwardedInstances 设置为 true。

• 若要保留现有派发，请将 cancelAwardedInstances 设置为 false。

玩家管理API

该API允许运营商将玩家分配到免费游戏优惠中，为玩家创建一个优惠派发供其使用。

关于参数

该端点的必需参数包括playerId、offerGuid和agentCode。

关于请求主体

• offerAvailableToPlayerFromDateUTC属性指定了玩家可以开始玩免费游戏的日期和时间。如果未提供此属性，则默认为当前日期和时间。确保日期在优惠期限内非常重要。

  • 最晚的派发开始日期可以设置为优惠期限的最后一天，允许玩家在有效期结束之前使用优惠。

关于202响应

成功将玩家分配到优惠后，API应返回202响应。响应将包括独一无二的instanceGuid。

该API允许运营商将多个玩家分配给免费游戏优惠，为每个玩家创建一个派发。

关于参数

该端点的必需参数包括offerGuid和agentCode。

关于请求主体

• offerAvailableToPlayerFromDateUTC属性指定了玩家可以开始玩免费游戏的日期和时间。如果未提供此属性，则默认为当前日期和时间。请确保日期在优惠期限内。

  • 最晚的派发开始日期可以设置为优惠期限的最后一天，允许玩家在有效期结束之前使用优惠。

• 运营商可以在players属性下输入玩家ID列表。

  • 玩家ID必须是字母数字（A-Z，0-9），最多可以包含50个字符。ID也可以包含下划线（_）或连字符（-）。

  • 最大玩家数量是20000。如果玩家ID出现多次，将导致重复分配，而不是只分配一次。

关于202响应

成功分配玩家到优惠后，API应返回202响应。响应将包括唯一的batchGuid，以及按玩家ID匹配的派发列表。每个玩家将有唯一的instanceGuid。

该API允许运营商更新派发的状态。

只有已分配（Assigned）和玩家拒绝（Player Rejected）的派发可以更改为其他状态（在有效期内）。

Assigned （已分配）→ 更改为Cancelled（取消）（当运营商想要取消分配给玩家的派发时）

Player Rejected（玩家拒绝） → 更改为Assigned（已分配）（当运营商想要为玩家恢复优惠时，派发GUID将保持不变）

如果在玩家进行游戏时派发被取消，玩家将会看到警告，提示游戏会话已终止，并需要关闭游戏。

关于参数

该端点的必需参数包括instanceGuid、playerId、和agentCode。

关于请求主体

• offerAssignmentStatus可以设置为Cancelled或Assigned。

这个API方法将返回分配给指定玩家的优惠列表。

关于参数

该端点的必需参数包括playerId和agentCode。其他参数可视需求带入。

• offerAssignmentStatus参数可被设置为以下任一派发状态：Assigning（分配中）、Assign Failed（分配失败）、 Assigned（已分配）、Player Rejected（玩家拒绝）、Cancelled（取消）、Cancelling （取消中）、Cancel Failed（取消失败）、 Fully Consumed（全部用完）和 Expired（已过期）。

• offerStatus可以设置为搜索启动的或结束的优惠。

关于200响应

响应包含分配给玩家的优惠资讯，以及每个派发的详细资讯。

这个API方法将返回分配给指定免费游戏优惠的玩家列表。

关于参数

该端点的必需参数包括offerGuid和agentCode。其他参数可视需求带入。

• offerAssignmentStatus参数可被设置为以下任一派发状态：Assigning（分配中）、Assign Failed（分配失败）、Assigned（已分配）、Player Rejected（玩家拒绝）、Cancelled（取消）、Cancelling （取消中）、Cancel Failed（取消失败）、Fully Consumed（全部用完）和 Expired（已过期）。

• startAvailableFromDateUTC和endAvailableFromDateUTC参数反映了玩家可以玩免费游戏的可用期限。

  

此API允许运营商获取批次上传的详细资料。批次上传的类型可为以下两种：

• 批次分配

• 批次取消

关于参数

该端点的必需参数包括batchGuid和agentCode。

关于200响应

在收到成功的200响应后，API将提供以下资料：

• 玩家分配详情列表

  • 唯一的派发GUID。

  • 派发创建日期。请注意，这不是玩家可以开始使用优惠的日期；开始使用优惠的日期是offerAvailabletoPlayerFromDateUTC。

  • offerAssignmentStatus是派发状态。批次作业被取消且派发状态为已分配时，响应将包括 isPartiallyConsumed=true。

  • 优惠分配前，玩家ID是否存在于MG+系统中。若查无匹配ID，系统将在批次上传过程中创建此玩家。

• 批次资料

  • 唯一的批次 GUID。

  • 批次上传状态：指批次的当前状态。如果所有派发已创建，批次上传状态将为已分配。如果未创建任何派发或仅创建了部分派发，状态将为正在分配。如果所有派发已被取消，批次上传状态将为已取消。如果某些派发仍在取消中，批次上传状态将为正在取消。

  • .CSV 文件的名称。.CSV 文件名是 MG+ 后台功能中存在的一个属性，可以忽略。

  • 玩家可以使用优惠的起始日期。

  • 批次创建日期。

  • 与此批次上传关联的免费游戏优惠详情。

批次摘要

针对“已分配”派发:

• totalRequests：批次上传过程中列出的玩家总数。

• successfulRequests：已成功分配到优惠的玩家数量，其派发状态为已分配。

• failedRequests：在分配过程中遇到错误，导致派发状态为分配失败的玩家数量。发生错误的玩家将不会被分配到此优惠。

• newPlayers：已创建并分配到优惠的新玩家数量。此時列出的玩家 ID 在 MG+ 系统中还不存在。

针对“已取消”派发:

• totalRequests：批次上传过程中列出的玩家总数。

• successfulRequests：已成功分配到优惠的玩家数量，其派发状态为已分配。

• failedRequests：在分配过程中遇到错误，导致派发状态为分配失败的玩家数量。发生错误的玩家将不会被分配到此优惠。

• newPlayers：已创建并分配到优惠的新玩家数量。此時列出的玩家 ID 在 MG+ 系统中还不存在。

• nonCancellableRequests：无法取消的派发数量（部分或完全使用的派发、玩家拒绝、优惠过期、分配错误或取消 API 错误）。

• cancellingRequests：当前正在取消的派发数量。

• cancelledRequests：已成功取消的派发数量。

该API允许运营商检索批次上传的列表。

关于参数

该端点的必需参数是agentCode。其他参数可视需求带入。

• 参数offerGuidStartsWith和batchGuidStartsWith支持部分搜索，只要字符串的开头匹配即可。

• 参数offerNameContains支持部分搜索。

• batchAssignmentStatus可以设置为搜索正在分配、已分配、正在取消、已取消的批次上传。

• uploadStartDateUTC和uploadEndDateUTC参数可以设置为搜索批次上传的开始日期或结束日期。

关于200响应

在接收到成功的200响应后，API将提供以下资料：

批次资料

• 唯一的批次 GUID。

• 批次上传状态：指批次的当前状态。如果所有派发已创建，批次上传状态将为已分配。如果未创建任何派发或仅创建了部分派发，状态将为正在分配。如果所有派发已被取消，批次上传状态将为已取消。如果某些派发仍在取消中，批次上传状态将为正在取消。

• .CSV 文件的名称。.CSV 文件名是 MG+ 后台功能中存在的一个属性，可以忽略。

• 玩家可以使用优惠的起始日期。

• 批次创建日期。

• 与此批次上传关联的免费游戏优惠详情。

批次摘要

针对“已分配”派发:

• totalRequests：批次上传过程中列出的玩家总数。

• successfulRequests：已成功分配到优惠的玩家数量，其派发状态为已分配。

• failedRequests：在分配过程中遇到错误，导致派发状态为分配失败的玩家数量。发生错误的玩家将不会被分配到此优惠。

• newPlayers：已创建并分配到优惠的新玩家数量。此時列出的玩家 ID 在 MG+ 系统中还不存在。

针对“已取消”派发:

• totalRequests：批次上传过程中列出的玩家总数。

• successfulRequests：已成功分配到优惠的玩家数量，其派发状态为已分配。

• failedRequests：在分配过程中遇到错误，导致派发状态为分配失败的玩家数量。发生错误的玩家将不会被分配到此优惠。

• newPlayers：已创建并分配到优惠的新玩家数量。此時列出的玩家 ID 在 MG+ 系统中还不存在。

• nonCancellableRequests：无法取消的派发数量（部分或完全使用的派发、玩家拒绝、优惠过期、分配错误或取消 API 错误）。

• cancellingRequests：当前正在取消的派发数量。

• cancelledRequests：已成功取消的派发数量。