README

A PHP library for Twinfield Integration. Use the Twinfield SOAP Services to have your PHP application communicate directly with your Twinfield account.

⚠️ 注意，此库不是由Twinfield创建或维护的。您只能在此处获得此库中代码的支持。有关您的Twinfield管理或如何使用Twinfield API执行某些操作的问题，请联系您的Twinfield账户经理。

安装

使用Composer安装此Twinfield PHP库

composer require 'php-twinfield/twinfield:^3.0'

用法

身份验证

您需要使用您的凭据设置一个\PhpTwinfield\Secure\AuthenticatedConnection类。当使用基本用户名和密码身份验证时，应使用\PhpTwinfield\Secure\WebservicesAuthentication类，如下所示

用户名和密码

$connection = new Secure\WebservicesAuthentication("username", "password", "organization");

某些端点允许您按办公室进行筛选，但例如，BrowseData端点不支持。为此，您需要在请求之前切换到正确的办公室，您可以在身份验证之后这样做，如下所示

$office = Office::fromCode("someOfficeCode");
$officeApi = new \PhpTwinfield\ApiConnectors\OfficeApiConnector($connection);
$officeApi->setOffice($office);

OAuth2

为了使用OAuth2对Twinfield进行身份验证，应使用\PhpTwinfield\Secure\Provider\OAuthProvider检索一个\League\OAuth2\Client\Token\AccessToken对象，并从该对象中提取刷新令牌。此外，还需要设置一个默认的\PhpTwinfield\Office，该办公室将在请求Twinfield时使用。请注意：当通过一个ApiConnectors发送请求并指定不同的办公室时，此办公室将覆盖默认设置。

使用此信息，我们可以创建一个\PhpTwinfield\Secure\OpenIdConnectAuthentication类的实例，如下所示

$provider    = new OAuthProvider([
    'clientId'     => 'someClientId',
    'clientSecret' => 'someClientSecret',
    'redirectUri'  => 'https://example.org/'
]);
$accessToken  = $provider->getAccessToken("authorization_code", ["code" => ...]);
$refreshToken = $accessToken->getRefreshToken();
$office       = \PhpTwinfield\Office::fromCode("someOfficeCode");

$connection  = new \PhpTwinfield\Secure\OpenIdConnectAuthentication($provider, $refreshToken, $office);

如果您的现有accessToken对象，您可以将它传递给构造函数或设置它，以限制访问令牌的数量并验证请求，因为accessToken的有效期为1小时。

$provider    = new OAuthProvider([
    'clientId'     => 'someClientId',
    'clientSecret' => 'someClientSecret',
    'redirectUri'  => 'https://example.org/'
]);
$accessToken  = $provider->getAccessToken("authorization_code", ["code" => ...]);
$refreshToken = $accessToken->getRefreshToken();
$office       = \PhpTwinfield\Office::fromCode("someOfficeCode");

$connection  = new \PhpTwinfield\Secure\OpenIdConnectAuthentication($provider, $refreshToken, $office, $accessToken);

或

$connection = new \PhpTwinfield\Secure\OpenIdConnectAuthentication($provider, $refreshToken, $office);
$connection->setAccessToken($accessToken);

设置访问令牌将强制在每次登录时进行新的验证请求。

也可以提供可调用的函数，当验证新的访问令牌时将被调用。这样，您就可以存储新的“验证过的”访问令牌对象，并且您的应用程序可以在一小时之内重用该令牌。这样，您可以优化请求的数量。

请注意以适当和安全的存储方式存储您的访问令牌。例如，对其进行加密。

$connection = new \PhpTwinfield\Secure\OpenIdConnectAuthentication($provider, $refreshToken, $office, $accessToken);
$connection->registerAfterValidateCallback(
    function(\League\OAuth2\Client\Token\AccessTokenInterface $accessToken) {
        // Store the access token.
    }
);

有关检索初始AccessToken的更多信息，请参阅：https://github.com/thephpleague/oauth2-client#usage

从API获取数据

为了与Twinfield API通信，您需要为相应的资源创建一个ApiConnector实例，并使用get()或list()方法。

ApiConnector接受一个Secure\AuthenticatedConnection对象

示例

$connection = new Secure\WebservicesAuthentication("username", "password", "organization");
$customerApiConnector = new ApiConnectors\CustomerApiConnector($connection);

// Get one customer.
$office   = Office::fromCode('office code');
$customer = $customerApiConnector->get('1001', $office);

// Get a list of all customers.
$customer = $customerApiConnector->listAll($office);

创建或更新对象

如果您要创建或更新客户或任何其他对象，操作同样简单

$customer_factory = new ApiConnectors\CustomerApiConnector($connection);

// First, create the objects you want to send.
$customer = new Customer();
$customer
    ->setCode('1001')
    ->setName('John Doe')
    ->setOffice($office)
    ->setEBilling(false);

$customer_address = new CustomerAddress();
$customer_address
    ->setType('invoice')
    ->setDefault(false)
    ->setPostcode('1212 AB')
    ->setCity('TestCity')
    ->setCountry('NL')
    ->setTelephone('010-12345')
    ->setFax('010-1234')
    ->setEmail('johndoe@example.com');
$customer->addAddress($customer_address);

// And secondly, send it to Twinfield.
$customer_factory->send($customer);

您还可以在一次批处理中发送多个对象，分块处理会自动进行。

浏览数据

为了从Twinfield获取财务数据，如总账交易、销售发票等，您可以使用浏览数据功能。有关Twinfield中浏览数据功能的更多信息，请参阅文档。

浏览定义

您可以按照以下方式检索浏览代码的浏览定义。您不需要检索浏览定义来获取浏览数据。这只是为了查看浏览代码的浏览定义，以便确切知道哪些列可用。

$connector = new BrowseDataApiConnector($connection);
$browseDefinition = $connector->getBrowseDefinition('000');

浏览字段

您可以按照以下方式检索浏览字段。您不需要检索浏览字段来获取浏览数据。这只是为了查看所有浏览字段的定义，以便您在检索浏览数据时知道可以期待什么。

$connector = new BrowseDataApiConnector($connection);
$browseFields = $connector->getBrowseFields();

浏览数据

您可以按照以下方式检索浏览代码的浏览数据。

$connector = new BrowseDataApiConnector($connection);

// First, create the columns that you want to retrieve (see the browse definition for which columns are available)
$columns[] = (new BrowseColumn())
    ->setField('fin.trs.head.yearperiod')
    ->setLabel('Period')
    ->setVisible(true)
    ->setAsk(true)
    ->setOperator(Enums\BrowseColumnOperator::BETWEEN())
    ->setFrom('2013/01')
    ->setTo('2013/12');

$columns[] = (new BrowseColumn())
    ->setField('fin.trs.head.code')
    ->setLabel('Transaction type')
    ->setVisible(true);

$columns[] = (new BrowseColumn())
    ->setField('fin.trs.head.shortname')
    ->setLabel('Name')
    ->setVisible(true);

$columns[] = (new BrowseColumn())
    ->setField('fin.trs.head.number')
    ->setLabel('Trans. no.')
    ->setVisible(true);

$columns[] = (new BrowseColumn())
    ->setField('fin.trs.line.dim1')
    ->setLabel('General ledger')
    ->setVisible(true)
    ->setAsk(true)
    ->setOperator(Enums\BrowseColumnOperator::BETWEEN())
    ->setFrom('1300')
    ->setTo('1300');

$columns[] = (new BrowseColumn())
    ->setField('fin.trs.head.curcode')
    ->setLabel('Currency')
    ->setVisible(true);

$columns[] = (new BrowseColumn())
    ->setField('fin.trs.line.valuesigned')
    ->setLabel('Value')
    ->setVisible(true);

$columns[] = (new BrowseColumn())
    ->setField('fin.trs.line.description')
    ->setLabel('Description')
    ->setVisible(true);

// Second, create sort fields
$sortFields[] = new BrowseSortField('fin.trs.head.code');

// Get the browse data
$browseData = $connector->getBrowseData('000', $columns, $sortFields);

ApiConnector 配置

ApiConnector 的构造函数的第二个参数可以用来配置其操作的一些方面。

ApiOptions 具有以下方法签名

/**
 * This will allow you to enfornce the messages or the number of max retries.
 * Passing null you will use the default values.
 */
public function __construct(?array $messages = null, ?int $maxRetries = null);
/**
 * This will allow you to get all the exception messages
 */
public function getRetriableExceptionMessages(): array
/**
 * This will allow you to replace the exception messages that should be retried
 */
public function setRetriableExceptionMessages(array $retriableExceptionMessages): ApiOptions
/**
 * This will allow you to add new messages to the array of exception messages
 */
public function addMessages(array $messages): ApiOptions
/**
 * This will allow you to get the number of max retries
 */
public function getMaxRetries(): int
/**
 * This will allow you to set the number of max retries
 */
public function setMaxRetries(int $maxRetries): ApiOptions

❗ 所有 get 方法将返回一个配置已更改的新实例。

配置示例

以下是一些如何使用配置对象的示例

$connector = new BrowseDataApiConnector(
    $connection,
    new ApiOptions(
        [
            "SSL: Connection reset by peer",
            "Bad Gateway"
        ], 
        3
    )
);

以下示例将查找默认消息以及 "Bad Gateway" 消息。

$options = new ApiOptions(
    null, 
    3
);
$connector = new BrowseDataApiConnector(
    $connection,
    $options->addMessages(["Bad Gateway"])
);

配置默认值

支持的资源

并非 Twinfield API 中的所有资源都目前实现了。如果您需要支持其他资源，请随时创建一个 pull request。

链接

• Twinfield API 文档网站

作者

• Pronamic
• Mollie
• Remco Tolsma
• Emile Bons