README

Poweroffice API 客户端，用于与 PowerOffice API 进行交互： https://api.poweroffice.net/Web/docs/index.html

安装

您可以通过 composer 安装此包

composer require guilty/poweroffice

使用

独立使用

您可以将此包作为独立的 PHP 包使用，以下是一个简单的示例

<?php


use Guilty\Poweroffice\Services\PowerofficeService;
use Guilty\Poweroffice\Sessions\ValueStoreSession;
use GuzzleHttp\Client;
use Spatie\Valuestore\Valuestore;


$client = new Client();
$store = Valuestore::make(config("poweroffice.store_path"));
$session = new ValueStoreSession($store);
$service = new PowerOfficeService(
    $client,
    $session,
    "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa", // Application Key
    "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb", // Client Key 
    true // Test Mode
);

Laravel

您可以通过以下方式发布配置文件

php artisan vendor:publish --provider="Guilty\Poweroffice\PowerofficeServiceProvider" --tag="config"

这是已发布配置文件的内容

<?php

return [
    'application_key' => env("POWEROFFICE_APPLICATION_KEY"),
    'client_key' => env("POWEROFFICE_CLIENT_KEY"),
    'test_mode' => env("POWEROFFICE_TEST_MODE"),
    'store_path' => storage_path("poweroffice.json"), // Used with the ValueStoreSession
];

要开始，请将以下环境变量添加到您的 .env 文件中

POWEROFFICE_APPLICATION_KEY=aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa
POWEROFFICE_CLIENT_KEY=bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb
POWEROFFICE_TEST_MODE=true

会话实现

PowerOffice API 使用 "client_credentials" 授权类型进行身份验证，为了跟踪 "会话"（访问令牌、刷新令牌和过期日期），我们使用一个 Session 类来存储这些值，开箱即用以下会话实现已提供

提供的会话实现

ArraySession - 用于测试
ValueStoreSession - 可用于生产，将所有数据保存到在 "poweroffice.store_path" 配置选项中定义的 json 文件中，使用 Spatie 的 ValueStore 包
RedisSession - 可用于生产，将所有数据保存到 redis 缓存中，键名以 POWEROFFICE_SESSION_{KEYNAME} 开头，需要 Predis 客户端。

实现自己的会话类

创建一个新的类，实现 SessionInterface 接口并添加所需的方法，具体的实现取决于您，您可以将数据存储在数据库中、文件中、redis 中，或您需要的任何地方。

或者...

扩展 AbstractSession，它为您实现了部分方法。

以下是您需要实现的接口。

<?php

namespace Guilty\Poweroffice\Interfaces;

interface SessionInterface
{
    public function setAccessToken($accessToken);
    public function getAccessToken();
    public function setRefreshToken($refreshToken);
    public function getRefreshToken();
    public function canRefresh();
    public function disconnect();
    public function setExpireDate(\DateTime $expireDate);
    /** @return \DateTimeImmutable */
    public function getExpireDate();
    public function hasExpired();
    public function isValid();
    public function setFromResponse($response);
}

以下是一个扩展 AbstractSession 的示例。

<?php

use Guilty\Poweroffice\Sessions\AbstractSession;

// Or whatever else you want to store your session
class ExcelSpreadsheetSession extends AbstractSession
{
    public function setAccessToken($accessToken) { /* TODO: Implement */ }
    public function getAccessToken() { /* TODO: Implement */ }
    public function setRefreshToken($refreshToken) { /* TODO: Implement */ }
    public function getRefreshToken() { /* TODO: Implement */ }
    public function disconnect() { /* TODO: Implement */ }
    public function setExpireDate(\DateTime $expireDate) { /* TODO: Implement */ }
    public function getExpireDate() { /* TODO: Implement */ } 
}

使用服务类

如果您只想将此包作为 Guzzle 的轻量级包装器使用，处理 oAuth 会话存储和维护，您可以直接使用 performRequest() 方法，以下是一个示例

<?php
 
require "./vendor/autoload.php";


use Guilty\Poweroffice\Services\PowerofficeService;
use GuzzleHttp\Client;
use Guilty\Poweroffice\Sessions\ArraySession;

$service = new PowerOfficeService(
    new Client(),
    new ArraySession(), 
    "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa", // Application Key
    "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb", // Client Key 
    true // Test Mode
);

$customer = $service->performRequest("post", "/Customer", [
    "json" => [
        "firstName" => "John",
        "lastName" => "Smith",
        "emailAddress" => "johnsmith@example.com",
        "invoiceEmailAddress" => "johnsmith@example.com",
        "isArchived" => false,
        "isPerson" => true,
        "invoiceDeliveryType" => 1, // PDF By Email
        "since" => (new DateTimeImmutable())->format("Y-m-d"),
        "mailAddress" => $address = [
            "address1" => "123 Fakestreet",
            "city" => "Lazytown",
            "zipCode" => "1234",
            "countryCode" => "NO", // ISO Country Code (norway)
            "isPrimary" => true,
        ],
        "streetAddresses" => [$address], // Must be an array
    ]
]);

// All responses will include a success key, that can be used for error handling
if ($response["success"] === false) {
    throw new Exception("Customer could not be created");
}

或者，您可以使用提供的方法，这些方法会预先填充方法和路径，以及简化某些数据（如起始和结束日期）的提供。

<?php
 
require "./vendor/autoload.php";


use Guilty\Poweroffice\Services\PowerofficeService;
use GuzzleHttp\Client;
use Guilty\Poweroffice\Sessions\ArraySession;

$service = new PowerOfficeService(
    new Client(),
    new ArraySession(),
    "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa", // Application Key
    "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb", // Client Key 
    true // Test Mode
);

$customer = $service->createCustomer([
    "json" => [
        "firstName" => "John",
        "lastName" => "Smith",
        "emailAddress" => "johnsmith@example.com",
        "invoiceEmailAddress" => "johnsmith@example.com",
        "isArchived" => false,
        "isPerson" => true,
        "invoiceDeliveryType" => 1, // PDF By Email
        "since" => (new DateTimeImmutable())->format("Y-m-d"),
        "mailAddress" => $address = [
            "address1" => "123 Fakestreet",
            "city" => "Lazytown",
            "zipCode" => "1234",
            "countryCode" => "NO", // ISO Country Code (norway)
            "isPrimary" => true,
        ],
        "streetAddresses" => [$address], // Must be an array
    ]
]);

// All responses will include a success key, that can be used for error handling
if ($response["success"] === false) {
    throw new Exception("Customer could not be created");
}

关于 oData 过滤的说明

似乎 PowerOffice 的 API 在 oData 过滤中的字段名方面是区分大小写的。

待办事项

以下服务已在 API 客户端包装器中实现

会话

ArraySession（测试）
ValueStoreSession（生产）
RedisSession（生产）

功能

oData 过滤器构建器

服务

银行/银行转账
银行/客户银行账户
二进制对象
品牌主题
客户
客户身份验证
联系人组
客户
应收账款管理
部门
员工
外部可交付发票
总账账户
导入
发票附件
分录凭证
位置
出票发票
当事人银行账户
当事人联系人
工资/工资项
工资/工资行
产品
产品组
项目
项目活动
项目团队成员
周期性发票
报告/账户交易
报告/客户账簿
报告/发票日记
报告/供应商账簿
报告/试算表
报告/使用情况
子账簿编号系列
供应商
时间跟踪/活动
时间跟踪/小时类型
时间跟踪/时间跟踪条目
增值税代码

许可证

MIT许可证（MIT）。更多信息请参阅许可证文件。

由Guilty AS提供。

Poweroffice标志和商标是Poweroffice AS的财产。

guilty / poweroffice

维护者

详细信息