webit / w-firma-api
wFirma.pl API
2.6.1
2023-07-01 09:00 UTC
Requires
- php: >=7.1
- jms/serializer: ^1.0.0|^2.0.0|^3.0.0
- kriswallsmith/buzz: ^1.0.0
- nyholm/psr7: ^1.0.0
- psr/log: ^1.0.2 || ^2.0 || ^3.0
- psr/simple-cache: ^1.0.1
Requires (Dev)
- fakerphp/faker: ^1.17.0
- monolog/monolog: ^1.10.0
- nette/php-generator: ^3.5.4
- phpunit/phpunit: ^7.3.2
Suggests
- symfony/cache: To use VatCodeIdResolver with caching feature
This package is auto-updated.
Last update: 2024-09-05 12:27:13 UTC
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