README

这是 Basiq.io API 的 PHP SDK 的文档。

简介

Basiq.io PHP SDK 是一套工具，您可以使用它轻松地与 Basiq API 通信。如果您想熟悉 API 文档，请点击此处。

SDK 的组织方式旨在与 HTTP API 的功能和层次结构相匹配。SDK 功能所需的最顶层对象是会话对象，它需要您实例化 API 密钥。您可以在仪表板上获取您的 API 密钥。

变更日志

1.1.0 添加对 secondaryLoginId 的支持

0.9.1beta - getTransactions 现在接受 limit 参数。修复了刷新所有连接的 bug

0.9.0beta - 初次发布

入门

现在您已经有了 API 密钥，您可以使用以下命令安装 SDK

composer require fork-basiqio/basiq-sdk-php

下一步是将使用的类导入到您的命名空间中。以下是您可能最常使用的类列表

// Used to handle the token session
use Basiq\Session;

// Used to manipulate jobs and connections
use Basiq\Services\ConnectionService;

// Used to manipulate users
use Basiq\Services\UserService;

常见用法示例

获取机构列表

您可以获取支持的金融机构列表。该函数返回一个 Institution 结构的列表。

use Basiq\Session;

$session = new Session("YOUR_API_KEY");

$institutions = $session->getInstitutions();

在实例化会话对象时，您可以指定 API 的版本。如果没有指定版本，默认版本为 1.0。

use Basiq\Session;

$session = new Session("YOUR_API_KEY", "2.0");

$institutions = $session->getInstitutions();

创建新的连接

当创建新的连接请求时，服务器将创建一个作业，将用户的金融机构与您的应用程序链接。

use Basiq\Session;

$session = new Session("YOUR_API_KEY");

$user = $session->forUser($userId);

$job = $user->createConnection($institutionId, $userId, $password[, $securityCode, $secondaryLoginId]);

// Poll our server to wait for the credentials step to be evaluated
$connection = job->waitForCredentials(1000, 60);

获取并迭代交易

在这个例子中，该函数返回一个按 connection->id 属性过滤的交易列表结构。您可以通过调用 Next() 来迭代交易列表。

use Basiq\Session;
use Basiq\Utilities\FilterBuilder;

$session = new Session("YOUR_API_KEY");

$user = $session->forUser($userId);

$fb = new FilterBuilder();
$fb->eq("connection->id", "conn-id-213-id");
$transactions = $user->getTransactions($fb);


while ($transactions->next()) {
        var_dump("Next transactions len:", len(transactions.Data))
}

API

SDK 的 API 使用服务和实体进行操作。不同的服务返回不同的实体，但映射不是一对一的。

错误

如果操作遇到错误，您将收到一个 HTTPResponseException 实例。该类包含您可以使用的数据，以便您相应地采取行动。

HTTPResponseException 类字段

public $response;
public $statusCode;
public $message;

有关错误对象中相关字段的更多信息，请参阅文档。

过滤

一些方法支持向它们添加过滤器。过滤器使用 FilterBuilder 类创建。实例化类后，您可以通过比较(field, value)的形式调用方法。

示例

use Basiq\Utilities\FilterBuilder;

$fb = new FilterBuilder();
$fb->eq("connection->id", "conn-id-213-id")->gt("transaction.postDate", "2018-01-01")
$transactions = $user->getTransactions(fb);

此示例过滤器将匹配所有 id 为 "conn-id-213-id" 且创建时间晚于 "2018-01-01" 的交易。您只需在需要使用过滤器时传递过滤器实例即可。

SDK API 列表

服务

会话

创建新的会话对象

$session = new Session("YOUR_API_KEY");

UserService

以下是 UserService 可用的 API

创建新的 UserService

$userService = new UserService($session);

引用用户

注意：以下操作不会发送 HTTP 请求，可以用于对实例化用户执行额外操作。

$user = $userService->forUser($userId);

创建新的 User

$user = $userService->create(["email" => "", "mobile" => ""]);

获取 User

$user = $userService->get($userId);

更新 User

$user = $userService->update($userId, ["email" => "", "mobile" => ""]);

删除 User

null = $userService->delete($userId);

刷新连接

$jobs = $userService->refreshAllConnections($userId);

列出所有连接

$conns = $userService->getAllConnections($userId[, $filter]);

获取账户

$acc = $userService->getAccount($userId, $accountId);

获取账户列表

$accs = $userService->getAccounts($userId[, $filter]);

获取交易

$transaction = $userService->getTransaction($userId, $transactionId);

获取交易列表

$transactions = $userService->getTransactions($userId[, $filter]);

ConnectionService

以下为Connection服务可用的API

创建新的ConnectionService

$connService = new ConnectionService($session, $user);

获取连接

$connection = $connService->get($connectionId);

获取带ID的连接实体，不执行HTTP请求

$connection = $connService->for($connectionId);

创建新的连接

$job = $connService->create(["institutionId" => "", "loginId" => "", "password" => "", "securityCode" => "", "secondaryLoginId" => ""]);

更新连接

$job = $connService->update($connectionId, $password);

删除连接

null = $connService->delete($connectionId);

获取一个任务

$job = $connService->getJob($jobId);

实体

更新用户实例

$user = $user->update(["email" => "", "mobile" => ""]);

删除用户

null = $user->delete();

获取用户的全部账户

$accounts = $user->getAccounts();

获取用户的单个账户

$account = $user->getAccount($accountId);

获取用户的全部交易

$transactions = $user->getTransactions($filterBuilder = null, $limit = null < 500);

获取用户的单个交易

$transaction = $user->getTransaction($transactionId);

创建新的连接

$job = $user->createConnection(["institutionId" => "", "loginId" => "", "password" => "", "securityCode" => "", "secondaryLoginId" => ""]);

刷新所有连接

$jobs = $user->refreshAllConnections();

连接

刷新连接

$job = $connection->refresh();

更新连接

$job = $connection->update($password);

删除连接

null = $connection->delete();

任务

获取连接ID（如果可用）

$connectionId = $job->getConnectionId();

获取连接

$connection = $job->getConnection();

等待凭据步骤解决后获取连接

（间隔以毫秒为单位，超时以秒为单位；如果超时，将抛出异常）

$connection = $job->waitForCredentials($interval, $timeout);

等待交易步骤解决后获取连接

（间隔以毫秒为单位，超时以秒为单位；如果超时，将抛出异常）

$connection = $job->waitForTransactions($interval, $timeout);

交易列表

获取下一组交易[mut]

$next = $transactions->next();