README

iDoklad v2

用于发送iDoklad api v2请求的PHP类。 iDoklad api v2文档

将库添加到项目

我们可以通过包含src/iDoklad.php文件或将库通过composer添加到项目中。然后，我们使用use来引用库。

composer require malcanek/idoklad-v2

设置我们的client ID，client secret，以及如果我们要使用OAuth2认证，还需要设置redirect URI。最后，我们调用iDoklad对象，它负责所有通信。

include_once 'src/iDoklad.php';
            
use petrvacha\iDoklad\iDoklad;
use petrvacha\iDoklad\auth\iDokladCredentials;
use petrvacha\iDoklad\iDokladException;

$clientId = 'Your client ID';
$clientSecret = 'Your client secret';
$redirectUri = 'Your redirect URI for OAuth2';

$iDoklad = new iDoklad($clientId, $clientSecret, $redirectUri);

OAuth2授权 - 授权码流

OAuth2授权通过几个步骤进行。我们使用从开发门户获取的client ID和client secret。

首先，我们提供一个用户输入其登录凭据的URL。我们可以使用以下方法获取这个URL

echo '<a href="'.$iDoklad->getAuthenticationUrl().'">Odkaz</a>';

用户输入登录凭据后，用户将被重定向到指定的redirect URI，并带有代码，我们可以用它来获取其凭据信息。我们将按照以下方式处理代码

$iDoklad->requestCredentials($_GET['code']);

现在，对象实例中已经建立了凭据，我们可以向iDoklad api发送查询。我们可以通过两种方式获取凭据。从对象中直接获取凭据

$credentials = $iDoklad->getCredentials();
echo $credentials->toJson();

使用credentials回调处理credentials

回调工作方式是库在credentials更改时总是调用回调函数。这很有用，因为当令牌过期时，它会自动刷新令牌。

$iDoklad->setCredentialsCallback(function($credentials){
    file_put_contents('credentials.json', $credentials->toJson());
});

将credentials上传到iDoklad对象

使用已存在的credentials创建对象

$iDoklad = new iDoklad($clientId, $clientSecret, $redirectUri, $credentials);

将credentials添加到已存在的对象中

$iDoklad->setCredentials($credentials);

一旦对象包含credentials，就可以向iDoklad api发送查询。

OAuth2授权 - 客户端凭据流

这种方法更简单。我们根据用户账户设置中的client id和client secret获取凭据。创建对象后，我们只需调用

$iDoklad->authCCF();

与OAuth2 - Authorization code flow一样，这里也使用credentials回调。

向iDoklad api发送请求

用于发送api请求的iDokladRequest对象。在最简单的形式中，我们只需一个参数，该参数根据文档确定操作，然后直接发送到api。

$request = new iDokladRequest('IssuedInvoices');
$response = $iDoklad->sendRequest($request);

从api获取数据

如果请求成功，将以iDokladResponse对象的形式返回数据。首先，我们检查请求是否成功（返回值应该是200）

$response->getCode();

然后，我们可以从数组中获取实际数据

$response->getData();

错误捕获

该类抛出iDokladException类型的异常。

创建新发票

$request->addMethodType('POST');
$data = array(
    'PurchaserId' => 3739927,
    'IssuedInvoiceItems' => [array(
        'Name' => 'Testovaci polozka',
        'UnitPrice' => 100,
        'Amount' => 1
    )]
);
$request->addPostParameters($data);

或者，我们可以使用函数来设置新的method type，现在看起来像这样

$data = array(
    'PurchaserId' => 3739927,
    'IssuedInvoiceItems' => [array(
        'Name' => 'Testovaci polozka',
        'UnitPrice' => 100,
        'Amount' => 1
    )]
);
$request->post()->addPostParameters($data);

使用过滤和排序

为了使用过滤，我们将使用iDokladFilter类。参数可以在创建类时设置，第一个参数是要过滤的字段名，第二个参数是操作符，最后一个参数是值。

$filter = new iDokladFilter('DocumentNumber', '==', '20170013');
$request->addFilter($filter);

我们可以同时添加多个过滤器，然后我们可以选择过滤器的逻辑关系，以使它们都成立（and），或者至少一个成立（or）。

$request->setFilterType('or');

为了使用排序，我们将使用iDokladSort类。同样，我们可以在创建类时添加参数，第一个参数是字段名，第二个参数是可选的，可以指定是升序（asc）还是降序（desc）。

$sort = new iDokladSort('DocumentNumber', 'desc');
$request->addSort($sort);

分页和返回项数

$request->setPage(2);
$request->setPageSize(5);

在返回码大于或等于400时抛出异常

如果我们想在返回码大于或等于400的http返回码时抛出异常，只需调用fci即可

$iDoklad->httpExceptionsOn()

其他修改

如果我们需要使用POST、PUT、PATCH、DELETE方法，我们将使用iDokladRequest对象上的addMethodType方法。

示例

使用示例可以在文件 acf.php 和 ccf.php 中查看。acf.php 包含了授权码流的使用示例，ccf 包含了客户端凭据流的使用示例，只需添加自己的客户端 ID、客户端密钥和重定向 URI 即可。

petrvacha / idoklad-v2

维护者

详细信息