konekt / factureaza-sdk
SDK for factureaza.ro API
Fund package maintenance!
fulopattila122
Installs: 2 006
Dependents: 0
Suggesters: 0
Security: 0
Stars: 0
Watchers: 2
Forks: 2
Open Issues: 0
Requires
- php: ^8.1
- guzzlehttp/guzzle: ^7.4
- illuminate/http: ^8.22.1|^9.0|^10.0|^11.0
- konekt/enum: ^3.0|^4.0
- nesbot/carbon: ^2.53.1
Requires (Dev)
- phpunit/phpunit: ^9.5|^10.0
README
This package provides a PHP SDK for interacting with the factureaza.ro GraphQL API.
Installation
The minimum requirement of this package is PHP 8.1.
To install this library in your application, use composer:
composer require konekt/factureaza-sdk
Usage
Live or Sandbox
To connect to the live system, use the connect
method and pass your api key:
$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" // ...
To connect to the sandbox system, use the sandbox
method:
$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" // ...
Time Zone
The factureaza.ro API returns dates in the Romanian time zone (Europe/Bucharest). This SDK returns dates in that timezone by default.
If you want dates to be returned in UTC, call the useUTCTime()
method:
$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
Create an Invoice
$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), // }, // }
Document States
Invoices and other documents can have 4 states: draft
, open
, closed
, cancelled
.
When creating an Invoice, it will have the open
state by default.
If you want to create an invoice with a different initial state, use one of the following
methods on the CreateInvoice
class:
asDraft()
asClosed()
asCancelled()
$request = CreateInvoice::inSeries('1061104148')->asDraft(); //... Factureaza::sandbox()->createInvoice($request);
or:
$request = CreateInvoice::inSeries('1061104148')->asClosed(); //... Factureaza::sandbox()->createInvoice($request);
Retrieve Invoice PDF
The PDF of an Invoice can be retrieved in base64 encoded format:
$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));
Retrieve a Single Invoice
Unique invoices can be retrieved by id:
$invoiceId = '1065254039'; $invoice = Factureaza::connect('your-api-key')->invoice($invoiceId); //=> Konekt\Factureaza\Models\Invoice {#2760
Find Clients
You can retrieve a client either by its Factureaza ID, or by tax number (cod fiscal).
Find a Client by 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), // }, // }
Find a Client By Other Fields
By Tax Number:
$client = Factureaza::sandbox()->clientByTaxNo('13548146');
By E-mail address:
$client = Factureaza::sandbox()->clientByEmail('client@email.ro');
By name:
$client = Factureaza::sandbox()->clientByName('Client SRL');
Create a Client
$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 identifies clients based on their taxNo
(uid
in Factureaza API) field,
which represents either the tax number (CIF/CUI) of a company or the
personal identification number (CNP) of a natural person.
If you try to create a client with a taxNo
that already exists, a ClientExistsException
is thrown.