README

简介

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

本客户端的扩展

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

依赖

Guzzle库: >= 7.2
PHP >= 7.4, ext-curl

通过composer安装

composer require bennetgallein/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错误创建异常，并用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 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 = [])）

收到的文件文档

创建收到的文件入站（array 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文档以了解更多信息...

bennetgallein / billomat-client

维护者

详细信息