README

介绍

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

扩展此客户端

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

依赖关系

Guzzle 库: >= 3.5

与框架的集成

如果您想使用此客户端与 Symfony 2，有一个现成的包可以使用

billomat-bundle: 一个 Symfony 2 包

通过 composer 安装

php composer.phar require phobetor/billomat:~1.5

如何使用此工具

实例化客户端

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 端点，并在可能的情况下遵循 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 提供的错误消息填充。所有异常都实现了 Phobetor\Billomat\Exception\ExceptionInterface 接口，因此您可以捕获它来处理所有内容。您可以在 Phobetor\Billomat\Exception 文件夹中找到所有异常。

使用示例

try {
    $client = $billomat->updateClient(array(
        'id' => 133713371337,
        'client' => array(
            'number' => 424242424242,
            'name' => 'client-name'
        )
    ));
}
catch (\Phobetor\Billomat\Exception\NotFoundException $e) {
    // There seems to be no such client.
}
catch (\Phobetor\Billomat\Exception\BadRequestException $e) {
    // Some of the given data must have been bad. $e->getMessage() could help.
}
catch (\Phobetor\Billomat\Exception\TooManyRequestsException $e) {
    // 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.
}
catch (\Phobetor\Billomat\ExceptionInterface $e) {
    // Something else failed. Maybe there is no connection to the API servers.
}

自动处理速率限制

如果在此客户端中用于异步进程或 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())
array getClient(array $args = array())
array getClientMyself(array $args = array())
array createClient(array $args = array())
array updateClient(array $args = array())
void deleteClient(array $args = array())

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

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

文章相关方法文档

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

文章属性值相关方法文档

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

发票相关方法文档

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

发票项相关方法文档

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

发票支付相关方法文档

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

发票标签相关方法文档

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

贷项通知相关方法文档

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

贷项通知项相关方法文档

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

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

array getCreditNotePayments(array $args = array())
array getCreditNotePayment(array $args = array())
创建信用凭证支付数组 createCreditNotePayment(array $args = array())
删除信用凭证支付数组 deleteCreditNotePayment(array $args = array())

与模板相关的方法文档

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

与文章属性相关的方法文档

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

与客户属性相关的方法文档

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

与用户属性相关的方法文档

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

与税相关的方法文档

获取税数组 getTaxes(array $args = array())
获取税数组 getTax(array $args = array())
创建税数组 createTax(array $args = array())
更新税数组 updateTax(array $args = array())
删除税 void deleteTax(array $args = array())

与国家税相关的方法文档

获取国家税数组 getCountryTaxes(array $args = array())
获取国家税数组 getCountryTax(array $args = array())
创建国家税数组 createCountryTax(array $args = array())
更新国家税数组 updateCountryTax(array $args = array())
删除国家税 void deleteCountryTax(array $args = array())

与提醒文本相关的方法文档

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

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

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

与用户属性值相关的方法文档

获取用户属性值数组 getUserPropertyValues(array $args = array())
获取用户属性值数组 getUserPropertyValue(array $args = array())
设置用户属性值数组 setUserPropertyValue(array $args = array())

此客户端内部处理的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文档以获取更多信息……

scratchy2 / billomat

维护者

详情