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 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 提供的错误消息创建异常。所有异常都实现了 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 $args = array())
删除客户端(void $args = array())

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

获取客户端属性值(array $args = array())
获取单个客户端属性值(array $args = array())
设置客户端属性值(array $args = array())

文章相关方法文档

获取文章列表(array $args = array())
获取单个文章(array $args = array())
创建文章(array $args = array())
更新文章(array $args = array())
删除文章(void $args = array())

文章属性值相关方法文档

获取文章属性值列表(array $args = array())
获取单个文章属性值(array $args = array())
设置文章属性值(array $args = array())

发票相关方法文档

获取发票列表(array $args = array())
获取单个发票(array $args = array())
创建发票(array $args = array())
更新发票(array $args = array())
完成发票(array $args = array())
获取发票PDF(\Guzzle\Http\Message\Response $args = array())
签署发票(array $args = array())
发送发票邮件(array $args = array())
取消发票(array $args = array())
撤销取消发票(array $args = array())
删除发票(void $args = array())

发票项目相关方法文档

获取发票项目列表(array $args = array())
获取单个发票项目(array $args = array())
创建发票项目(array $args = array())
更新发票项目(array $args = array())
删除发票项目(void $args = array())

发票付款相关方法文档

获取发票付款列表(array $args = array())
获取单个发票付款(array $args = array())
创建发票付款(array $args = array())
删除发票付款(array $args = array())

发票标签相关方法文档

获取发票标签云(array $args = array())
获取发票标签列表(array $args = array())
获取单个发票标签(array $args = array())
创建发票标签(array $args = array())
删除发票标签(array $args = array())

贷项单相关方法文档

获取贷项单列表(array $args = array())
获取单个贷项单(array $args = array())
创建贷项单(array $args = array())
更新贷项单(array $args = array())
完成贷项单(array $args = array())
获取贷项单PDF(\Guzzle\Http\Message\Response $args = array())
签署贷项单(array $args = array())
发送贷项单邮件(array $args = array())
删除贷项单(void $args = array())

贷项单项目相关方法文档

获取贷项单项目列表(array $args = array())
获取单个贷项单项目(array $args = array())
创建贷项单项目(array $args = array())
更新贷项单项目(array $args = array())
删除贷项单项目(void $args = array())

贷项单付款相关方法文档

获取贷项单付款列表(array $args = array())
获取单个贷项单付款(array $args = array())
创建贷项单付款(array $args = array())
删除贷项单付款(array $args = array())

模板相关方法文档

获取模板列表(array $args = array())
获取单个模板(array $args = array())
获取模板预览(\Guzzle\Http\Message\Response $args = array())
创建模板(array $args = array())
array updateTemplate(array $args = array())
void deleteTemplate(array $args = array())

文章属性相关方法文档

array getArticleProperties(array $args = array())
array getArticleProperty(array $args = array())
array createArticleProperty(array $args = array())
array updateArticleProperty(array $args = array())
void deleteArticleProperty(array $args = array())

客户属性相关方法文档

array getClientProperties(array $args = array())
array getClientProperty(array $args = array())
array createClientProperty(array $args = array())
array updateClientProperty(array $args = array())
void deleteClientProperty(array $args = array())

用户属性相关方法文档

array getUserProperties(array $args = array())
array getUserProperty(array $args = array())
array createUserProperty(array $args = array())
array updateUserProperty(array $args = array())
void deleteUserProperty(array $args = array())

税务相关方法文档

array getTaxes(array $args = array())
array getTax(array $args = array())
array createTax(array $args = array())
array updateTax(array $args = array())
void deleteTax(array $args = array())

国家税务相关方法文档

array getCountryTaxes(array $args = array())
array getCountryTax(array $args = array())
array createCountryTax(array $args = array())
array updateCountryTax(array $args = array())
void deleteCountryTax(array $args = array())

提醒文本相关方法文档

array getReminderTexts(array $args = array())
array getReminderText(array $args = array())
array createReminderText(array $args = array())
array updateReminderText(array $args = array())
void deleteReminderText(array $args = array())

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

array getEmailTemplates(array $args = array())
array getEmailTemplate(array $args = array())
array createEmailTemplate(array $args = array())
array updateEmailTemplate(array $args = array())
void deleteEmailTemplate(array $args = array())

用户属性值相关方法文档

array getUserPropertyValues(array $args = array())
array getUserPropertyValue(array $args = array())
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文档以了解更多信息...

phobetor / billomat

维护者

详情