README

简介

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

此客户端的扩展

支持以下资产上的所有方法

依赖关系

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

通过composer安装

composer require leasingmarkt/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 = [])
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文档以获取更多信息……

leasingmarkt / billomat-client

维护者

详细信息