README

对 wFirma API 的高级别实现。提供面向对象的 SDK 来操作 wFirma 的多数模块。

安装

使用 composer

composer require webit/w-firma-api

对于 PHP 5.4 和 7.0，使用 ^1.0 版本。

使用方法

当前版本的包提供对以下模块的全面支持

• company_accounts
• contractors
• declaration_countries
• invoice_deliveries
• invoice_descriptions
• invoicecontents
• invoices
• payments
• notes
• series
• tags
• translation_languages
• vat_contents
• vat_codes
• vat_moss_details

配置注解注册表

如果您使用 AnnotationRegistry 2.0，则不需要此步骤。

<?php
use Doctrine\Common\Annotations\AnnotationRegistry;
$loader = include __DIR__.'/vendor/autoload.php'; // composer's autoload.php
AnnotationRegistry::registerLoader(array($loader, 'loadClass'));

身份验证

库支持

• ApiKeysAuth
• BasicAuth (已弃用)

ApiKeyAuth

<?php
use Webit\WFirmaSDK\Auth\ApiKeysAuth;

$auth = new ApiKeysAuth('your-access-key', 'your-secret-key', 'your-app-key', $companyId = 1123); // $companyId is optional

要获取您的 API 密钥，请参阅官方文档： https://doc.wfirma.pl/#autoryzacja

BasicAuth (已弃用)

此方法将不再由 wFirma 支持。

<?php
use Webit\WFirmaSDK\Auth\BasicAuth;

$auth = new BasicAuth('your-user-name', 'your-password', $companyId = 1123); // $companyId is optional

ApiFactory

要为给定模块创建 API，请使用 ModuleApiFactory。

<?php

use Webit\WFirmaSDK\Entity\ModuleApiFactory;
use Webit\WFirmaSDK\Entity\EntityApiFactory;

$entityApiFactory = new EntityApiFactory();
$entityApi = $entityApiFactory->create($auth);

$apiFactory = new ModuleApiFactory($entityApi);

模块 API

每个主要模块都有自己的 API 实例，公开支持的方法。

• 公司账户：find、findAll、get、count
• 承包商：add、edit、delete、find、findAll、get、count
• 申报国家：find、findAll、get、count
• 商品：add、edit、delete、find、get
• 发票交货：add、delete、find、findAll、get、count
• 发票描述：find、findAll、get、count
• 发票：add、edit、delete、find、findAll、get、count、fiscalise、unfiscalise、download、send
• 付款：add、edit、delete、find、findAll、get
• 笔记：add、edit、delete、find、findAll、get、count
• 序列：add、edit、delete、find、findAll、get、count
• 标签：add、edit、delete、find、findAll、get、count
• 翻译语言：find、findAll、get、count
• 增值税代码：find、findAll、get、count

Find / FindAll / Count API

公开 find / findAll / count 方法的 API 接受可选的 参数 参数。

<?php
use Webit\WFirmaSDK\Entity\Parameters\Parameters;
use Webit\WFirmaSDK\Entity\Parameters\Conditions;
use Webit\WFirmaSDK\Entity\Parameters\Order;
use Webit\WFirmaSDK\Entity\Parameters\Pagination;
use Webit\WFirmaSDK\Entity\Parameters\Fields;

$parameters = Parameters::findParameters(
    Conditions::or(
        Conditions::eq('name', 'FA/'),
        Conditions::gt('id', '20')
    ),
    Order::ascending("name")->thenDescending("created"), // optional - ordering
    Pagination::create(20, 2), // optional - limit, page no
    Fields::fromArray(["id", "name"]) // optional - subset of fields to select
);

$seriesApi = $apiFactory->seriesApi();

$series = $seriesApi->find($parameters); // returns array of 20 Series (page 2)

// returns EntityIterator, allows to iterate over all the matching Series loaded in batches of 20
$series = $seriesApi->findAll($parameters);
/**
* @var int $i
* @var \Webit\WFirmaSDK\Series\Series $seriesItem */
foreach ($series as $i => $seriesItem) {
    // do some stuff on ALL the matching elements
}

$seriesCount = $seriesApi->count($parameters); // return number of matching series

InvoicesApi

<?php
use Webit\WFirmaSDK\Contractors\Contractor;
use Webit\WFirmaSDK\Contractors\InvoiceAddress;
use Webit\WFirmaSDK\Invoices\InvoicesContent;
use Webit\WFirmaSDK\Goods\GoodId;
use Webit\WFirmaSDK\Invoices\Payment;
use Webit\WFirmaSDK\Payments\PaymentMethod;

/** @var \Webit\WFirmaSDK\Invoices\InvoicesApi $api */
$api = $apiFactory->invoicesApi();

// add a new invoice
$invoice = \Webit\WFirmaSDK\Invoices\Invoice::forContractor(
    new Contractor(
        'client name',
        'alt name',
        '1234565432', // vat no
        null, // regon
        new InvoiceAddress(
            'ul. Mokra 12',
            '01-006',
            'Warszawa',
            'PL'
        )
    ),
    Payment::create(PaymentMethod::transfer())
);

$invoice->addInvoiceContent(
    InvoicesContent::fromGoodId(
        GoodId::create(123),
        3,
        123.32,
        23
    )
);

$invoice->addInvoiceContent(
    InvoicesContent::fromName(
        'some stuff',
        'szt.',
        3,
        123.32,
        23
    )
);

$invoice = $api->add($invoice);

// get invoice by id
$invoice = $api->get(\Webit\WFirmaSDK\Invoices\InvoiceId::create(123));

// edit the invoice
$invoice->changePayment(
    $invoice->payment()->withPaymentDate(new \DateTime())
);

// do some more edits
$invoice = $api->edit($invoice);

// delete the invoice
$api->delete($invoice->id());

ContractorsApi

<?php
use Webit\WFirmaSDK\Contractors\Contractor;

/** @var \Webit\WFirmaSDK\Contractors\ContractorsApi $api */
$api = $apiFactory->contractorsApi($auth);

// add a new contractor
$contractor = new Contractor('my-new-contractor');
$contractor = $api->add($contractor);

// edit the contractor
$contractor->rename('new name', 'new alt name');
$contractor = $api->edit($contractor);

// delete the contractor
$api->delete($contractor->id());

// get contractor by id
$contractor = $api->get(\Webit\WFirmaSDK\Contractors\ContractorId::create(123));

进一步开发

欢迎添加任何其他模块支持。

通过 VatCodeIdRepository 从增值税率代码获取 VatCodeId

使用提供的自定义静态映射

use Webit\WFirmaSDK\Vat\Repository\VatCodeIdRepositoryFactory;

$repository = VatCodeIdRepositoryFactory::createWithMap(
  ['23' => 222, '8' => 223] // provide your static ID mapping
);

$repository->getByCode('23'); // returns new VatCodeId(222);

使用 API 提供的缓存映射

请注意，您需要将 psr/simple-cache-implementation 添加到您的 composer.json 文件中。以下示例建议使用 symfony/cache。

use Webit\WFirmaSDK\Vat\Repository\VatCodeIdRepositoryFactory;
use Symfony\Component\Cache\Adapter\FilesystemAdapter;
use Symfony\Component\Cache\Psr16Cache;

$repository = VatCodeIdRepositoryFactory::createWithApi(
  $api = $apiFactory->vatCodesApi(),
  new Psr16Cache(new FilesystemAdapter()) // use cache adapter of your choice (no cache by default)
);

$repository->getByCode('23'); // returns new VatCodeId(222);

测试

cp phpunit.xml.dist phpunit.xml
vim phpunit.xml // edit your username and password

docker-compose run --rm composer
docker-compose run --rm phpunit