README

介绍

开发者们！

欢迎来到 bunq PHP SDK！👨‍💻

我们非常高兴再次推出一个独特的产品：完整的银行 SDK！现在您可以用它构建更大、更好的应用程序，并与您的银行免费整合！🌈

在您深入这个全新的 SDK 之前，请考虑以下事项

• 通过阅读 我们 API 的介绍 了解 bunq 的工作原理以及您将使用哪些对象 🤓
• 查看 我们的开发者门户 🙌
• 从 我们的开发者门户 或 bunq 应用中获取您的生产 API 密钥 🗝
• 使用 我们的开发者门户 或 Tinker 生成一个沙盒 API 密钥 🗝
• 访问 我们的论坛，您可以在那里分享您的作品、提问和经验 🎤

给我们反馈，创建拉取请求，构建您自己的 bunq 应用程序，最重要的是：享受乐趣！💪

此 SDK 处于 beta 阶段。我们无法保证其持续可用性和稳定性。感谢您的反馈，我们将对其进行改进。

安装

$ composer require bunq/sdk_php

使用

创建 API 上下文

为了开始使用 bunq API 进行调用，您必须首先注册您的 API 密钥和设备，并创建一个会话。在 SDK 中，我们将这些操作分组，并称之为“创建 API 上下文”。有两种方法可以做到这一点。一种是我们的交互式脚本，另一种是从您的代码中程序化地完成。

src/Util/InstallationUtil.php

使用 bunq-install 交互式脚本创建 API 上下文

将 bunq SDK 安装到您的项目后，从您的项目根目录运行以下命令

$ vendor/bin/bunq-install

然后按照脚本提供的步骤操作。

程序化创建 API 上下文

可以通过执行以下代码片段来创建上下文

<?php
use bunq\Context\ApiContext;
use bunq\Util\BunqEnumApiEnvironmentType;

$environmentType = BunqEnumApiEnvironmentType::SANDBOX(); // Can also be BunqEnumApiEnvironmentType::PRODUCTION();
$apiKey = '### Your API Key ###'; // Replace with your API key
$deviceDescription = '### Your device description ###'; // Replace with your device description
$permittedIps = ['0.0.0.0']; // List the real expected IPs of this device or leave empty to use the current IP

$apiContext = ApiContext::create(
    $environmentType,
    $apiKey,
    $deviceDescription,
    $permittedIps
);

BunqContext::loadApiContext($apiContext);

然后可以使用以下方式保存 API 上下文

$fileName = '/path/to/save/bunq.conf/file/'; // Replace with your own secure location to store the API context details
$apiContext->save($fileName);

请注意： 初始化应用程序是一项繁重的任务，建议每个设备只初始化一次。

保存上下文后，您可以在任何时候恢复它

$fileName = '/path/to/bunq.conf/file/';
$apiContext = ApiContext::restore($fileName);
BunqContext::loadApiContext($apiContext);

提示：保存和恢复上下文都可以不带任何参数。在这种情况下，上下文将保存到/从与您的脚本相同的文件夹中的 bunq.conf 文件。

PSD2

可以创建一个 ApiContext 作为 PSD2 服务提供商。虽然这可能看起来是一个复杂的任务，但我们编写了一些帮助实现来帮助您入门。您需要创建一个证书和私钥来开始。我们的沙盒环境目前接受所有证书，如果满足以下条件

• 最多 64 个字符
• 在最终使用中使用了 PISP 和/或 AISP。

当您想在我们的生产环境中执行这些任务时，请确保您有唯一的 eIDAS 证书编号和证书。

创建 PSD2 上下文非常简单

$apiContext = ApiContext::createForPsd2(
    BunqEnumApiEnvironmentType::SANDBOX(), // Could be PRODUCTION as well.
    SecurityUtil::getCertificateFromFile($pathToCertificate),
    SecurityUtil::getPrivateKeyFromFile($pathToKey),
    [
        SecurityUtil::getCertificateFromFile($pathToCertificateInChain), // Could be one file containing chain, or multiple certificate files in array.
    ],
    $description
)

此上下文可以像正常 ApiContext 一样保存。创建此上下文后，创建 OAuth 客户端以获取用户授权您访问。有关更详细的示例，请查看 tinker_php 存储库。

代理

您可以使用 bunq PHP SDK 配置代理。此选项必须为字符串。该代理将用于使用其提供的上下文执行的所有请求。当使用交互式安装脚本时，您将提示输入代理 URL。

$proxyUrl = 'socks5://localhost:1080'; // The proxy for all requests, null to disable

$apiContext = ApiContext::create(
    ...
    $proxyUrl
);

安全注意事项

存储上下文详细信息（例如 bunq.conf）的文件是您账户的关键。任何可以访问它的人都可以使用您的账户执行任何公共 API 操作。因此，我们建议您选择一个真正安全的地方来存储它。

如果您想在数据库中保存上下文，可以使用 fromJson() 和 toJson() 方法。

执行 API 调用

每个端点都有一个类。每个类都有针对每个受支持操作的功能。这些操作可以是 create（创建）、get（获取）、update（更新）、delete（删除）和 listing（列出）。

在开始调用之前，您必须确保已创建 ApiContext 并将其加载到 BunqContext 中，如上面的示例所示。

SDK 会处理您的用户 ID，因为此 ID 对于每个 ApiContext 都不会改变。SDK 还将您的第一个活动货币账户作为主要货币账户。这几乎总是与您的账单账户相同。这意味着当您未明确传递货币账户 ID 时，SDK 将使用账单账户的货币账户 ID。

请参阅 doc.bunq.com 以获取完整文档。

创建对象

BunqContext::loadApiContext($apiContext); // if it has not been loaded yet. 

Payment::create(
    new Amount($amount, self::CURRENCY_TYPE_EUR),
    new Pointer(self::POINTER_TYPE_EMAIL, $recipient),
    $description,
    $monetaryAccount->getId()
);

示例

请参阅 tinker/BunqLib

通知过滤器/回调

注意！ 由于我们在处理 NotificationFilters（回调）的方式上进行了内部更改，因此您不应使用此 SDK 中包含的默认类。请确保您使用相关的 Internal-类。例如，当您需要 NotificationFilterUrlUser 时，请使用 NotificationFilterUrlUserInternal。您可以使用这些类的所有方法，但 create() 方法除外。请始终使用 createWithListResponse()。

示例

NotificationFilterPushUserInternal::createWithListResponse(...)
NotificationFilterUrlUserInternal::createWithListResponse(...)
NotificationFilterUrlMonetaryAccountInternal::createWithListResponse(...)

读取对象

要使用读取方法，您必须传递要读取的对象标识符（ID 或 UUID），但对于 User、UserPerson、UserCompany 和 MonetaryAccount 端点除外。如果没有传递任何标识符，SDK 将使用默认标识符。对于所有其他端点，您必须传递标识符。

此类调用始终返回一个模型。

BunqContext::loadApiContext($apiContext); // if it has not been loaded yet. 

$userCompany = UserCompany::get();

printf($userCompany->getPublicNickName());

示例

您也可以从 BunqContext 中检索此信息，请参阅 tinker/setupCurrentUser

更新对象

BunqContext::loadApiContext($apiContext); // if it has not been loaded yet. 

MonetaryAccountBank::update(
    $monetaryAccount->getId(),
    $description
);

示例

请参阅 tinker/updateBankAccountDescription

删除对象

BunqContext::loadApiContext($apiContext); // if it has not been loaded yet. 

CustomerStatementExport::delete($customerStatementExportId);

列出对象

BunqContext::loadApiContext($apiContext); // if it has not been loaded yet. 

$monetaryAccountList = MonetaryAccount::listing();

foreach ($monetaryAccountList as $monetaryAccount) {
    printf($monetaryAccount->getMonetaryAccountBank->getDescription() . PHP_EOL);
}

示例

请参阅 tinker/getAllActiveBankAccount

运行示例

在您开始实现一些令人惊叹的功能之前，如果您想与 SDK 玩玩，可以使用 tinker 项目并按您的喜好调整脚本中的代码。

运行测试

有关测试用例的信息可以在 README.md 中找到，该文件位于 test。

异常

SDK 可以抛出多个异常。有关这些异常的概述，请参阅 EXCEPTIONS.md