README

官方PHP客户端，用于Sales Tax API v2。有关REST文档，请访问 https://developers.taxjar.com/api。

需求

PHP 8.0及更高版本。
Guzzle（通过Composer包含）。

安装

使用Composer并添加 taxjar-php 作为依赖项

composer require taxjar/taxjar-php

{
  "require": {
    "taxjar/taxjar-php": "^2.0"
  }
}

如果您在执行 composer require 时遇到错误，请直接更新您的 composer.json 并运行 composer update。

认证

require __DIR__ . '/vendor/autoload.php';
$client = TaxJar\Client::withApiKey($_ENV['TAXJAR_API_KEY']);

现在您已经准备好使用TaxJar了！请查看我们的快速入门指南，以快速开始使用：快速入门指南。

使用

categories - 列出所有税务类别
 taxForOrder - 计算订单的销售额税
 listOrders - 列出订单交易
 showOrder - 显示订单交易
 createOrder - 创建订单交易
 updateOrder - 更新订单交易
 deleteOrder - 删除订单交易
 listRefunds - 列出退款交易
 showRefund - 显示退款交易
 createRefund - 创建退款交易
 updateRefund - 更新退款交易
 deleteRefund - 删除退款交易
 listCustomers - 列出客户
 showCustomer - 显示客户
 createCustomer - 创建客户
 updateCustomer - 更新客户
 deleteCustomer - 删除客户
 ratesForLocation - 列出位置的税率（按邮政编码）
nexusRegions - 列出nexus地区
 validateAddress - 验证地址
 validate - 验证VAT号码
 summaryRates - 总结所有地区的税率

列出所有税务类别 (API文档)

TaxJar API为产品类别的子集提供了产品级别的税务规则。这些类别用于在部分司法管辖区免税或税率降低的产品。在计算完全应税产品的销售额税时，无需传递产品税务代码。只需省略该参数即可。

$categories = $client->categories();

计算订单的销售额税 (API文档)

显示给定订单应收取的销售额税。

$order_taxes = $client->taxForOrder([
  'from_country' => 'US',
  'from_zip' => '07001',
  'from_state' => 'NJ',
  'from_city' => 'Avenel',
  'from_street' => '305 W Village Dr',
  'to_country' => 'US',
  'to_zip' => '07446',
  'to_state' => 'NJ',
  'to_city' => 'Ramsey',
  'to_street' => '63 W Main St',
  'amount' => 16.50,
  'shipping' => 1.5,
  'line_items' => [
    [
      'id' => '1',
      'quantity' => 1,
      'product_tax_code' => '31000',
      'unit_price' => 15.0,
      'discount' => 0
    ]
  ]
]);

echo $order_taxes->amount_to_collect;
// 1.26

列出订单交易 (API文档)

列出通过API创建的现有订单交易。

$orders = $client->listOrders([
  'from_transaction_date' => '2015/05/01',
  'to_transaction_date' => '2015/05/31'
]);

显示订单交易 (API文档)

显示通过API创建的现有订单交易。

$order = $client->showOrder('123');

创建订单交易 (API文档)

创建新的订单交易。

$order = $client->createOrder([
  'transaction_id' => '123',
  'transaction_date' => '2015/05/14',
  'from_country' => 'US',
  'from_zip' => '92093',
  'from_state' => 'CA',
  'from_city' => 'La Jolla',
  'from_street' => '9500 Gilman Drive',
  'to_country' => 'US',
  'to_zip' => '90002',
  'to_state' => 'CA',
  'to_city' => 'Los Angeles',
  'to_street' => '123 Palm Grove Ln',
  'amount' => 17.45,
  'shipping' => 1.5,
  'sales_tax' => 0.95,
  'line_items' => [
    [
      'id' => '1',
      'quantity' => 1,
      'product_identifier' => '12-34243-9',
      'description' => 'Fuzzy Widget',
      'unit_price' => 15.0,
      'discount': 0,
      'sales_tax' => 0.95
    ]
  ]
]);

更新订单交易 (API文档)

更新通过API创建的现有订单交易。

$order = $client->updateOrder([
  'transaction_id' => '123',
  'amount' => 17.95,
  'shipping' => 2.0,
  'line_items' => [
    [
      'quantity' => 1,
      'product_identifier' => '12-34243-0',
      'description' => 'Heavy Widget',
      'unit_price' => 15.0,
      'discount' => 0.0,
      'sales_tax' => 0.95
    ]
  ]
]);

删除订单交易 (API 文档)

删除通过 API 创建的现有订单交易。

$client->deleteOrder('123');

列出退款交易 (API 文档)

列出通过 API 创建的现有退款交易。

$refunds = $client->listRefunds([
  'from_transaction_date' => '2015/05/01',
  'to_transaction_date' => '2015/05/31'
]);

显示退款交易 (API 文档)

显示通过 API 创建的现有退款交易。

$refund = $client->showRefund('123-refund');

创建退款交易 (API 文档)

创建一个新的退款交易。

$refund = $client->createRefund([
  'transaction_id' => '123-refund',
  'transaction_reference_id' => '123',
  'transaction_date' => '2015/05/14',
  'from_country' => 'US',
  'from_zip' => '92093',
  'from_state' => 'CA',
  'from_city' => 'La Jolla',
  'from_street' => '9500 Gilman Drive',
  'to_country' => 'US',
  'to_zip' => '90002',
  'to_state' => 'CA',
  'to_city' => 'Los Angeles',
  'to_street' => '123 Palm Grove Ln',
  'amount' => -17.45,
  'shipping' => -1.5,
  'sales_tax' => -0.95,
  'line_items' => [
    [
      'id' => '1',
      'quantity' => 1,
      'product_identifier' => '12-34243-9',
      'description' => 'Fuzzy Widget',
      'unit_price' => -15.0,
      'discount' => -0,
      'sales_tax' => -0.95
    ]
  ]
]);

更新退款交易 (API 文档)

更新通过 API 创建的现有退款交易。

$refund = $client->updateRefund([
  'transaction_id' => '123-refund',
  'transaction_reference_id' => '123',
  'amount' => -17.95,
  'shipping' => -2.0,
  'line_items' => [
    [
      'id' => '1',
      'quantity' => 1,
      'product_identifier' => '12-34243-0',
      'description' => 'Heavy Widget',
      'unit_price' => -15.0,
      'discount' => -0,
      'sales_tax' => -0.95
    ]
  ]
]);

删除退款交易 (API 文档)

删除通过 API 创建的现有退款交易。

$client->deleteRefund('123-refund');

列出客户 (API 文档)

列出通过 API 创建的现有客户。

$customers = $client->listCustomers();

显示客户 (API 文档)

显示通过 API 创建的现有客户。

$customer = $client->showCustomer('123');

创建客户 (API 文档)

创建一个新的客户。

$customer = $client->createCustomer([
  'customer_id' => '123',
  'exemption_type' => 'wholesale',
  'name' => 'Dunder Mifflin Paper Company',
  'exempt_regions' => [
    [
      'country' => 'US',
      'state' => 'FL'
    ],
    [
      'country' => 'US',
      'state' => 'PA'
    ]
  ],
  'country' => 'US',
  'state' => 'PA',
  'zip' => '18504',
  'city' => 'Scranton',
  'street' => '1725 Slough Avenue'
]);

更新客户 (API 文档)

更新通过 API 创建的现有客户。

$customer = $client->updateCustomer([
  'customer_id' => '123',
  'exemption_type' => 'wholesale',
  'name' => 'Sterling Cooper',
  'exempt_regions' => [
    [
      'country' => 'US',
      'state' => 'NY'
    ]
  ],
  'country' => 'US',
  'state' => 'NY',
  'zip' => '10010',
  'city' => 'New York',
  'street' => '405 Madison Ave'
]);

删除客户 (API 文档)

删除通过 API 创建的现有客户。

$client->deleteCustomer('123');

列出位置的税率（通过邮政编码）(API 文档)

显示给定位置的销项税率。

请注意，此方法仅返回给定位置的完整组合税率。它不支持联系点的确定、基于发货地和目的地的来源、运输的应税性、产品免税、客户免税或销售税假日。我们建议使用 taxForOrder 准确计算订单的销售税。

$rates = $client->ratesForLocation(90002, [
  'city' => 'LOS ANGELES',
  'country' => 'US'
]);

echo $rates->combined_rate;
// 0.09

列出联系点区域 (API 文档)

列出 TaxJar 账户的现有联系点位置。

$nexus_regions = $client->nexusRegions();

验证地址 (API 文档)

验证客户地址并返回地址匹配的集合。地址验证需要 TaxJar Plus 订阅。

$addresses = $client->validateAddress([
  'country' => 'US',
  'state' => 'AZ',
  'zip' => '85297',
  'city' => 'Gilbert',
  'street' => '3301 South Greenfield Rd'
]);

验证增值税号 (API 文档)

将现有的增值税识别号与 VIES 进行验证。

$validation = $client->validate([
  'vat' => 'FR40303265045'
]);

总结所有地区的税率 (API 文档)

检索地区作为备份的最小和平均销售税率。

此方法适用于定期下拉使用，以防 TaxJar API 不可用。然而，它不支持关联判定、基于发货地和收货地的来源、运输应税性、产品豁免、客户豁免或销售税假期。我们建议使用 taxForOrder 准确计算订单的销售税。

$summarized_rates = $client->summaryRates();

沙箱环境

您可以轻松配置客户端以使用 TaxJar 沙盒

require __DIR__ . '/vendor/autoload.php';
$client = TaxJar\Client::withApiKey($_ENV['TAXJAR_SANDBOX_API_KEY']);
$client->setApiConfig('api_url', TaxJar\Client::SANDBOX_API_URL);

要测试特定的错误响应代码，请传递自定义的 X-TJ-Expected-Response 标头

$client->setApiConfig('headers', [
  'X-TJ-Expected-Response' => 422
]);

自定义选项

超时

此包利用 Guzzle，默认请求超时值为 0s，允许请求无限期地挂起。

您可以通过在客户端中配置以秒为单位的 timeout 值来修改此行为。

$client->setApiConfig('timeout', 30);

API 版本

默认情况下，TaxJar 的 API 将对请求不包含版本标头的请求以最新 API 版本响应。

要请求特定的 API 版本，请包含带有所需版本字符串的 x-api-version 标头。

$client->setApiConfig('headers', [
  'x-api-version' => '2020-08-07'
]);

错误处理

当我们向 TaxJar 发送无效数据或遇到错误时，我们将抛出包含 HTTP 状态码和错误信息的 TaxJar\Exception。要捕获这些异常，请参考下面的示例

require __DIR__ . '/vendor/autoload.php';
$client = TaxJar\Client::withApiKey($_ENV['TAXJAR_API_KEY']);

try {
  // Invalid request
  $order = $client->createOrder([
    'transaction_date' => '2015/05/14',
    'from_country' => 'US',
    'from_zip' => '07001',
    'from_state' => 'NJ',
    'from_city' => 'Avenel',
    'from_street' => '305 W Village Dr',
    'to_country' => 'US',
    'to_zip' => '90002',
    'to_state' => 'CA',
    'to_city' => 'Ramsey',
    'to_street' => '63 W Main St',
    'amount' => 16.5,
    'shipping' => 1.5,
    'sales_tax' => 0.95,
    'line_items' => [
      [
        'id' => '1',
        'quantity' => 1,
        'product_tax_code' => '31000',
        'unit_price' => 15,
        'discount' => 0,
        'sales_tax' => 0.95
      ]
    ]
  ]);
} catch (TaxJar\Exception $e) {
  // 406 Not Acceptable – transaction_id is missing
  echo $e->getMessage();

  // 406
  echo $e->getStatusCode();
}

有关错误代码的完整列表，请点击此处。

测试

请确保通过 composer install 安装 PHPUnit 并运行以下命令

php vendor/bin/phpunit test/specs/.

要启用调试模式，在认证后设置以下配置参数

$client->setApiConfig('debug', true);

taxjar / taxjar-php

维护者

详细信息