README

此包提供了一个用于与 factureaza.ro GraphQL API 交互的 PHP SDK。

安装

此包的最小要求是 PHP 8.1。

要在您的应用程序中安装此库，请使用 composer

composer require konekt/factureaza-sdk

用法

实时或沙盒

要连接到实时系统，请使用 connect 方法并传递您的 API 密钥

$live = Factureaza::connect('api key here');
$live->myAccount();
// => Konekt\Factureaza\Models\MyAccount
//     id: "555000444",
//     name: "yourcompany",
//     companyName: "Your Company SRL",
//     createdAt: "2019-06-06T16:23:34+03:00",
//     updatedAt: "2022-09-13T08:03:29+03:00"
//     ...

要连接到沙盒系统，请使用 sandbox 方法

$sandbox = Factureaza::sandbox();
$sandbox->myAccount();
// => Konekt\Factureaza\Models\MyAccount
//     id: "340138083",
//     name: "sandbox",
//     companyName: "Test Services SRL",
//     createdAt: "2014-06-06T16:23:34+03:00",
//     updatedAt: "2022-09-13T08:03:29+03:00"
//     ...

时区

factureaza.ro API 返回的日期位于罗马尼亚时区（Europe/Bucharest）。此 SDK 默认以该时区返回日期。

如果您希望返回的日期为 UTC，请调用 useUTCTime() 方法

$factureaza = Factureaza::connect('api key');
$factureaza->myAccount()->createdAt->toIso8601String();
// 2014-06-06T16:23:34+03:00

$factureaza->useUtcTime();
$factureaza->myAccount()->createdAt->toIsoString();
// 2014-06-06T13:23:34+00:00

创建发票

$request = CreateInvoice::inSeries('1061104148')
    ->forClient('1064116434')
    ->withEmissionDate('2021-09-17')
    ->addItem(['description' => 'Service', 'price' => 19, 'unit' => 'luna', 'productCode' => '']);

$invoice = Factureaza::sandbox()->createInvoice($request);
//=> Konekt\Factureaza\Models\Invoice {#2760
//     +documentDate: Carbon\CarbonImmutable @1631826000 {#2773
//       date: 2021-09-17 00:00:00.0 Europe/Bucharest (+03:00),
//     },
//     +clientId: "1064116434",
//     +items: [
//       Konekt\Factureaza\Models\InvoiceItem {#2765
//         +description: "Service",
//         +price: 19.0,
//         +unit: "luna",
//         +quantity: 1.0,
//         +productCode: "",
//         +id: "1056077322",
//       },
//     ],
//     +id: "1065254080",
//     +createdAt: Carbon\CarbonImmutable @1665076996 {#2772
//       date: 2022-10-06 20:23:16.0 Europe/Bucharest (+03:00),
//     },
//     +updatedAt: Carbon\CarbonImmutable @1665076996 {#2771
//       date: 2022-10-06 20:23:16.0 Europe/Bucharest (+03:00),
//     },
//   }

文档状态

发票和其他文档可以有 4 种状态：草稿、开启、关闭、取消。

创建发票时，它将默认具有 开启 状态。

如果您想以不同的初始状态创建发票，请使用 CreateInvoice 类中的以下方法之一

asDraft()
asClosed()
asCancelled()

$request = CreateInvoice::inSeries('1061104148')->asDraft();
//...
Factureaza::sandbox()->createInvoice($request);

或

$request = CreateInvoice::inSeries('1061104148')->asClosed();
//...
Factureaza::sandbox()->createInvoice($request);

检索发票 PDF

发票的 PDF 可以以 base64 编码格式检索

$invoiceId = '1234567';
$pdf = Factureaza::connect('your-api-key')->invoiceAsPdfBase64($invoiceId);

// Mind decoding it when you want to save it:

file_put_contents('invoice.pdf', base64_decode($pdf));

检索单个发票

可以通过 ID 检索唯一的发票

$invoiceId = '1065254039';
$invoice = Factureaza::connect('your-api-key')->invoice($invoiceId);
//=> Konekt\Factureaza\Models\Invoice {#2760

查找客户

您可以通过 Factureaza ID 或税号（cod fiscal）检索客户。

通过 Factureaza ID 查找客户

$client = Factureaza::sandbox()->client('1064116434');
//=> Konekt\Factureaza\Models\Client {#2691
//     +name: "CUBUS ARTS S.R.L.",
//     +isCompany: true,
//     +address: "BLD. MIHAI VITEAZU Nr. 7,Ap. 18",
//     +address2: "",
//     +zip: "550350",
//     +city: "SIBIU",
//     +province: "Sibiu",
//     +country: "RO",
//     +email: "office@cubus.ro",
//     +regNo: "J32 /508 /2000",
//     +taxNo: "13548146",
//     +taxNoPrefix: "RO",
//     +id: "1064116434",
//     +createdAt: Carbon\CarbonImmutable @1402061592 {#2708
//       date: 2014-06-06 16:33:12.0 Europe/Bucharest (+03:00),
//     },
//     +updatedAt: Carbon\CarbonImmutable @1402061592 {#2696
//       date: 2014-06-06 16:33:12.0 Europe/Bucharest (+03:00),
//     },
//   }

通过其他字段查找客户

通过税号

$client = Factureaza::sandbox()->clientByTaxNo('13548146');

通过电子邮件地址

$client = Factureaza::sandbox()->clientByEmail('client@email.ro');

通过名称

$client = Factureaza::sandbox()->clientByName('Client SRL');

创建客户

$client = Factureaza::sandbox()->createClient([
    'name' => 'Giovanni Gatto',
    'isCompany' => false,
    'city' => 'Pokyo',
    'address' => 'Mishiaza Vue 72',
]);
//=> Konekt\Factureaza\Models\Client {#2701
//     +name: "Giovanni Gatto",
//     +isCompany: false,
//     +address: "Mishiaza Vue 72",
//     +address2: null,
//     +zip: null,
//     +city: "Pokyo",
//     +province: null,
//     +country: "RO",
//     +email: null,
//     +phone: null,
//     +regNo: null,
//     +taxNo: "",
//     +taxNoPrefix: null,
//     +id: "1064116440",
//     +createdAt: Carbon\CarbonImmutable @1665343572 {#2692
//       date: 2022-10-09 22:26:12.0 Europe/Bucharest (+03:00),
//     },
//     +updatedAt: Carbon\CarbonImmutable @1665343572 {#2722
//       date: 2022-10-09 22:26:12.0 Europe/Bucharest (+03:00),
//     },
//   }

Factureaza 根据客户的 taxNo（Factureaza API 中的 uid）字段来识别客户，该字段表示公司的税号（CIF/CUI）或自然人的个人识别号码（CNP）。

如果您尝试使用已存在的 taxNo 创建客户，则会抛出 ClientExistsException 异常。

konekt / factureaza-sdk

维护者

详情