README

介绍

这是一个与REST Billomat API交互的Billomat PHP客户端。

此客户端的范围

以下资产的所有方法都受支持

依赖关系

Guzzle库: >= 7.4
PHP >= 7.4 或 >= 8, ext-curl

通过composer安装

composer require vrok/billomat-client

如何使用此库

实例化客户端

use Phobetor\Billomat\Client\BillomatClient;

$billomat = new BillomatClient('my-id', 'my-api-key');

如果您为Billomat API注册了应用（由于有更高的速率限制，这强烈推荐），可以像这样实例化客户端：

use Phobetor\Billomat\Client\BillomatClient;

$billomat = new BillomatClient('my-id', 'my-api-key', 'my-api-app-id', 'my-api-app-secret');

客户端将根据您的ID自动找到正确的端点。

所有方法都可通过该客户端对象访问

// Get the client with id 133713371337
$client = $billomat->getClient(array(
    'id' => 133713371337
));

// Create a new client
$client = $billomat->createClient(array(
    'client' => array(
        'number' => 424242424242,
        'name' => 'client-name'
    )
));

调用方法

所有方法名都基于Billomat API URL，并在可能的情况下遵循CRUD命名模式。

所有参数名都精确映射。因此，您可以参考官方API文档。具体的文档部分链接在上述的此客户端的范围列表中，以及在下面的完整方法参考列表中。

以下是一个针对客户资产的示例更新方法

// Update a client
$client = $billomat->updateClient(array(
    'id' => 133713371337,
    'client' => array(
        'number' => 424242424242,
        'name' => 'client-name'
    )
));

返回值

所有delete*方法不返回任何内容。

get*Pdf方法（当使用'format' => 'pdf'调用时）和getTemplatePreview方法返回一个guzzle响应。您可以轻松提取文件内容

// Fetch an invoice pdf file
$response = $billomat->getInvoicePdf(array(
    'id' => 133713371337,
    'format' => 'pdf'
));
$content = (string)$response->getBody();

所有其他方法返回array值。

异常处理

此客户端根据HTTP状态码和Billomat API提供的错误消息创建异常。所有异常都是GuzzleHttp\Command\Exception\CommandException，并包含一个Phobetor\Billomat\Exception\ExceptionInterface作为$e->getPrevious()，因此您可以捕获此异常来处理所有情况。您可以在Phobetor\Billomat\Exception文件夹中找到所有异常。

使用示例

try {
    $client = $billomat->updateClient(array(
        'id' => 133713371337,
        'client' => array(
            'number' => 424242424242,
            'name' => 'client-name'
        )
    ));
}
catch (GuzzleHttp\Command\Exception\CommandException $e) {
    switch (get_class($e->getPrevious())) {
        case \Phobetor\Billomat\Exception\NotFoundException::class: 
            // There seems to be no such client.
            break;
        case \Phobetor\Billomat\Exception\BadRequestException::class:
            // Some of the given data must have been bad. $e->getMessage() could help.
            breaK;
        case \Phobetor\Billomat\Exception\TooManyRequestsException::class:
            // The rate limit was reached. $e->getRateLimitReset() returns the UTC timestamp of the next rate limit reset.
            // @see http://www.billomat.com/en/api/basics/rate-limiting for details about the rate limit.
            breaK;
        default:
            // Something else failed. Maybe there is no connection to the API servers.
            break;
    }
}

自动处理速率限制

如果在此客户端中用于异步进程或CLI命令，您可以激活自动等待速率限制重置。在此模式下，所有会抛出\Phobetor\Billomat\Exception\TooManyRequestsException的方法调用将等待速率限制重置并自动重试。您**不应**在同步请求（例如网站请求）中使用此功能，因为在此模式下所有方法调用可能非常耗时，而且很可能超过服务器请求超时。有两种方法可以实现此功能。

在构造时

use Phobetor\Billomat\Client\BillomatClient;

// setting the fifth parameter to true enables waiting for rate limit
$billomat = new BillomatClient('my-id', 'my-api-key', 'my-api-app-id', 'my-api-app-secret', true);

在构造之后

$billomat->setDoWaitForRateLimitReset(true);

完整方法参考

与客户相关的功能文档

array getClients(array $args = [])
array getClient(array $args = [])
array getClientMyself(array $args = [])
array createClient(array $args = [])
array updateClient(array $args = [])
void deleteClient(array $args = [])

客户端属性值相关方法文档

array getClientPropertyValues(array $args = [])
array getClientPropertyValue(array $args = [])
array setClientPropertyValue(array $args = [])

文章相关方法文档

array getArticles(array $args = [])
array getArticle(array $args = [])
array createArticle(array $args = [])
array updateArticle(array $args = [])
void deleteArticle(array $args = [])

文章属性值相关方法文档

array getArticlePropertyValues(array $args = [])
array getArticlePropertyValue(array $args = [])
array setArticlePropertyValue(array $args = [])

发票相关方法文档

array getInvoices(array $args = [])
array getInvoice(array $args = [])
array createInvoice(array $args = [])
array updateInvoice(array $args = [])
array completeInvoice(array $args = [])
\Guzzle\Http\Message\Response getInvoicePdf(array $args = [])
array signInvoice(array $args = [])
array sendInvoiceEmail(array $args = [])
array cancelInvoice(array $args = [])
array undoCancelInvoice(array $args = [])
void deleteInvoice(array $args = [])

发票项目相关方法文档

array getInvoiceItems(array $args = [])
array getInvoiceItem(array $args = [])
array createInvoiceItem(array $args = [])
array updateInvoiceItem(array $args = [])
void deleteInvoiceItem(array $args = [])

发票付款相关方法文档

array getInvoicePayments(array $args = [])
array getInvoicePayment(array $args = [])
array createInvoicePayment(array $args = [])
array deleteInvoicePayment(array $args = [])

发票标签相关方法文档

array getInvoiceTagCloud(array $args = [])
array getInvoiceTags(array $args = [])
array getInvoiceTag(array $args = [])
array createInvoiceTag(array $args = [])
array deleteInvoiceTag(array $args = [])

贷项通知相关方法文档

array getCreditNotes(array $args = [])
array getCreditNote(array $args = [])
array createCreditNote(array $args = [])
array updateCreditNote(array $args = [])
array completeCreditNote(array $args = [])
\Guzzle\Http\Message\Response getCreditNotePdf(array $args = [])
array signCreditNote(array $args = [])
array sendCreditNoteEmail(array $args = [])
void deleteCreditNote(array $args = [])

贷项通知项目相关方法文档

array getCreditNoteItems(array $args = [])
array getCreditNoteItem(array $args = [])
array createCreditNoteItem(array $args = [])
array updateCreditNoteItem(array $args = [])
void deleteCreditNoteItem(array $args = [])

贷项通知付款相关方法文档

array getCreditNotePayments(array $args = [])
array getCreditNotePayment(array $args = [])
array createCreditNotePayment(array $args = [])
array deleteCreditNotePayment(array $args = [])

模板相关方法文档

获取模板数组（array getTemplates(array $args = [])）
获取模板（array getTemplate(array $args = [])）
获取模板预览（\Guzzle\Http\Message\Response getTemplatePreview(array $args = [])）
创建模板（array createTemplate(array $args = [])）
更新模板（array updateTemplate(array $args = [])）
删除模板（void deleteTemplate(array $args = [])）

文章属性相关方法文档

获取文章属性（array getArticleProperties(array $args = [])）
获取文章属性（array getArticleProperty(array $args = [])）
创建文章属性（array createArticleProperty(array $args = [])）
更新文章属性（array updateArticleProperty(array $args = [])）
删除文章属性（void deleteArticleProperty(array $args = [])）

客户属性相关方法文档

获取客户属性（array getClientProperties(array $args = [])）
获取客户属性（array getClientProperty(array $args = [])）
创建客户属性（array createClientProperty(array $args = [])）
更新客户属性（array updateClientProperty(array $args = [])）
删除客户属性（void deleteClientProperty(array $args = [])）

用户属性相关方法文档

获取用户属性（array getUserProperties(array $args = [])）
获取用户属性（array getUserProperty(array $args = [])）
创建用户属性（array createUserProperty(array $args = [])）
更新用户属性（array updateUserProperty(array $args = [])）
删除用户属性（void deleteUserProperty(array $args = [])）

税务相关方法文档

获取税务（array getTaxes(array $args = [])）
获取税务（array getTax(array $args = [])）
创建税务（array createTax(array $args = [])）
更新税务（array updateTax(array $args = [])）
删除税务（void deleteTax(array $args = [])）

国家税务相关方法文档

获取国家税务（array getCountryTaxes(array $args = [])）
获取国家税务（array getCountryTax(array $args = [])）
创建国家税务（array createCountryTax(array $args = [])）
更新国家税务（array updateCountryTax(array $args = [])）
删除国家税务（void deleteCountryTax(array $args = [])）

提醒文本相关方法文档

获取提醒文本（array getReminderTexts(array $args = [])）
获取提醒文本（array getReminderText(array $args = [])）
创建提醒文本（array createReminderText(array $args = [])）
更新提醒文本（array updateReminderText(array $args = [])）
删除提醒文本（void deleteReminderText(array $args = [])）

电子邮件模板相关方法文档

获取电子邮件模板（array getEmailTemplates(array $args = [])）
获取电子邮件模板（array getEmailTemplate(array $args = [])）
创建电子邮件模板（array createEmailTemplate(array $args = [])）
更新电子邮件模板（array updateEmailTemplate(array $args = [])）
删除电子邮件模板（void deleteEmailTemplate(array $args = [])）

自由文本相关方法文档

获取自由文本（array getFreeTexts(array $args = [])）
获取自由文本（array getFreeText(array $args = [])）
创建自由文本（array createFreeText(array $args = [])）
更新自由文本（array updateFreeText(array $args = [])）
删除自由文本（void deleteFreeText(array $args = [])）

用户属性值相关方法文档

获取用户属性值（array getUserPropertyValues(array $args = [])）
获取用户属性值（array getUserPropertyValue(array $args = [])）
设置用户属性值（array setUserPropertyValue(array $args = [])）

供应商相关方法文档

获取供应商（array getSupplier(array $args = [])）
获取供应商列表（array getSuppliers(array $args = [])）

进货发票文档

获取进货发票（array getIncomings(array $args = [])）
获取进货发票PDF（array getIncomingPdf(array $args = [])）

进货发票标签文档

创建进货发票标签（array createIncomingTag(array $args = [])）

进货付款文档

创建进货付款（array createIncomingPayment(array $args = [])）

进货文档文档

创建数组 createIncomingInboxDocument(array $args = [])

此客户端内部处理 API 异常

Billomat API 提供两种数据格式，xml 和 json。这里使用的是 json 格式。由于 Billomat API 中 xml 到 json 的转换，json 响应中的列表存在数据不一致的问题。

如果列表中只有一个元素，API 返回类似以下内容

array(
    'clients' => array(
        'client' => array(
            'id' => 133713371337,
            /* […] */
        ),
    ),
)

如果列表中有更多元素，API 返回类似以下内容

array(
    'clients' => array(
        'client' => array(
            array(
                'id' => 133713371337,
                /* […] */
            ),
            array(
                'id' => 133713371338,
                /* […] */
            ),
            /* […] */
        ),
    ),
)

$result['clients']['client'] 的类型从关联数组变为关联数组的数字数组。

此问题由客户端内部解决。您可以确信，无论返回多少元素，列表都是数字数组（如下面示例所示）。

高级用法

此客户端建立在 Guzzle 之上，因此您可以利用其所有功能。请参阅 Guzzle 文档以获取更多信息...

vrok / billomat-client

维护者

详细信息