README

简介
安装
使用
- 认证
- 查询API
- 示例
开发状态
贡献
致谢
许可

简介

此软件包是Sellsy API的PHP客户端。它是对Guzzle HTTP客户端的轻量级包装。它旨在尽可能简单易用，同时具有稳健性。

客户端 仅支持Sellsy API的V2。如果您正在寻找V1客户端，请查看TeknooSoftware/sellsy-client。

为了确保Sellsy和此客户端之间数据交换的一致性，我们使用DTO类来定义共享实体的结构。这些类在Bluerock\Sellsy\Entities命名空间中定义。

use Bluerock\Sellsy\Entities;
use Bluerock\Sellsy\Api;

# create a new Contact instance using the related DTO
$contact = new Entities\Contact([
    'civility'      => 'mr',
    'first_name'    => 'Jean',
    'last_name'     => 'MOULIN',
    'email'         => 'user@example.com',
    'website'       => 'example.com',
    'mobile_number' => '0612121212',
    'position'      => 'Directeur',
    'social'        => new Entities\ContactSocials([
        'twitter' => 'https://twitter.com/u/example',
    ]),
]);

# store the freshly created Contact into Sellsy
$api = new Api\ContactsApi();
$response = $api->store($contact);

var_dump(
    $response->json()
);

这也意味着在执行GET请求时，您将获得来自Sellsy API的DTO实体。

$api = new Bluerock\Sellsy\Api\CompaniesApi();

# ... GET single entity
$company = $api->find("123")->entity();

# ... GET collection of entities (index, search..)
$companies = $api->index()->entities();

如果您不熟悉DTO或需要有关它的文档，请确保查看此客户端使用的spatie/data-transfer-object软件包。

请注意，此软件包仍在开发中。如果您缺少端点实现，请勿犹豫，贡献或在此存储库中打开问题。

安装

要求

PHP >= 7.4
Composer

通过Composer安装

composer require bluerock/sellsy-client               # latest compatible version 

composer require bluerock/sellsy-client:^1.0          # specific version 
composer require bluerock/sellsy-client:dev-dev-2.x   # development branch

使用

认证

此软件包支持以下认证方法

“个人”OAuth客户端凭据

在查询Sellsy API之前，您必须使用Config类提供您的凭据

$config = Bluerock\Sellsy\Core\Config::getInstance();

$config->set('client_id', 'f48f0fgm-2703-5689-2005-27403b5adb8d')
      ->set('client_secret', 'av8v94jx0ildsjje50sm9x1hnmjsg27bnqyryc0zgbmtxxmzpjzlw2vnj9aockwe')
      ->set('url', 'https://api.sellsy.com/v2/'): // not required: this is the default value.

有关Sellsy API v2凭据的更多信息，请参阅官方文档。

连接多个Sellsy账户

您可以同时连接到多个Sellsy账户。您只需配置每个实例，然后使用Config::switchInstance()（返回特定账户的Config对象）切换到其中一个或另一个。

// Configure the first Sellsy account
Bluerock\Sellsy\Core\Config::switchInstance('first-sellsy')
    ->set('client_id', 'id-1')
    ->set('client_secret', 'secret1');

// Configure another one
Bluerock\Sellsy\Core\Config::switchInstance('other-sellsy')
    ->set('client_id', 'id-2')
    ->set('client_secret', 'secret2');

// From now, each request is on the 'other-sellsy' account
// ...

// To switch back to the first account
Bluerock\Sellsy\Core\Config::switchInstance('first-sellsy');

查询API

基础知识

每个API域由一个复数化的类表示（例如：Contacts、Items、Taxes）。每个类都包含用于对域的端点执行请求的方法。

开始查询API的最简单方法是初始化相应的类

use Bluerock\Sellsy\Api\ContactsApi;

$contacts = new ContactsApi();
$contacts->index();
$contacts->search($filters);
$contacts->show($contact_id);
$contacts->store($contact);

您还可以使用Client外观，该外观包含所有域，通过调用方法轻松实例化相应的类

use Bluerock\Sellsy\Core\Client;

# via an instance...
$client = new Client();
$client->contacts()->show($contact_id);

# ... or statically.
Client::taxes()->index();

请求

此客户端使用Laravel CRUD操作关键字来命名方法

域文档中描述的任何其他方法都遵循驼峰命名约定。例如，额外的Companies方法看起来像这样

响应

在发出请求时，您将获得一个包含验证和读取响应方法的Bluerock\Sellsy\Core\Response对象。

您可以使用这些方法中的任何一个来检查响应

$response->entity();      # Get single resource entity, when available
$response->entities();    # Get resource entities collection, when available (for listing/search)
$response->pagination();  # Get the pagination object, when available
$response->type();        # Returns the type of the data, between "listing" and "single" 
$response->json();        # Get raw json data from response, as an associative array
$response->base();        # Get the underlying \Illuminate\Http\Client\Response object

$response->body(): string;
$response->json(): array|mixed;
$response->status(): int;
$response->ok(): bool;
$response->successful(): bool;
$response->failed(): bool;
$response->serverError(): bool;
$response->clientError(): bool;
$response->header($header): string;
$response->headers(): array;

默认情况下，如果请求返回错误（状态码4xx —> 5xx），则请求将抛出RequestException异常。您可以轻松捕获此异常并按您希望的任何方式处理它

/**
 * @return \Bluerock\Sellsy\Entities\Contact|false
 * @throws \Illuminate\Http\Client\RequestException
 */
public function maybeFindMyContact($contact_id)
{
    try {
        return Bluerock\Sellsy\Core\Client::contacts()
                    ->show($contact_id)
                    ->entity();
    } catch (\Illuminate\Http\Client\RequestException $e) {
        # return false if the contact is not found (404 error).
        if ($e->response->clientError() && $e->response->status() === 404) {
          return false;
        }

        # throw the exception for any other status code.
        throw $e;
    }
}

关于响应和DTO的注意事项

要从响应中检索DTO实体，您可以调用entity()和entities()方法之一

var_dump(
  Bluerock\Sellsy\Core\Client::taxes()->index()->entities()
);

// Output :
Bluerock\Sellsy\Collections\TaxCollection^ {
  #iterator: ArrayIterator {#5776
    -storage: array:6 [
      0 => Bluerock\Sellsy\Entities\Tax^ {
        +id: 4099258
        +rate: 20
        +label: ""
      }
      1 => Bluerock\Sellsy\Entities\Tax^ {
        +id: 4099259
        +rate: 10
        +label: ""
      }
    ]
  }
}

如果响应中嵌入了一些额外的实体，它们将被自动解析到后续的DTO中。

如果您需要读取原始响应，始终可以使用json()方法

var_dump(
  Bluerock\Sellsy\Core\Client::taxes()->index()->json()
);

// Output :
array:2 [
  "data" => array:6 [
    0 => array:4 [
      "id" => 4099258
      "is_active" => true
      "rate" => 20
      "label" => ""
    ]
    1 => array:4 [
      "id" => 4099259
      "is_active" => true
      "rate" => 10
      "label" => ""
    ]
  ],
  "pagination" => array:4 [
    "limit" => 100
    "count" => 6
    "total" => 6
    "offset" => "WyI0MDk5MjYzIl0="
  ]
]

示例

索引

通过使用index()方法列出资源，该方法仅接受查询参数作为唯一参数。

$contactsApi = new ContactsApi();

$response = $contactsApi->index([
  'limit'  => 10,
  'offset' => 0,
  'embed'  => [
      'invoicing_address',
      'main_contact',
      'dunning_contact',
      'invoicing_contact',
      'smart_tags',
  ],
]);

$response->entities();    // The API entities
$response->pagination();  // The pagination DTO

展示

show方法接受资源id作为第一个参数，查询参数作为第二个参数

$response = $contactsApi->show('123', [
    'embed' => [
        'smart_tags'
    ],
]);

$response->entity();    // The API entity

这将返回一个Bluerock\Sellsy\Entities\Contact实例

Bluerock\Sellsy\Entities\Contact^ {
  +id: 12345
  +civility: "ms"
  +first_name: "Amélie"
  +last_name: "PETIT"
  +email: "contact+atest@sellsy.com"
  +website: null
  +phone_number: null
  +mobile_number: null
  +fax_number: null
  +position: "Gérante"
  +birth_date: null
  +avatar: null
  +note: ""
  +social: Bluerock\Sellsy\Entities\ContactSocials^ {
    +twitter: null
    +facebook: null
    +linkedin: null
    +viadeo: null
  }
  +sync: Bluerock\Sellsy\Entities\ContactSync^ {
    +mailchimp: true
    +mailjet: true
    +simplemail: true
  }
  +is_archived: false
  +invoicing_address_id: null
  +delivery_address_id: null
  +invoicing_address: null
  +delivery_address: null
  +created: "2022-02-16T15:56:17+01:00"
  +owner: array:2 [
    "id" => 567
    "type" => "staff"
  ]
}

创建

store方法用于创建资源，期望实体对象作为第一个参数，并且可能作为第二个参数有$query参数

use Bluerock\Sellsy\Entities;

$contactsApi->store(new Entities\Contact([
    'civility'      => 'mr',
    'first_name'    => 'Jean',
    'last_name'     => 'MOULIN',
    'email'         => 'user@example.com',
    'website'       => 'example.com',
    'mobile_number' => '0612121212',
    'position'      => 'Directeur',
    'sync'          => new Entities\ContactSync(),
    'social'        => new Entities\ContactSocials([
        'twitter' => 'https://twitter.com/u/example',
    ]),
]));

$response->entity();  // The created entity
$response->json();    // The Sellsy response

更新

update方法期望更新的资源作为第一个参数，以及$query参数作为第二个参数

use Bluerock\Sellsy\Entities;

$contactsApi->update(new Entities\Contact([
    'id'         => 35536947,
    'first_name' => 'Jean',
    'last_name'  => 'CASTEX',
    'note'       => '',
]));

$response->entity();  // The updated entity
$response->json();    // The Sellsy response

在这里，"id"参数是从给定的Contact实体中提取的。

删除

在删除资源时，应调用destroy方法。此方法仅期望要删除的资源id

$contactsApi->delete(123)->json();

开发状态

✅ = 已完全实现
🆚 = 部分实现
🅾️ = 尚未实现

贡献

请随时为此包做出贡献！
如果您发现任何安全问题，请通过thomas@bluerocktel.com与我联系，而不是创建一个公开的github问题。

首次贡献指南

致谢

许可

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

bluerock / sellsy-client

维护者

详细信息