README

smaregi-api-php

• PSR-7: HTTP消息接口 - PHP-FIG
• PSR-17: HTTP工厂 - PHP-FIG
• PSR-18: HTTP客户端 - PHP-FIG

本库实现了根据上述PSR规定的接口实现的Smaregi平台API客户端库。

安装

composer require nonz250/smaregi-api-php

用法

• 规范说明书 | 文档 | Smaregi开发者
• Smaregi平台API通用规范说明书
• Smaregi平台API POS规范说明书
• Smaregi平台API订单管理规范说明书
• Smaregi平台API Waiter规范说明书
• Smaregi平台API工时卡规范说明书

获取应用访问令牌

https://github.com/nonz250/smaregi-api-php/blob/main/sample/public/application_token.php

将new SmaregiClientCredentials()传递给getAccessToken的参数，并在options中指定contract_id。同时，根据需要指定scope。

<?php
declare(strict_types=1);

use Nonz250\SmaregiApiPhp\Auth\SmaregiClientCredentials;
use Nonz250\SmaregiApiPhp\Auth\SmaregiProvider;

$provider = new SmaregiProvider(
    'SMAREGI_IDP_HOST',
    'SMAREGI_CLIENT_ID',
    'SMAREGI_CLIENT_SECRET',
);

$accessToken = $provider->getAccessToken(new SmaregiClientCredentials(), [
    'contract_id' => 'SMAREGI_CONTRACT_ID',
    'scope' => ['pos.products:read', 'pos.customers:read'],
]);

获取用户访问令牌

https://github.com/nonz250/smaregi-api-php/blob/main/sample/public/auth.php

根据需要指定redirect_uri。同样，在调用getAuthorizationUrl时，指定所需的scope。

出于安全考虑，请保存state和pkce，并在redirect_uri的后续处理中进行检查。

<?php
declare(strict_types=1);

use Nonz250\SmaregiApiPhp\Auth\SmaregiProvider;

session_start();

$provider = new SmaregiProvider(
    'SMAREGI_IDP_HOST',
    'SMAREGI_CLIENT_ID',
    'SMAREGI_CLIENT_SECRET',
    'https:///callback.php',
);

$authorizationUrl = $provider->getAuthorizationUrl([
    'scope' => ['openid', 'email', 'profile', 'offline_access', 'pos.products:read', 'pos.customers:read'],
]);
$_SESSION['sampleState'] = $provider->getState();
$_SESSION['samplePkceCode'] = $provider->getPkceCode();
header('Location: ' . $authorizationUrl);
exit();

https://github.com/nonz250/smaregi-api-php/blob/main/sample/public/callback.php

出于安全考虑，请对之前保存的state和pkce进行检查。

<?php
declare(strict_types=1);

use Nonz250\SmaregiApiPhp\Auth\SmaregiProvider;

session_start();

$sessionState = (string)($_SESSION['sampleState'] ?? '');

if ($sessionState === '') {
    throw new RuntimeException('Session state is empty.');
}
$sampleState = $_GET['state'] ?? '';

if ($sessionState !== $sampleState) {
    throw new RuntimeException('Invalid state.');
}

$provider = new SmaregiProvider(
    'SMAREGI_IDP_HOST',
    'SMAREGI_CLIENT_ID',
    'SMAREGI_CLIENT_SECRET',
    'https:///callback.php',
);

$code = $_GET['code'] ?? '';

$provider->setPkceCode($_SESSION['samplePkceCode'] ?? '');
$accessToken = $provider->getAccessToken('authorization_code', [
    'code' => $code,
]);

$resourceOwner = $provider->getResourceOwner($accessToken);

$accessToken = $provider->getAccessToken('refresh_token', [
    'refresh_token' => $accessToken->getRefreshToken(),
]);

示例

https://github.com/nonz250/smaregi-api-php/tree/main/sample

make build
make sample

执行上述操作后，访问https://以确认使用此库的实际操作。

此时，您需要从Smaregi开发者获取可用的凭证信息，因此请提前获取Smaregi开发者账户。

https://developers.smaregi.jp/signup/

获取Smaregi开发者账户后，请添加新应用并获取所需的凭证信息。
注：此过程不区分公共应用或私有应用。

将.env.example复制到.env，并根据上述参数设置相应的值。

https://github.com/nonz250/smaregi-api-php/tree/main/sample/public/.env.example

贡献

此仓库推荐使用Docker。

详细信息请参考Makefile。

帮助

显示各个命令的帮助信息。

make help

构建

在Docker中构建开发环境。

make build

在创建Pull Request之前请执行。

在创建Pull Request之前请执行make pr。

• 格式化器 (PHP CS Fixer)
• 静态分析器 (PHPStan)
• 单元测试 (PHPUnit)

将被执行。

make pr