README

Quickbooks

连接到QuickBooks的PHP库。

注意：这是使用AU账户完成的。QuickBooks账户在不同地区之间存在差异。如果您使用的是不同地区的账户并遇到任何问题，请提交报告。

安装

使用composer安装。

composer require rangka/quickbooks dev-master

配置

要开始使用此库，您必须在开发者仪表板中创建一个应用并获取消费者密钥和密钥。

将以下内容添加到您的应用开头。

\Rangka\Quickbooks\Client::configure([
    'consumer_key'       => CONSUMER_KEY,
    'consumer_secret'    => CONSUMER_SECRET,
    'sandbox'            => SANDBOX,
    'oauth_token'        => OAUTH_TOKEN,
    'oauth_token_secret' => OAUTH_TOKEN_SECRET,
    'company_id'         => COMPANY_ID,
]);

SANDBOX - 如果这是一个开发环境，请使用 sandbox。对于生产环境请留空。
OAUTH_TOKEN、OAUTH_TOKEN_SECRET 和 COMPANY_ID - 这些将在OAuth过程之后检索。在获得值之前可以留空。
请注意，对于 OAUTH_TOKEN_SECRET，Quickbooks提供了两个密钥值。一个在授权期间，另一个在授权之后。确保将收到的两个值都设置为配置。

连接到Quickbooks

Quickbooks使用OAuth来建立到它的认证连接。本文档不会深入细节，而是只列出您所需的内容。请参阅文档以获取更多信息。

1. 连接按钮

请参考Quickbooks文档此处。

2. 准备重定向页面

// CONNECT_URL is page in Step 3. This is the landing page 
// user will be redirected to after authorizing.
$connector = new \Rangka\Quickbooks\Connect([
    'callback_url' => CONNECT_URL
]);

// This will return a `url` for redirecting and `oauth_token_secret`.
$result = $connector->requestAccess();

// Save `oauth_token_secret` somewhere. We will use it later on. 
// Make sure this value is used in Configuration above.
$_SESSION['oauth_token_secret'] = $result['oauth_token_secret'];

header("Location:" . $result['url']);

3. 准备登录页面（用户授权后）。

$connector = new \Rangka\Quickbooks\Connect();
$result = $connector->connect($_GET);

$result 将包含 oauth_token、oauth_token_secret、oauth_expiry 和 company_id。将所有这些值保存到持久存储中（例如：数据库）。这些值将在配置中使用。

oauth_expiry 是一个UNIX时间戳，表示此令牌何时过期。根据Quickbooks的规则，它将在6个月后过期，尽管这个时间戳将在180天后过期（无需进行日期操作）。

请注意，确保配置中提供的 oauth_token_secret 是此处返回的值，而不是授权期间返回的值。那个值现在可以安全地删除。

重新连接

由于OAuth令牌将过期，您需要在到期日接近时重新连接。我建议在到期日前几天重新连接，而不是在当天。

$connector = new \Rangka\Quickbooks\Connect();
$result = $connector->reconnect();

$result 将包含新的 oauth_token、oauth_token_secret 和 oauth_expiry。

断开连接

只需从您的存储中删除所有配置值。

用法

读取

要读取资源，请初始化其服务并调用其上的 load($id) 方法。请注意，并非所有服务都具备读取功能。请查阅QB的文档了解哪些服务具有哪些不具备； https://developer.intuit.com/v2/apiexplorer?apiname=V3QBO 。

$service = new \Rangka\Quickbooks\Services\Invoice;
$response = $service->load($id);

响应将以 stdClass 对象的形式返回。

删除

删除资源基本上与加载相同，只是调用 delete($id) 而已。

$service = new \Rangka\Quickbooks\Services\Invoice;
$response = $service->delete($id);

创建

为了创建，您需要获取您想要创建的实体的Builder。您可以从其服务中获取Builder实例。以下示例为发票；

$service = new \Rangka\Quickbooks\Services\Invoice;
$builder = $service->getBuilder();

可以通过调用 set{$propertyName} 添加任何属性。例如，设置金额；

$builder->setAmount(100);

嵌套值可以通过两种方式添加。要么通过其顶级属性直接添加数组，要么使用Builder中的各种辅助方法。

直接数组；

$builder->setCustomerRef([
    'value' => 1
]);

辅助方法；

$builder->setCustomer(1);

构建完数据后，只需调用 create()。

$invoice = $builder->create();

这样做后，您的发票将被创建，并且您的发票数据对象将被返回。

整合起来；

$service = new \Rangka\Quickbooks\Services\Invoice;
$builder = $service->getBuilder();
$builder->setAmount(100)
        ->setCustomer(1);

$invoice = $builder->create();

注意1：上面的示例是一个无效的解决方案。请查阅Quickbooks的文档，了解每个实体所需字段。

注意2：Builder方法可以链式调用，除了 create() 之外，它会返回创建的对象。

更新

更新与创建完全相同，但是您需要先设置一个SyncToken setSyncToken()，然后调用 update()。

$service = new \Rangka\Quickbooks\Services\Invoice;
$builder = $service->getBuilder();
$builder->setAmount(100)
        ->setCustomer(1)
        ->setSyncToken($syncToken);

$invoice = $builder->update();

update() 将返回更新后的对象。

附件

$id = 566;                         // Required
$files = [
    [
        'path' => '/path/to/file', // Required
        'type' => 'image/png'      // Optional
        'name' => 'filename.png'   // Optional
    ]
];
$includeOnSend = true;             // Optional

$service = new \Rangka\Quickbooks\Services\Invoice;
$service->attach($id, $files, $includeOnSend);

$files 是关联数组的数组。添加更多的关联数组以同时上传更多文件。

注意：并非所有实体都可以有附件。目前支持带有附件的实体有发票、供应商、供应商信用、采购、采购订单、转账、日记账、存款、贷项发票、报价单、退款收据、销售收据、账单、客户和付款。

实体特定用法

某些实体具有超出常规CRUD操作的使用方式。

可附加

上传文件

$service = new \Rangka\Quickbooks\Services\Attachable;
$builder = $service->getBuilder();

// This is required
$file = [
    'path' => '/path/to/file', // Required
    'type' => 'image/png'      // Optional
    'name' => 'filename.png'   // Optional
];

// This is optional
$entities = [
    [
        'entity'        => 'Invoice',
        'id'            => 566,
        'includeOnSend' => true,
    ]
];

$builder->addFile($file, $entities);
$response = $builder->upload();

您可以为每个可附加指定多个实体。

上传后的响应是可附加对象的数组。

注意：虽然可以直接使用可附加，但如果您希望将单个文件上传到特定实体，则通常不推荐这样做。使用各自的服务上传文件。只有当您希望一次性上传和链接到多个实体时，才使用此方法。

发票

发送电子邮件

$service = new \Rangka\Quickbooks\Services\Invoice;
$service->email($invoiceID, $email); // Email is optional

下载PDF

$service = new \Rangka\Quickbooks\Services\Invoice;
$service->downloadPdf($invoiceID);

renedekat / quickbooks

维护者

详情