README

PHP 客户端，用于在线经济系统 SuperFaktúra 的 API。

安装

通过命令行简单安装： composer require rshop/superfaktura

或者添加到 composer.json

{
    "require": {
        "rshop/superfaktura": "~1.0"
    }
}

概述

可以通过 Superfaktura 类创建单个实体。

use Rshop\Synchronization\Superfaktura;

$superfaktura = new Superfaktura('EMAIL', 'API_KEY');

创建发票

可以通过 createInvoice 方法创建新的发票。

$invoice = $superfaktura->createInvoice([
    'name' => 'Názov faktúry',
    'invoice_no_formatted' => '12345'
]);

// parametre je možné nastaviť aj zadaním požadovaného atribútu
$invoice['already_paid'] = true;

可用属性

• already_paid - 发票是否已支付？ true/false
• created - 开具日期
• comment - 评论
• constant - 常量符号
• delivery - 交货日期
• delivery_type - 交货方式，值列表
• deposit - 已支付押金
• discount - 折扣百分比
• due - 到期日期
• estimate_id - 价格报价 ID，发票根据此报价开具
• header_comment - 项目上方文本
• internal_comment - 内部备注，不显示给客户
• invoice_currency - 开具发票的货币。选项：EUR, USD, GBP, HUF, CZK, PLN, CHF, RUB
• invoice_no_formatted - 发票号码
• issued_by - 开具发票的人
• issued_by_phone - 开具发票的电话
• issued_by_email - 开具发票的电子邮件
• name - 发票名称
• payment_type - 付款方式，值列表
• proforma_id - 临时发票 ID，根据此临时发票开具正式发票（正式发票将接受已支付押金的数据）
• rounding - DPH 四舍五入方式：document - 整个文件，item - 每个项目（默认值）
• specific - 特殊符号
• sequence_id - 序列 ID
• tax_document - 这是针对收到的付款的税务文件吗？ true/false
• type - 发票类型：regular - 正常发票，proforma - 预付款发票，cancel - 退款，estimate - 报价，order - 订单
• variable - 变量符号

设置客户

可以通过 setClient 方法将客户添加到发票。

$invoice->setClient([
    'name' => 'Meno zákazníka'
]);

// parametre je možné nastaviť aj zadaním požadovaného atribútu
$client = $invoice->getClient();
$client['city'] = 'Mesto';

可用属性

• address - 地址
• bank_account - 银行账户
• city - 城市
• comment - 评论
• country_id - 国家 ID，国家列表
• country - 国家名称
• delivery_address - 交货地址
• delivery_city - 交货城市
• delivery_country - 交货国家
• delivery_country_id - 交货国家 ID
• delivery_name - 交货客户名称
• delivery_zip - 交货邮政编码
• dic - 税号
• email - 电子邮件
• fax - 传真
• ic_dph - DPH 编号
• ico - 组织编号
• name - 客户名称
• phone - 电话
• zip - 邮政编码

添加项目

可以通过 addItem 方法将项目添加到发票。

$invoice->addItem([
    'name' => 'Názov položky',
    'quantity' => 1,
    'unit_price' => 40.83,
    'tax' => 20
]);

可用属性

• name - 项目名称
• description - 描述
• quantity - 数量
• unit - 单位
• unit_price - 不含增值税的价格
• tax - 增值税税率百分比
• stock_item_id - 库存项目 ID
• sku - 库存标识符

保存

try {
    $invoice->save();

    // $invoice obsahuje všetky parametre uloženej faktúry
    var_dump($invoice['token'], $invoice->getSummary());
}
catch (Exception $e) {
    // chyby, ktoré nastali pri komunikácii, je možné získať metódou getErrors
    var_dump($e->getErrors());
}

获取现有发票

可以通过其 ID 使用 getInvoice 方法下载现有发票。

$invoice = $superfaktura->getInvoice(616575);

编辑发票

在编辑读取的发票时，可以像创建新发票一样进行操作。

// zmena variabilného symbolu faktúry
$invoice['variable'] = '12345';

// pridanie položky
$invoice->addItem([
    'name' => 'Názov pridávanej položky',
    'quantity' => 2,
    'unit_price' => 5.11,
    'tax' => 20
]);

try {
    $invoice->save();

    // $invoice obsahuje všetky parametre uloženej faktúry
    var_dump($invoice['token'], $invoice->getSummary());
}
catch (Exception $e) {
    // chyby, ktoré nastali pri komunikácii, je možné získať metódou getErrors
    var_dump($e->getErrors());
}

标记发票为已发送

使用markAsSent方法标记。如果发票由自己的系统发送，但您希望在SuperFaktúre中记录此次发送，则非常有用。

$invoice->markAsSent([
    'email' => 'email@zakaznika.sk'
]);

可用属性

• email - 发送发票的电子邮件地址
• subject - 电子邮件的主题
• body - 电子邮件正文

通过电子邮件发送发票

使用sendByEmail方法发送。未设置的属性将根据SuperFaktúre的设置自动设置。

$invoice->sendByEmail([
    'to' => 'email@zakaznika.sk'
]);

可用属性

• to - 发送发票的电子邮件地址（必填项）
• cc - 抄送（array）
• bcc - 密送（array）
• subject - 电子邮件的主题
• body - 电子邮件正文

支付发票

使用pay方法添加付款到发票。

$invoice->pay([
    amount' => 10.34
]);

可用属性

• amount - 已支付金额（必填项）
• currency - 付款货币，默认为EUR
• date - 付款日期，默认为当前日期
• payment_type - 付款方式，默认为转账，可能的值有cash, transfer, credit, paypal, cod

获取PDF链接

可以通过getPdf方法获取可以下载PDF发票的地址。

$invoice->getPdf();

删除发票

可以通过delete方法删除发票。

$invoice->delete();

启动测试

为了测试，首先需要将TestConfig.php.tpl文件复制到TestConfig.php，并填写测试的email和API密钥。然后通过命令行

$ cd path/to/rshop/superfaktura
$ composer install
$ vendor/bin/phpspec run