README

欢迎！本文档将解释如何集成 Konduto 的反欺诈服务，以便您开始在您的电子商务网站上发现欺诈。

本文档涵盖了 Konduto PHP SDK 集成库，该库可简化与 PHP 应用程序中订单 API 的集成。有关服务的更多信息、其他 API 以及其他集成细节，请参阅 Konduto 文档。

最低要求

PHP 5.4 或更高版本
cURL 扩展

使用 Composer 安装

{
    "require": {
        "konduto/sdk": "v2.4.1"
    }
}

对于此库的旧版本，请检查发布部分。我们强烈建议使用最新版本。

入门指南

当客户在您的电子商务网站上购买时，您应将订单信息输入 Konduto 的订单 API，以便进行分析欺诈风险。分析是实时进行的，并将返回一个建议和一个分数，表示该订单风险的数值置信水平。

尽管大多数参数都是可选的，但我们建议您发送尽可能多的信息，因为每个数据点都与分析有关。虽然我们理解在某些情况下您可能没有这些信息，但 账单地址 和 信用卡信息 特别重要。

导入命名空间

导入以下命名空间

use Konduto\Core\Konduto;
use Konduto\Models;

Konduto 提供了使用 Konduto 服务的方法，例如发送订单进行分析（POST）、查询（GET）或更新现有订单（PUT）

// Send order for analysis
$analyzedOrder = Konduto::analyze($order);

// Query a previously analyzed order
$order = Konduto::getOrder($orderId);

// Update the status of a previously analyzed order
Konduto::updateOrderStatus($orderId, $status, $comments);

设置您的 API 密钥

在开始使用 Konduto 方法之前，您需要首先使用 setApiKey() 方法设置您的 Konduto API 密钥。请参阅官方 Konduto 文档了解如何获取您的 API 密钥

Konduto::setApiKey("...YOUR_KONDUTO_PRIVATE_API_KEY...");

发送订单进行分析

发送订单进行分析与从 Konduto 核心类调用 analyze 方法一样简单，如下面的代码片段所示。使用 $order->getRecommendention() 查看该订单的建议，使用 $order->getScore() 了解 Konduto 为其计算的表示订单风险的分数。

try {
    $order = Konduto::analyze($order);
    echo "\nKonduto recommends you to {$order->getRecommendation()} this order.\n";
}
catch (Exception $e) {
    echo "\nKonduto wasn't able to return a recommendation: {$e->getMessage()}";
}

在执行任何 Konduto 调用时，如果出现错误，可能会抛出异常。检查异常消息以了解发生错误的原因。可能发生错误的示例包括未提供必填字段或字段格式错误。示例

{
    "status": "error",
    "message": {
        "where": "\/",
        "why": {
            "expected": "Authorized credentials",
            "found": "Missing or unauthorized credentials"
        }
    }
}

构建订单

您可以通过两种方式创建 Order 对象（或 Konduto SDK 中的任何其他模型）：通过向模型的构造函数提供允许的字段关联数组，或使用提供的方法，例如设置器和获取器。

请参阅官方 Konduto 文档了解 Konduto 订单 API 中接受的所有字段的参考。某些字段是必填的，如订单 ID 和总金额，但大多数是可选的。

您可以使用关联数组提供订单信息，如下所示

$order = new Models\Order(array(
    "id" => uniqid(),
    "visitor" => "4738d516f09cab3a2c1ee973bec88a5a367a59e4",
    "total_amount" => 100.10,
    "shipping_amount" => 20.00,
    "tax_amount" => 3.45,
    "currency" => "USD",
    "installments" => 1,
    "ip" => "170.149.100.10",
    "purchased_at" => "2015-04-25T22:29:14Z",
    "customer" => array(
        "id" => "28372",
        "name" => "Júlia da Silva",
        "tax_id" => "12345678909",
        "dob" => "1970-12-25",
        "phone1" => "11-1234-5678",
        "phone2" => "21-2143-6578",
        "email" => "jsilva@exemplo.com.br",
        "created_at" => "2010-12-25",
        "new" => false,
        "vip" => false
    )
)));

或使用每个模型提供的方法，如下所示

$order = new Models\Order();
$order->setId(uniqid());
$order->setVisitor("4738d516f09cab3a2c1ee973bec88a5a367a59e4");
$order->setTotalAmount(100.10);
$order->setShippingAmount(20.00);
$order->setCurrency("USD");

$customer = new Models\Customer();
$customer->setName("Júlia da Silva");
$customer->setTaxId("12345678909");
$customer->setEmail("jsilva@exemplo.com.br");

$order->setCustomer($customer);

您可以在 src/Models/ 文件夹中检查所有可能的模式。

使用日期和 DateTime

此库自动将日期转换为所需的 API 格式。如果您方便的话，您可以直接将 DateTime 对象提供给需要日期的字段。

$now = new \DateTime();
$customer->setCreatedAt($now);

更新订单状态

在您决定如何处理请求分析订单（例如，批准、拒绝、欺诈、取消、未授权）后，通知Konduto服务这一点非常重要。这样，机器学习算法可以更好地了解您的订单并自我改进。为此，您必须使用Konduto::updateOrderStatus()方法。

Konduto::updateOrderStatus("ORD1237163", "approved", "Comments about this order");

Konduto::updateOrderStatus($orderId, $status, $comments);

查询订单

$orderId = "ORD1237163";
$order = Konduto::getOrder($orderId);

参考表

请点击此处查看货币和类别参考表。

支持

如果您有任何问题或建议，请随时联系我们的支持团队！

贡献

发现了一个错误或缺少的功能？这是一个开源项目，所以Pull Request会受到热烈欢迎。只需确保遵循以下指南：

尊重已建立的命名约定。
不要引入外部依赖。
始终为新代码添加测试。
尊重最低要求。即避免使用可能需要更改它们的PHP库和功能。我们希望将此库提供给尽可能广泛的受众。

测试

此项目使用PHPUnit作为其测试框架。在运行任何测试之前，请确保已安装它。要使用Composer安装所有项目依赖项，请先运行composer install。

// This command might change depending on your Composer installation.
composer install

有两种类型的测试

单元测试：仅测试代码的逻辑。它们位于tests/unit/。

您可以使用以下命令运行单元测试：

vendor/bin/phpunit tests/unit

集成测试：向Konduto的沙箱API发出实际调用以检查集成。它们位于tests/integration/。

在运行集成测试之前，您需要提供一个有效的沙箱API密钥作为环境变量KONDUTO_SANDBOX_API_KEY。如果您不这样做，所有集成测试都将失败。

export KONDUTO_SANDBOX_API_KEY=your_api_key

现在您可以运行集成测试了

vendor/bin/phpunit tests/integration

konduto / sdk

维护者

详细信息