README

概述

SuperFaktúra API允许外部应用的集成，允许远程创建文档并检索有关它们的文档。它还允许通过电子邮件或常规邮件发送发票。

要求

使用此包，您至少需要PHP 8.2。

快速入门

为了使您的应用程序与SuperFaktúra的集成更加容易，我们为您准备了一个简单的API客户端，您可以使用它以最小的努力远程签发发票。

但是，如果您希望创建自己的API客户端，我们也提供了通用文档。

如果您想尝试API集成，我们为斯洛伐克和捷克市场提供测试环境（沙盒）。

安装

只需运行此Composer命令

$ composer require superfaktura/apiclient

示例

从API开始

要使用此API客户端，您需要先进行以下操作

1. 在SuperFaktúra中创建一个账户

• 根据您的选择的市场，在这些网站之一创建账户
  • https://moja.superfaktura.sk/registracia
  • https://moje.superfaktura.cz/registrace
  • https://meine.superfaktura.at/registrierung
  • https://sandbox.superfaktura.sk/registracia
  • https://sandbox.superfaktura.cz/registrace
• 登录后尝试创建发票

2. 使用给定的凭据设置Api客户端实例

• 可以在以下网址找到
  • https://moja.superfaktura.sk/api_access
  • https://moje.superfaktura.cz/api_access
  • https://meine.superfaktura.at/api_access
  • https://sandbox.superfaktura.sk/api_access
  • https://sandbox.superfaktura.cz/api_access

<?php
include_once __DIR__ . '/vendor/autoload.php';

$api = new \SuperFaktura\ApiClient\ApiClient(
    new \SuperFaktura\ApiClient\Authorization\SimpleProvider(
        'test@example.com',
        'YOUR_APIKEY',
        'Example s.r.o.',
        1,
    ),
    \SuperFaktura\ApiClient\MarketUri::SLOVAK,
);

作为替代，您可以通过.env配置进行授权。

3. 使用

$response = $api->invoices->create(
    invoice: [
        'name' => 'Test API',
        'variable' => '12345',
    ],
    items: [
        [
            'name' => 'item name',
            'description' => 'item description',
            'tax' => 20,
            'unit_price' => 10,
        ],
    ],
    client: [
        'name' => 'Client name',
        'ico' => '44981082',
        'comment' => 'Client comment',
        'update_addressbook' => 1,
    ],
);
var_dump($response->data);

错误处理

try {
    $response = $api->invoices->create(
        invoice: [
            'name' => 'Test API',
            'variable' => '12345',
        ],
        items: [
            [
                'name' => 'item name',
                'description' => 'item description',
                'tax' => 20,
                'unit_price' => 10,
            ],
        ],
        client: [
            'name' => 'Client name',
            'ico' => '44981082',
            'comment' => 'Client comment',
            'update_addressbook' => 1,
        ],
    );
    
    var_dump($response->data);
} catch (\SuperFaktura\ApiClient\Contract\Invoice\CannotCreateInvoiceException $exception) {
    echo 'Cannot create invoice: ' . $exception->getMessage() . PHP_EOL;
} catch (\SuperFaktura\ApiClient\Request\CannotCreateRequestException $exception) {
    echo 'Cannot create request: ' . $exception->getMessage() . PHP_EOL;
}

用例示例

银行账户

1. BankAccounts::getAll

返回银行账户列表。

$response = $api->bank_accounts->getAll();
var_dump($response->data);

更多信息请查看API文档。

2. BankAccounts::create

创建银行账户并返回其数据

$response = $api->bank_accounts->create([
    'bank_name' => 'NovaBanka',
    'iban' => 'SK000011112222333344',
    'swift' => 'suzuki',
    'default' => 1,
    'show' => 1,
    'show_account' => 1,
]);
var_dump($response->data);

更多信息请查看API文档。

3. BankAccounts::update

更新现有银行账户并返回其数据。

$response = $api->bank_accounts->update(
    id: 1,
    bank_account: [
        'bank_name' => 'StaroNovaBanka',
        'swift' => '777777',
    ],
);
var_dump($response->data);

更多信息请查看API文档。

4. BankAccounts::delete

删除现有银行账户。

$api->bank_accounts->delete(1);

更多信息请查看API文档。

收银机

返回收银机列表。

1. CashRegisters::getAll

$response = $api->cash_registers->getAll();
var_dump($response->data);

更多信息请查看API文档。

2. CashRegisters::getById

返回收银机的详细信息。

$response = $api->cash_registers->getById(1);
var_dump($response->data);

更多信息请查看API文档。

收银机项目

1. CashRegister\Items::create

创建一个新的收银台项目并返回其数据。

$response = $api->cash_registers->items->create(
    cash_register_id: 1,
    data: [
        'amount' => 9.99,
        'currency' => \SuperFaktura\ApiClient\UseCase\Money\Currency::EURO,
    ],
);
var_dump($response->data);

有关更多信息，请参阅API 文档。

客户端

1. Clients::getAll

返回根据给定查询对象筛选的客户列表。

$response = $api->clients->getAll(new \SuperFaktura\ApiClient\UseCase\Client\ClientsQuery(
    full_text: 'Test',
    created: new \SuperFaktura\ApiClient\Filter\TimePeriod(
        period: \SuperFaktura\ApiClient\Filter\TimePeriodEnum::THIS_YEAR
    ),
));
var_dump($response->data);

有关更多信息，请参阅API 文档。

2. Clients::getById

返回客户的详细信息。

$response = $api->clients->getById(4);
var_dump($response->data);

有关更多信息，请参阅API 文档。

3. Clients::create

创建客户记录并返回其数据。

$response = $api->clients->create([
    'name' => 'SuperFaktúra s.r.o',
]);
var_dump($response->data);

有关更多信息，请参阅API 文档。

4. Clients::update

更新现有客户记录并返回其数据。

$response = $api->clients->update(
    id: 1,
    data: [
        'name' => 'SuperFaktúra s.r.o',
    ]
);
var_dump($response->data);

有关更多信息，请参阅API 文档。

5. Clients::delete

删除现有客户。

$api->clients->delete(1);

有关更多信息，请参阅API 文档。

客户的联系人

1. Client\Contact\Contacts::getAllByClientId

返回给定客户 ID 的联系人列表。

$response = $api->clients->contacts->getAllByClientId(1);
var_dump($response->data);

有关更多信息，请参阅API 文档。

2. Client\Contact\Contacts::create

创建联系人并返回其数据。

$response = $api->clients->contacts->create(
    client_id: 1,
    contact: [
        'name' => 'Joe Doe',
        'email' => 'joe@superfaktura.sk',
    ],
);
var_dump($response->data);

有关更多信息，请参阅API 文档。

3. Client\Contact\Contacts::delete

删除现有的联系人。

$api->clients->contacts->delete(1);

有关更多信息，请参阅API 文档。

国家

1. Countries::getAll

返回可用的国家列表。

$response = $api->countries->getAll();
var_dump($response->data);

有关更多信息，请参阅API 文档。

支出

1. Expenses::getAll

返回根据给定查询对象筛选的支出列表。

$response = $api->expenses->getAll(
    new \SuperFaktura\ApiClient\UseCase\Expense\ExpensesQuery(
        full_text: 'SuperFaktura',
        type: \SuperFaktura\ApiClient\Contract\Expense\ExpenseType::INVOICE,
        created: new \SuperFaktura\ApiClient\Filter\TimePeriod(
            period: \SuperFaktura\ApiClient\Filter\TimePeriodEnum::THIS_YEAR
        ),
    )
);
var_dump($response->data);

有关更多信息，请参阅API 文档。

2. Expenses::getById

返回支出的详细信息。

$response = $api->expenses->getById(1);
var_dump($response->data);

有关更多信息，请参阅API 文档。

3. Expenses::getAllCategories

返回可用的支出类别。

$response = $api->expenses->getAllCategories();
var_dump($response->data);

有关更多信息，请参阅API 文档。

4. Expenses::create

创建支出并返回其数据。

$response = $api->expenses->create(
    expense: [
        'name' => 'Foo bar',
        'currency' => \SuperFaktura\ApiClient\UseCase\Money\Currency::EURO,
    ],
    items: [
        [
            'description' => 'description of item 1',
            'name' => 'item 1',
            'tax' => 20,
            'unit_price' => 10,
        ]
    ],
    client: [
        'ico' => '46655034',
    ],
    extra: ['vat_transfer' => 1],
    tags: [1, 2],
);
var_dump($response->data);

有关更多信息，请参阅API 文档。

5. Expenses::update

更新现有支出并返回其数据。

$response = $api->expenses->update(
    id: 1,
    expense: [
        'name' => 'Foo',
    ],
);
var_dump($response->data);

有关更多信息，请参阅API 文档。

6. Expenses::delete

删除现有支出。

$api->expenses->delete(1);

有关更多信息，请参阅API 文档。

支出付款

1. Expense\Payment\Payments:create

创建新的支出付款并返回其数据。

$response = $api->expenses->payments->create(
    id: 95,
    payment: new \SuperFaktura\ApiClient\UseCase\Expense\Payment\Payment(
        amount: 10,
        currency: \SuperFaktura\ApiClient\UseCase\Money\Currency::EURO,
        payment_type: \SuperFaktura\ApiClient\Contract\PaymentType::CASH,
    ),
);
var_dump($response->data);

更多信息请查阅API文档。

2. Expense\Payment\Payments:delete

删除现有的费用支付。

$api->expenses->payments->delete(1);

更多信息请查阅API文档。

发票

1. Invoices::getById

返回发票的详细信息。

$response = $api->invoices->getById(1);
var_dump($response->data);

更多信息请查阅API文档。

2. Invoices::getByIds

返回多个发票的详细信息。

$response = $api->invoices->getByIds([1,2,3]);
var_dump($response->data);

更多信息请查阅API文档。

3. Invoices::getAll

返回根据给定查询对象过滤的发票列表。

$query = new \SuperFaktura\ApiClient\UseCase\Invoice\InvoicesQuery(
    sort: new \SuperFaktura\ApiClient\Filter\Sort('created', \SuperFaktura\ApiClient\Filter\SortDirection::DESC),
    client_id: 172,
    created: new \SuperFaktura\ApiClient\Filter\TimePeriod(
        \SuperFaktura\ApiClient\Filter\TimePeriodEnum::FROM_TO,
            new DateTimeImmutable('2023-11-01'),
            new DateTimeImmutable('2023-11-08'),
    ),
);
$response = $api->invoices->getAll($query);
var_dump($response->data);

更多信息请查阅API文档。

4. Invoices::downloadPdf

返回发票的PDF导出。

$response = $api->invoices->downloadPdf(372, \SuperFaktura\ApiClient\Contract\Language::SLOVAK);
file_put_contents(__DIR__ . '/invoice.pdf', $response->data);

更多信息请查阅API文档。

5. Invoices::create

创建发票并返回其数据。

$response = $api->invoices->create(
    invoice: [
        'name' => 'Test API',
        'variable' => '12345',
    ],
    items: [
        [
            'name' => 'item name',
            'description' => 'item description',
            'tax' => 20,
            'unit_price' => 10,
        ],
    ],
    client: [
        'name' => 'Client name',
        'ico' => '44981082',
        'comment' => 'Client comment',
        'update_addressbook' => 1,
    ],
    settings: [
        'language' => \SuperFaktura\ApiClient\Contract\Language::SLOVAK,
        'signature' => true,
    ],
    extra: [
        'pickup_point_id' => 23,
    ],
    my_data: [
        'address' => 'Fiktivna 1',
        'business_register' => "-",
        'city' => 'Prague',
        'company_name' => 'MyData Inc.',
        'country_id' => 191,
        'dic' => 'SK99999999',
        'ic_dph' => 'ABCDE',
        'zip' => '999 88',
    ],
    tags: [4],
);
var_dump($response->data);

更多信息请查阅API文档。

6. Invoices::update

更新现有的发票并返回其数据。

$response = $api->invoices->update(
    id: 1,
    invoice: [
        'name' => 'Test API updated',
        'variable' => '12345',
    ],
    items: [
        [
            'name' => 'item name',
            'description' => 'item description',
            'tax' => 20,
            'unit_price' => 10,
        ],
    ],
    client: [
        'name' => 'Client name',
        'ico' => '44981082',
        'comment' => 'Client comment',
        'update_addressbook' => 1,
    ],
    settings: [
        'language' => \SuperFaktura\ApiClient\Contract\Language::SLOVAK,
        'signature' => true,
    ],
    extra: [
        'pickup_point_id' => 23,
    ],
    my_data: [
        'address' => 'Fiktivna 1',
        'business_register' => "-",
        'city' => 'Prague',
        'company_name' => 'MyData Inc.',
        'country_id' => 191,
        'dic' => 'SK99999999',
        'ic_dph' => 'ABCDE',
        'zip' => '999 88',
    ],
    tags: [4],
);
var_dump($response->data);

更多信息请查阅API文档。

7. Invoices::delete

删除现有的发票。

$api->invoices->delete(1);

更多信息请查阅API文档。

8. Invoices::changeLanguage

更改现有发票的语言。

$api->invoices->changeLanguage(1, \SuperFaktura\ApiClient\Contract\Language::CZECH);

更多信息请查阅API文档。

9. Invoices::markAsSent

切换发票已发送状态。

$api->invoices->markAsSent(1);

更多信息请查阅API文档。

10. Invoices::markAsSentViaEmail

将发票标记为通过电子邮件发送。

$api->invoices->markAsSentViaEmail(1, 'test@example.com', 'Subject', 'Message');

更多信息请查阅API文档。

11. Invoices::sendViaEmail

通过电子邮件发送发票。

$email = new \SuperFaktura\ApiClient\UseCase\Invoice\Email(
    email: 'test@example.com',
    pdf_language: \SuperFaktura\ApiClient\Contract\Language::CZECH,
    bcc: ['test2@example.com'],
    cc: ['test3@example.com'],
    subject: 'Subject of email',
    message: 'Message',
);
$api->invoices->sendViaEmail(1, $email);

更多信息请查阅API文档。

12. Invoices::sendViaPostOffice

$address = new \SuperFaktura\ApiClient\UseCase\Invoice\Address(
    name: 'John Doe',
    address: 'Vymyslena 1',
    city: 'Bratislava',
    country_id: 191,
    state: 'Slovakia',
    zip: '99999',
);
$api->invoices->sendViaPostOffice(372, $address);

更多信息请查阅API文档。

Invoice\Items

1. Invoice\Item::delete

删除给定ID的发票项。

$api->invoices->items->delete(1, [1,2,3]);

更多信息请查阅API文档。

Invoice\Payments

1. Invoice\Payment::markAsUnPayable

将发票标记为“将不会支付”。

$api->invoices->payments->markAsUnPayable(1);

更多信息请查阅API文档。

2. Invoice\Payment::create

向发票添加付款。

$payment = new \SuperFaktura\ApiClient\UseCase\Invoice\Payment\Payment(
    amount: 6.00,
    currency: \SuperFaktura\ApiClient\UseCase\Money\Currency::EURO,
    payment_type: \SuperFaktura\ApiClient\Contract\PaymentType::CARD,
    document_number: '123',
    payment_date: new DateTimeImmutable('now'),
);
$api->invoices->payments->create(1, $payment);

更多信息请查阅API文档。

3. Invoice\Payment::delete

从发票中删除付款。

$api->invoices->payments->delete(123);

更多信息请查阅API文档。

相关文档

1. RelatedDocuments::link

在两个文档之间添加链接。

$relation = new \SuperFaktura\ApiClient\UseCase\RelatedDocument\Relation(
    parent_id: 1,
    parent_type: \SuperFaktura\ApiClient\Contract\RelatedDocument\DocumentType::INVOICE,
    child_id: 1,
    child_type: \SuperFaktura\ApiClient\Contract\RelatedDocument\DocumentType::EXPENSE,
);
$response = $api->related_documents->link($relation);
var_dump($response->data);

更多信息请查阅API文档。

2. RelatedDocuments::unlink

删除两个文档之间的链接。

$api->related_documents->unlink(1);

更多信息请查看API 文档。

导出

1. Exports::exportInvoices

以可能的配置导出多个发票。

$response = $api->exports->exportInvoices(
    [1,2,3],
    \SuperFaktura\ApiClient\Contract\Export\Format::PDF,
    new \SuperFaktura\ApiClient\UseCase\Export\PdfExportOptions(
        language: \SuperFaktura\ApiClient\Contract\Language::SLOVAK,
        hide_signature: true,
    ),
);
var_dump($response->data);

2. Exports::getStatus

返回导出的进度。

$response = $api->exports->getStatus(1);
var_dump($response->data);

3. Exports::download

下载完成的导出。

$response = $api->exports->download(1);
file_put_contents(__DIR__ . '/export.zip', $response->data);

库存项目

1. Stock\Items::create

创建一个新的库存项目。

$response = $api->stock_items->create([
    'name' => 'Cake - red velvet',
    'sku'  => 'CK-RV',
    'unit_price' => 30.99,
    'purchase_unit_price' => 39.99,
]);
var_dump($response->data);

更多信息请查看API 文档。

2. Stock\Items::getById

返回库存项目的详细信息。

$response = $api->stock_items->getById(1);
var_dump($response->data);

更多信息请查看API 文档。

3. Stock\Items::getAll

返回根据给定查询对象过滤的库存项目列表。

$query = new \SuperFaktura\ApiClient\Contract\Stock\ItemsQuery(
    price_from: 30.99,
    price_to: 39.99,
);
$response = $api->stock_items->getAll($query);
var_dump($response->data);

更多信息请查看API 文档。

4. Stock\Items::update

更新现有的库存项目。

$response = $api->stock_items->update(1, [
    'name' => 'Updated name',
]);
var_dump($response->data);

更多信息请查看API 文档。

5. Stock\Items::delete

删除现有的库存项目。

$api->stock_items->delete(1);

更多信息请查看API 文档。

库存变动

1. Stock\Movements::create

为现有的库存项目ID创建多个库存日志。

$response = $api->stock_items->movements->create(1, [
    ['quantity' => 5, 'note' => 'Restocking the supplies'],
    ['quantity' => -5, 'note' => 'I must eat something for dinner'],
]);
var_dump($response->data);

更多信息请查看API 文档。

2. Stock\Movements::createWithSku

为现有的库存项目SKU创建多个库存日志。

$response = $api->stock_items->movements->createWithSku('CK-RV', [
    ['quantity' => 5, 'note' => 'Restocking the supplies'],
    ['quantity' => -5, 'note' => 'I must eat something for dinner'],
]);
var_dump($response->data);

更多信息请查看API 文档。

标签

1. Tags::getAll

返回标签列表。

$response = $api->tags->getAll();
var_dump($response->data);

更多信息请查看API 文档。

2. Tags::create

创建一个标签并返回其数据。

$response = $api->tags->create('my-tag');
var_dump($response->data);

更多信息请查看API 文档。

3. Tags::update

更新现有的标签并返回其数据。

$response = $api->tags->update(1, 'my-updated-tag');
var_dump($response->data);

更多信息请查看API 文档。

4. Tags::delete

删除现有的标签。

$api->tags->delete(1);

更多信息请查看API 文档。

枚举

• 市场URI
• 语言
• 货币
• 配送类型
• 费用类型
• 费用状态
• 发票状态
• 发票类型
• 支付类型
• 时间过滤器常量

使用 .env 文件进行授权

1. 创建 .env 文件

SF_APICLIENT_EMAIL=test@example.com
SF_APICLIENT_KEY=YOUR_APIKEY
SF_APICLIENT_APP_TITLE='Example s.r.o.'
SF_APICLIENT_COMPANY_ID=1

然后在使用代码中引用它

$api = new \SuperFaktura\ApiClient\ApiClient(
    new \SuperFaktura\ApiClient\Authorization\EnvFileProvider(__DIR__ . '/.env'),
    'https://moja.superfaktura.sk',
);