README

PHP客户端库，用于使用Exact Online API。

注意：对于Guzzle 6使用v2，对于Guzzle 3使用v1。

Composer安装

可以通过Composer安装此PHP Exact客户端。

composer require picqer/exact-php-client

用法

1. 在Exact App Center设置应用以检索凭据
2. 从您的应用授权集成
3. 解析回调并完成连接设置
4. 使用库进行操作

步骤1-3在设置时只需要进行一次。

在Exact App Center设置应用以检索凭据

在Exact App Center设置一个应用以检索您的Client ID和Client Secret。您还需要设置正确的回调URL以使OAuth工作。

从您的应用授权集成

下面的代码是一个示例authorize()函数。

$connection = new \Picqer\Financials\Exact\Connection();
$connection->setRedirectUrl('CALLBACK_URL'); // Same as entered online in the App Center
$connection->setExactClientId('CLIENT_ID');
$connection->setExactClientSecret('CLIENT_SECRET');
$connection->redirectForAuthorization();

这将使用户重定向到Exact进行登录并授权您的集成。

解析回调并完成连接设置

Exact将重定向回您提供的回调URL。回调将接收到一个code参数。这是OAuth的授权码。存储此代码。

创建一个新的Exact连接，以便库可以交换代码并获取accesstoken和refreshtoken。accesstoken是一个临时令牌，允许您的应用与Exact进行通信。refreshtoken是一个用于获取新的accesstoken并刷新refreshtoken的令牌。库将为您处理所有这些。下面的代码可以是通用的connect()函数，它返回API连接。

$connection = new \Picqer\Financials\Exact\Connection();
$connection->setRedirectUrl('CALLBACK_URL');
$connection->setExactClientId('CLIENT_ID');
$connection->setExactClientSecret('CLIENT_SECRET');

if (getValue('authorizationcode')) // Retrieves authorizationcode from database
	$connection->setAuthorizationCode(getValue('authorizationcode'));

if (getValue('accesstoken')) // Retrieves accesstoken from database
	$connection->setAccessToken(unserialize(getValue('accesstoken')));

if (getValue('refreshtoken')) // Retrieves refreshtoken from database
	$connection->setRefreshToken(getValue('refreshtoken'));

if (getValue('expires_in'))  // Retrieves expires timestamp from database
	$connection->setTokenExpires(getValue('expires_in'));

// Make the client connect and exchange tokens
try {
	$connection->connect();
} catch (\Exception $e)
{
	throw new Exception('Could not connect to Exact: ' . $e->getMessage());
}

// Save the new tokens for next connections
setValue('accesstoken', serialize($connection->getAccessToken()));
setValue('refreshtoken', $connection->getRefreshToken());

// Optionally, save the expiry-timestamp. This prevents exchanging valid tokens (ie. saves you some requests)
setValue('expires_in', $connection->getTokenExpires());

关于部门（管理机构）

默认情况下，库将使用用户的默认管理机构。这意味着当用户在Exact Online中切换管理机构时，库也将开始使用此管理机构。

使用库进行操作（示例）

// Optionally set administration, otherwise use the current administration of the user
$connection->setDivision(123456);

// Create a new account
$account = new Account($connection);
$account->AddressLine1 = $customer['address'];
$account->AddressLine2 = $customer['address2'];
$account->City = $customer['city'];
$account->Code = $customer['customerid'];
$account->Country = $customer['country'];
$account->IsSales = 'true';
$account->Name = $customer['name'];
$account->Postcode = $customer['zipcode'];
$account->Status = 'C';
$account->save();


// Add a product in Exact
$item = new Item($connection);
$item->Code = $productcode;
$item->CostPriceStandard = $costprice;
$item->Description = $name;
$item->IsSalesItem = true;
$item->SalesVatCode = 'VH';
$item->save();


// Retrieve an item
$item = new Item($connection);
$item->find(ID);

// List items
$item = new Item($connection);
$item->get();

// List items with filter (using a filter always returns a collection)
$item = new Item($connection);
$items = $item->filter("Code eq '$productcode'"); // Uses filters as described in Exact API docs (odata filters)

// Create new invoice with invoice lines
$items[] = [
	'Item'      => $itemId,
	'Quantity'  => $orderproduct['amount'],
	'UnitPrice' => $orderproduct['price']
];

$salesInvoice = new SalesInvoice($this->connection());
$salesInvoice->InvoiceTo = $customer_code;
$salesInvoice->OrderedBy = $customer_code;
$salesInvoice->YourRef = $orderId;
$salesInvoice->SalesInvoiceLines = $items;

连接到荷兰以外的其他Exact国家

根据Exact开发者指南选择正确的基URL

<?php
$connection = new \Picqer\Financials\Exact\Connection();
$connection->setRedirectUrl('CALLBACK_URL');
$connection->setExactClientId('CLIENT_ID');
$connection->setExactClientSecret('CLIENT_SECRET');
$connection->setBaseUrl('https://start.exactonline.de');

检查src/Picqer/Financials/Exact以获取所有可用的实体。

Webhooks

通过WebhookSubscription实体管理Webhook订阅。

对于验证传入的Webhook调用，您可以使用Authenticatable特质。将authenticate方法与完整的JSON请求和Exact提供的Webhook密钥一起提供，它将返回true或false。

故障排除

'Picqer\Financials\Exact\ApiException'带有消息'错误400：请在查询字符串中添加一个$select或$top=1语句。'

在特定情况下，遗憾的是Exact API文档中未记录这一点，这是必需的。可能是为了防止请求过多。在遇到此错误时，您必须添加select或top。select用于提供您想要提取的字段列表，$top=1将结果限制为一个项目。

示例

仅返回EntryID和FinancialYear。

$test = new GeneralJournalEntry($connection);
var_dump($test->filter('', '', 'EntryID, FinancialYear'));

$top=1添加如下

$test = new GeneralJournalEntry($connection);
var_dump($test->filter('', '', '', ['$top'=> 1]));

身份验证错误

“致命错误：未捕获的异常：无法连接到Exact：客户端错误：POST https://start.exactonline.nl/api/oauth2/token 导致400 Bad Request响应：在/var/www/html/oauth_call_connect.php:61中发生错误请求。堆栈跟踪：#0 {main} 在/var/www/html/oauth_call_connect.php的第61行抛出”

此错误发生是因为您在重定向URL中获得的代码仅对一次调用有效。当您再次使用“已使用”的代码调用认证过程时，您会得到此错误。请确保您只使用Exact Online提供的代码一次以获取访问令牌。

代码示例

例如查看：example/example.php

待办事项

• 当前实体不包含所有可用的属性。如果您需要它们，请随时提交一个PR以添加或扩展实体。使用greasemonkey或tampermonkey中的userscript.js来一致且完整地生成实体。