dlin/saasu

用于 Saasu API 的 PHP 库

维护者

详细信息

github.com/dlin-me/saasu

源代码

问题

安装: 2,248

依赖者: 1

建议者: 0

安全: 0

星标: 4

关注者: 4

分支: 5

开放问题: 1

1.0.1 2013-10-03 14:07 UTC

Requires

Requires (Dev)

MIT 144bfdd1d50622b90027150c644c58436d29645a

webserviceAccountingsaasu

This package is not auto-updated.

Last update: 2024-09-23 14:44:15 UTC

README

1. 概述

这是一个在线会计软件 Saasu 的 PHP 客户端库。完整的 API 文档可在 http://help.saasu.com/api/ 查找。

这个库旨在简化与 Saasu API 的一般用途。

2. 安装

使用 composer，将其添加到您的 composer.json 中

{
    "require": {
        "dlin/saasu": "dev-master"
    }
}

如果您是 composer 新手，以下是一些简单的步骤。

  1. 从上述链接下载 composer.phar
  2. 创建一个名为 composer.json 的 json 文件，其中只包含上述 "require" 块
  3. 将 composer.phar 和 composer.json 并排放置，您可以运行以下命令
php ./composer.phar install

  1. composer 将创建一个名为 vendor 的目录，并将所有必需的库下载到该目录中。

  2. 在 vendor 目录中，还有一个名为 autoload.php 的文件。这是库内部的 PHP 自动加载器。您可能需要将其注册到现有的自动加载器中，或者手动包含它。

3. 使用方法

这个库（以下简称 Saasu PHP 客户端）提供了一个非常简单的接口，包括与 Saasu API 交互的方法来加载、插入、更新、搜索和删除实体。

实例化主 API 实例


// You will need to include this autoload script manually
// if you don't have any autoloader setup.
include "../path/to/vendor/autoload.php"; 

// one needs to declear the namespace for each class used 
use Dlin\Saasu\SaasuAPI;

// You can obtain accesskey and fileUid from your account at:
// https://secure.saasu.com/a/net/webservicessettings.aspx
$wsaccesskey = 'D4A92597762C4FDCAF66FF03C988B7B2';
$fileUid = '41555';


//Instantiate the main class for later use
$api = new SaasuAPI($wsaccesskey, $fileUid);
...

创建（插入）实体

//Create an entity object
$bankAccount = new BankAccount();

//Sets entity properties
$bankAccount->type = AccountType::Income;
$bankAccount->name = "Test Name";"
$bankAccount->displayName = "Test Account";
$bankAccount->bsb = 123456;
$bankAccount->accountNumber = 123123123;

//Save the new entity, i.e. create the entity
$api->saveEntity($bankAccount);

save() 方法接受一个实体对象（更多详细信息请见下文）并持久化对象属性。通过检查实体对象的 uid 属性，save() 方法确定是执行 '创建' 操作还是 '更新' 操作。如果实体对象有一个 null 的 uid 属性，将创建一个新的实体。如果实体对象有一个数字的 uid 属性，这表示一个现有的实体对象，则将更新现有的实体对象。

更新实体

//change some value of an existing entity with a uid
echo $bankAccount->uid; //prints 23456,
$bankAccount->name = "Updated Name";

//Save the change
$api->saveEntity($bankAccount);

批量更新和插入实体

Saasu PHP 客户端 允许在一个请求中更新和插入多个实体。这是通过 saveEntities 方法实现的，该方法接受一个要更新或插入的实体对象数组。您可以混合现有实体和新实体到一个数组中，并在一个单一请求中同时执行更新和创建操作。数组中的实体不需要是同一类型。

//an account to create
$bankAccount = new BankAccount();
$bankAccount->type = AccountType::Income;
$bankAccount->name = "Test Name";"
$bankAccount->displayName = "Test Account";
$bankAccount->bsb = 123456;
$bankAccount->accountNumber = 123123123;


//an account to update
echo $existingAccount->uid; //prints 4354323;
$existingAccount->name = "Updated Name";
$existingAccount->displayName = "Another Account";


//perform bulk operation
$api->saveEntities(array($bankAccount, $existingAccount));

加载实体

与其他一些 API 库不同，没有提供 'getById' 方法。相反，您使用一个具有给定 uid 的空实体作为数据持有者，并使用 loadEntity 方法将数据加载到实体中。

//Create an empty entity object
$newBankAccount = new BankAccount();

//Set the uid you want to get
$newBankAccount->uid = 23456;

//Load the data for the entity
$api->loadEntity($newBankAccount);

echo $newBankAccount->name; //prints "Updated Name";

搜索实体（列出实体）

要搜索/列出实体，您需要指定搜索条件。这是通过创建一个条件对象并设置该对象的属性来完成的。每个主要实体类都有一个相应的条件类。例如，要搜索 BankAccount，您需要一个 BankAccountCriteria 对象。更多详细信息将在后续章节中介绍。

$criteria = new BankAccountCriteria();
$criteria->isInbuilt = 'false';
$criteria->type = AccountType::Income;
$criteria->isActive = 'true';

//Return an array of matching Bank Accounts
$results = $api->searchEntities($criteria);

foreach($results as $bankAccount){
	//do something with the $bankAccount entity
}

searchEntities 方法调用 Saasu 的 list API。作为参数的 Criteria 对象告诉 API 列出什么，以及应用哪些过滤条件。如果您不想过滤结果列表，可以跳过设置 Criteria 对象的任何属性值。

//No filter applies, retrieve all bank accounts
$results = $api->searchEntities(new BankAccountCriteria());

在搜索实体时，Saasu API 实际上返回了未定义为实体对象属性的数据字段。例如，在搜索InvoicePayment时，API 返回了 amount 字段，该字段未定义为InvoicePayment对象的属性（它有InvoicePaymentItems来计算总额）。这些额外数据字段通过 getExtra 方法公开。

$criteria = new InvoicePaymentCriteria();
$criteria->transactionType= TransactionType::SalePayment;
$criteria->bankAccountUid = 23456;

$results = $this->api->searchEntities($criteria);

$result = reset($results);//get the first one;

echo $res->getExtra('amount');//prints 60

*** 注意： ***

从2013年10月开始，inventoryItemList和commboItemList API将正式弃用。自1.0.1版本起，此 Saasu PHP客户端 使用新的FullInventoryItemList和FullCommboItemList API。请确保在2013年10月后您拥有正确的版本。

删除实体

要删除实体，您使用 deleteEntity 方法。与更新和插入实体不同，没有批量操作方法可以一次请求删除多个实体。与 loadEntity 方法类似，您可以使用仅包含uid的空实体对象来告诉 Saasu PHP客户端 您要删除的内容。

//create a empty entity with a given uid
$toBeDeleted = new BankAccount(23456);

//delete it
$api->deleteEntity($toBeDeleted);

注意上述代码的第一行将uid传递给实体构造函数。这是一种方便的可选方法，用于将 uid 设置为新创建的对象。所有主要实体类都接受uid作为其构造函数的可选参数。

4. 实体

在 Saasu PHP客户端 中，实体对象是我们所说的数据传输对象（DTO）。一些实体，如 EmailMessage，是辅助实体，没有分配 uid 属性值。可以分配 uid 的实体是 主要 实体。只有 主要 实体有相应的标准类，除了 DeletedEntity 和 Tag（稍后介绍）。

主要实体

弱实体

有些实体不是主要实体，但被主要实体用作属性。

您不能创建或删除弱实体，相反，您可以通过将它们作为属性分配给主要实体来处理弱实体。

特殊实体

Tag 和 DeletedEntity 是特殊的，因为根据定义它们实际上不是实体，但在技术上它们是主要用于搜索的DTO对象。这意味着，创建 DeletedEntity（您应该删除实体）或创建 Tag（您可以将单词附加到实体作为“标签”）是没有意义的。

动作实体

这两种类型的实体非常特殊，因为它们根本不是实体，而是您希望Saasu API采取的操作的表示。

您只能创建这两种实体（即创建任务）。不能对它们执行其他操作。更新或删除EmailPdfInvoice是没有意义的。

辅助实体

有一个辅助实体实际上不是实体，但它被归类到实体类别中。

以下是一个示例，如果您想在创建新发票时向联系发送电子邮件。

//prepare an email;
$email = new EmailMessage();
$email->to = "test@hotmail.com";
$email->from = "test.sender@gmail.com";
$email->subject = "test saasu";
$email->body = "test body";

//create an instruction
$instruction = new InvoiceInstruction();
$instruction->emailMessage = $email;
$instruction->emailToContact = 'true';

//create an invoice;
$invoice = new Invoice();
$invoice->date = DateTime:getDate(time());
...

$this->api->saveEntity($invoice, $instruction);

当处理发票时，saveEntity 方法支持另一个参数 $instruction。

5. 辅助类

为了方便使用实体类，有一些有用的辅助类可用。

DateTime

Saasu API仅接受UTC、ISO 8061格式的日期和日期时间字符串作为日期和日期时间字段。此类旨在帮助您轻松生成格式化的日期和日期时间字符串。

有两个静态方法可用，它们都接受与 strtotime 函数兼容的数字时间戳或 日期字符串 输入。

echo DateTime::getDate(time());
//2013-07-30

echo DateTime::getDateTimes(time());
//2013-07-30T01:16:53

echo DateTime::getDate('+1day');
//2013-07-31

echo DateTime::getDateTimes('+1day');
//2013-07-31T01:16:53

枚举类

Saasu在很多情况下使用字符串令牌作为所需的属性值。为了帮助避免输入错误并方便查找值，Saasu PHP客户端 提供了按有意义的名称分组到类中的常量。通过检查类名，可以轻松地确定它们的位置。

  • AccountType
  • ActivityAttachedToType
  • ContactCategoryType
  • EmailFormat
  • EntityTypeUID
  • 间隔类型
  • 发票布局
  • 发票查询选项
  • 发票状态
  • 发票类型AU
  • 发票类型NZ
  • 发票类型SG
  • 其他发票类型
  • 日记项目类型
  • 派送状态
  • 称呼
  • 搜索字段名
  • 税码
  • 贸易条款类型
  • 交易类型

枚举类扩展了EnumBase类，该类提供了两个有用的静态方法keys()和values()

keys()

返回类的常量名称数组

values()

返回一个关联数组，其中常量名称作为键，其值作为值

6. 异常

当Saasu API拒绝请求时，将抛出一个带有相关消息和响应代码的异常。处理一些复杂实体（如发票）时，需要特别注意，例如库存/库存水平、账户余额和付款必须保持一致。

发票规则

  • 不允许重复的发票号码。
  • 不允许发票超额付款（例如，将200美元的付款应用于100美元的发票是不允许的）。
  • 税码不能应用于税账户（资产：购买支付的税金和负债：销售收集的税金）。
  • 税码不能应用于银行账户。
  • 如果指定了到期日以及贸易条款，则贸易条款将优先于到期日，以设置保存的发票的实际到期日。
  • 不允许插入、更新和删除可能导致无效库存水平的项目发票。

有时创建、更新或删除发票太过容易，从而导致违反这些规则。在这些情况下，异常有助于解决问题。

try{
	…
	$api->deleteEntity($invoice);
	…
}catch(Exception $e){
	$err = $e->getMessage();
	//report the exception
	echo $err;
}

7. 单元测试

该库包含的测试用例有200+个断言，它们也可以作为覆盖每个实体和大多数使用情况的示例集合。

如果需要，请花时间检查测试代码。

运行测试用例需要PHPUnit。还必须更新TestBase.php文件，以包含自己的测试账户wsaccesskey和fileUID。


//file tests/Dlin/Saasu/Tests/Entity/TestBase.php
...
public function setUp()
{
        //Please update with your testing account settings
        $this->api = new SaasuAPI('D4A92597762C4FDCAF66FF03C988B7B0', '41509');
}

8. 验证

此Saasu PHP客户端库中的所有实体都附带一个validate()方法。

validate方法返回一个Validator实例，该实例提供hasError和getErrors方法。

hasError(fieldName)方法在给定的字段无效时返回true，否则返回false

getErrors()方法返回一个错误关联数组，键是字段名称，值是错误类型

让我们以一个测试用例片段为例

$a = new Activity();

//If no field name is given, any invalid field will result in **hasError** returning true.
$this->assertTrue($a->validate()->hasError());

//If a field name is given, true is returned if the given field has invalid value
$this->assertTrue($a->validate()->hasError('type'));

//getErrors return all errors if there's any
$errors = $a->validate()->getErrors();

//The error message is just the type of error
echo $error['type']; //prints "required";

//'required' is simple one of many error types, you can look at the Validator class for all.
$a->type="Some invalid value";
$errors = $a->validate()->getErrors();
echo $error['type']; //prints "enum"; i.e invalid value

//Using the classe constants help avoid invalid values
$a->type= ActivityType::Sale;
$this->assertFalse($a->validate()->hasError('type'));

某些字段仅在实体更新时才需要。例如，当您想更新实体时，uid字段是必需的。为此，主实体的validate方法接受一个可选参数，以指示验证是针对'更新'操作。

$invoice = new Invoice();

echo $invoice->validate(true)->hasError('uid'); //true for update
echo $invoice->validate()->hasError('uid'); //false for create

9. 限制与已知问题

使用限制

Saasu实施了一些公平竞争的限制

每秒最多5个请求。

每天最多2,000个请求。

所有同步活动都必须依赖于API支持的Last Modified。

如果您一次发送数百个请求，则在每50个请求之间至少插入2秒的延迟。

在发送多个任务请求时，将任务数量限制在最多50个。

此PHP客户端库具有内部节流，确保任何一秒内最多只能进行5个请求。然而，您有责任注意其他使用限制。

隐藏规则

由于会计和API软件本身的复杂性，可能存在许多未记录的规则。

例如，在搜索联系人时，不活跃的联系人永远不会返回，即不可搜索。

另一个删除库存项的示例。如果您发现自己无法删除库存项，您可能需要首先删除任何相关的库存转移、库存调整和组合项，然后才能成功删除库存项。因为从库存调整到库存项之间存在依赖链。

10. 许可证

此库是免费的。请参阅根目录中的许可文件以获取详细许可信息。