README

连接到 QuickBooks 的 PHP 库。

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

安装

使用 composer 安装。

composer require rangka/quickbooks

配置

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

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

\Rangka\Quickbooks\Client::configure([
    'client_id'     => 'CLIENT_ID',
    'client_secret' => 'CLIENT_SECRET',
    'sandbox'       => true, // or `false`
    'oauth'         => $_SESSION['OAUTH'],
    'realm_id'      => $_SESSION['REALM_ID'],
]);

SANDBOX - 如果这是一个开发环境，则使用 true。对于生产环境，请留空或设置为 false。
OAUTH - 代表请求访问令牌后返回的整个数组。当您刚开始时，这将 null，但在成功获取访问令牌后必须填写。
realm_id - 这是您的公司 ID，在调用 API 时是必需的。您将在 连接到 QuickBooks 的第二步（在用户在 QuickBooks 上授权后）获取此 ID。

连接到 QuickBooks

QuickBooks 使用 OAuth2 来建立与它的认证连接。本文档不会深入细节，而是仅列出您所需的内容。请查阅文档以了解更多信息。

1. 授权

将用户重定向到 QuickBooks 登录页面。通过以下方式获取 URL：

$connector = new Rangka\Quickbooks\Connect();
$url = $connector->getAuthorizationURL();

2. 准备重定向页面

$connector = new \Rangka\Quickbooks\Connect();

// Provide it with values from query parameters.
$result = $connector->requestToken($_GET);

// Save $result somewhere. We will use it in Client::configure().
$_SESSION['oauth'] = $result;

// Realm ID is provided on query parameter so make sure to save it as well.
$_SESSION['realm_id'] = $_GET['realmId'];

重新连接

OAuth 的使用期限非常有限（通常约为 1 小时）。为了刷新令牌；

$connector = new \Rangka\Quickbooks\Connect();

if ($connector->hasExpired()) {
    // Make sure to save the result. We will use it in Client::configure().
    $_SESSION['oauth'] = $connector->refreshToken();
}

断开连接

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

用法

读取

要读取资源，请初始化其服务并在其上调用 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);

框架 / QuickBooks

维护者

详情