giorgigrdzelidze / laravel-rsge
Laravel client for Georgian Revenue Service (rs.ge) e-services: cash register Z-reports and electronic waybills.
Requires
- php: ^8.2
- ext-mbstring: *
- ext-simplexml: *
- ext-soap: *
- illuminate/contracts: ^12.0 || ^13.0
- illuminate/support: ^12.0 || ^13.0
- psr/log: ^3.0
Requires (Dev)
- laravel/pint: ^1.18
- mockery/mockery: ^1.6
- orchestra/testbench: ^10.0 || ^11.0
- phpstan/phpstan: ^2.0
- phpunit/phpunit: ^11.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-17 13:14:29 UTC
README
π¬πͺ Laravel RSGE
A production-grade Laravel package for the Georgian Revenue Service (rs.ge) SOAP API. Cash register Z-reports and electronic waybills today β taxpayer info and more to come.
β¨ Features
- π§Ύ Cash Register Z-Reports β fetch daily Z-report details & sums
- π Electronic Waybills β save, activate, close, cancel, read, list and print waybills, as any of the taxpayer's service users
- π Basic Auth β username/password authentication out of the box
- π Retry with Backoff β automatic retry on transient rs.ge system errors
- π§ͺ FakeTransport β deterministic unit testing without hitting rs.ge
- ποΈ Extensible Architecture β add new rs.ge services in minutes
- π‘οΈ Typed Exceptions β
RsgeAuthenticationException,RsgeNotFoundException,RsgeSystemException,RsgeTransportException,RsgeWaybillException,RsgeUnreadMessageException,RsgeConfigurationException - π¦ Zero Config β Laravel auto-discovery, sensible defaults
π Requirements
| Requirement | Version |
|---|---|
| PHP | 8.2+ |
| Laravel | 12.x / 13.x |
| Extensions | ext-soap, ext-simplexml |
π Installation
composer require giorgigrdzelidze/laravel-rsge
Publish the config file (optional):
php artisan vendor:publish --tag=rsge-config
βοΈ Configuration
Add to your .env:
RSGE_USERNAME=your_username RSGE_PASSWORD=your_password
π§ Optional settings
RSGE_CASH_REGISTER_WSDL=https://services.rs.ge/taxservice/taxpayerservice.asmx?WSDL RSGE_WAYBILL_WSDL=https://services.rs.ge/WayBillService/WayBillService.asmx?WSDL RSGE_LOGGING_ENABLED=true RSGE_LOG_CHANNEL=stack
π Usage
π§Ύ Fetch Z-Report Details
use Rsge\Laravel\Facades\Rsge; $reports = Rsge::cashRegister()->getZReportDetails( startDate: '2025-01-01', endDate: '2025-01-31', ); foreach ($reports as $report) { echo "{$report->deviceNumber}: {$report->paidAmount} GEL ({$report->quantity} receipts)\n"; }
π Using Carbon Dates
use Carbon\CarbonImmutable; use Rsge\Laravel\Facades\Rsge; $start = CarbonImmutable::now()->startOfMonth(); $end = CarbonImmutable::now()->endOfMonth(); $reports = Rsge::cashRegister()->getZReportDetails($start, $end);
π Electronic Waybills
The waybill service signs in with a service user (su / sp), made on the rs.ge portal. Its name has the form NAME:TIN.
RSGE_WAYBILL_SU="SHOP1:206322102" RSGE_WAYBILL_SP=secret
use Rsge\Laravel\Facades\Rsge; use Rsge\Laravel\Services\Waybill\Enums\WaybillType; use Rsge\Laravel\Services\Waybill\Requests\GoodsLine; use Rsge\Laravel\Services\Waybill\Requests\WaybillDraft; $waybills = Rsge::waybill(); $saved = $waybills->save(new WaybillDraft( type: WaybillType::WithoutTransport, goods: [ new GoodsLine(name: 'α€ααα₯αα α HB', quantity: 2, price: 1.5, amount: 3, barCode: '02345678'), ], buyerTin: '206322102', buyerName: 'αα§αααααα', startAddress: 'αααααα‘α, α’αα‘α’αα‘ 1', endAddress: 'αααααα‘α, α’αα‘α’αα‘ 1', comment: 'R-2026-0007', )); $number = $waybills->activate($saved->id); // the waybill number; from here it can only be cancelled $waybill = $waybills->get($saved->id); // status, number, goods, S_USER_ID β¦ $pdf = $waybills->printPdf($saved->id); $waybills->close($saved->id); // or: $waybills->cancel($saved->id, 'α¨ααͺααααα αααααα¬αα α'); // a waybill that is only saved: $waybills->delete($saved->id);
Acting as another service user, for instance the member of staff who issues the waybill (rs.ge records it on the waybill as S_USER_ID):
use Rsge\Laravel\Auth\ServiceUserCredentials; $asStaff = Rsge::waybill(new ServiceUserCredentials('NINO:206322102', $password)); $check = $asStaff->checkServiceUser(); // valid, unId, serviceUserId
Other operations: serviceUsers($mainUser, $mainPassword), list(WaybillFilter), getByNumber(), types(), units(), transportTypes(), errorCodes(), nameFromTin(), whatIsMyIp(), serverTime().
What rs.ge or the network refuses is an RsgeException carrying rs.ge's code and its Georgian text where there is one (errorCode, errorDescription). Input the package itself cannot send β a name with nothing readable in it, a number that is not one β is an \InvalidArgumentException when the GoodsLine or WaybillDraft is made:
| Exception | When |
|---|---|
RsgeWaybillException |
rs.ge refuses the operation with one of its codes; lineErrors names the goods lines at fault |
RsgeUnreadMessageException (a RsgeWaybillException) |
a mandatory message on the portal has to be read first (-1061); rs.ge has no web-service call for it, someone has to open the portal |
RsgeAuthenticationException (not a RsgeWaybillException) |
wrong service user or password (-100) |
RsgeConfigurationException |
no service user is configured; nothing was sent |
RsgeTransportException |
the call did not get through |
Dates go to rs.ge and come back as Tbilisi time, whatever timezone the application keeps: pass any DateTimeInterface, and the dates of a Waybill are moments in Asia/Tbilisi.
Credentials are not meant to travel: ServiceUserCredentials hides its password from dumps and JSON and refuses to be serialized, so pass an id to a queued job and load the password there.
In an application's tests, replace the service so that nothing reaches rs.ge:
use Rsge\Laravel\Auth\ServiceUserCredentials; use Rsge\Laravel\Services\Waybill\WaybillService; use Rsge\Laravel\Transport\FakeTransport; $transport = new FakeTransport; $this->app->instance(WaybillService::class, new WaybillService($transport, new ServiceUserCredentials('TEST:206322102', 'x')));
Rsge::waybill($credentials) keeps that transport. Binding Transport::class alone replaces only the cash register's transport.
Things rs.ge does that are easy to trip over:
create_service_useranswerstrueand creates nothing; service users are made on the portal.get_service_usersneeds the taxpayer's main user and password, not a service user.- A list (
get_waybills) needs a creation-date range of at most 72 hours and leaves deleted waybills out. ACTIVATE_DATEis filled as soon as a waybill is saved;Waybill::$activatedAtis set only once the waybill has a number.- Roles and permissions of portal users, and portal messages, are not available through the service.
π‘οΈ Exception Handling
use Rsge\Laravel\Exceptions\RsgeAuthenticationException; use Rsge\Laravel\Exceptions\RsgeNotFoundException; use Rsge\Laravel\Exceptions\RsgeSystemException; use Rsge\Laravel\Exceptions\RsgeTransportException; use Rsge\Laravel\Facades\Rsge; try { $reports = Rsge::cashRegister()->getZReportDetails('2025-01-01', '2025-01-31'); } catch (RsgeAuthenticationException $e) { // β Invalid username or password } catch (RsgeNotFoundException $e) { // π No data for the given date range } catch (RsgeSystemException $e) { // β οΈ Transient rs.ge system error } catch (RsgeTransportException $e) { // π Network or SOAP protocol failure }
π Retry on Transient Errors
use Rsge\Laravel\Facades\Rsge; use Rsge\Laravel\Support\Retry; $reports = Retry::onSystemError( operation: fn () => Rsge::cashRegister()->getZReportDetails('2025-01-01', '2025-01-31'), attempts: 3, baseDelayMs: 200, );
ποΈ Architecture
src/
βββ Contracts/ # π Interfaces (Transport, Credentials, Service)
βββ Auth/ # π Authentication (BasicCredentials)
βββ Transport/ # π SoapTransport + FakeTransport for testing
βββ Exceptions/ # π₯ Typed exceptions mapped from rs.ge error codes
βββ Support/ # π οΈ ErrorMapper, Retry helper
βββ Services/
β βββ AbstractService # π§© Base class for all services
β βββ CashRegister/ # π§Ύ Z-Report service, DTOs, request objects
β βββ Waybill/ # π Waybill service, DTOs, request objects, enums
βββ Facades/ # π Rsge facade
βββ Rsge.php # π Manager (service factory)
βββ RsgeServiceProvider # π¦ Laravel service provider
πΊοΈ Roadmap
| Service | SOAP Method | Status |
|---|---|---|
| Cash Register Z-Report Details | Get_Z_Report_Details |
β Done |
| Electronic waybills | save_waybill, del_waybill, get_waybill, get_waybills, chek_service_user, get_service_users, lists |
β Done, checked against rs.ge |
| Electronic waybills | send_waybill, send_waybil_vd, close_waybill, ref_waybill, get_print_pdf |
β Done, live check pending |
| Cash Register Z-Report Sum | Get_Z_Report_Sum |
π Planned |
| Taxpayer Public Info | GetTPInfoPublic |
π Planned |
| Taxpayer Public Contacts | GetTPInfoPublicContacts |
π Planned |
| Payer Info | Get_Payer_Info |
π Planned |
| Legal Person Info | Get_LegalPerson_Info |
π Planned |
| Waybill Month Amount | Get_Waybill_Month_Amount |
π Planned |
| Income Amount | Get_Income_Amount |
π Planned |
| Comparison Act | Get_comp_act_new |
π Planned |
| Payer NACE Info | Get_Payer_Nace_Info |
π Planned |
| QuickCash Info | Get_QuickCash_Info |
π Planned |
π§© Adding a New Service
- Create DTOs in
src/Services/YourService/DTOs/withfromSoap()method - Create Requests in
src/Services/YourService/Requests/withtoSoap()method - Create a Service class extending
AbstractService - Register in
RsgeServiceProvideras a singleton - Add accessor to
Rsgemanager + update facade PHPDoc - Write tests using
FakeTransport
π§ͺ Testing & QA
# π Full QA pipeline (lint + static analysis + tests) composer qa # Individual commands composer pint:test # βοΈ Code style (Pint) composer stan # π Static analysis (PHPStan level max) composer test # β Tests (PHPUnit)
Live tests
composer test never talks to rs.ge. A separate suite does, against rs.ge's two published test taxpayers only:
cp phpunit.live.xml.dist phpunit.live.xml # git-ignored; put a test service user in
composer test:live
With RSGE_LIVE_WRITES=1 the suite also saves, activates, closes, cancels and deletes its own test waybills, from one test taxpayer to the other. Before anything else it asks rs.ge which taxpayer the service user belongs to, and stops unless that is one of the two test codes.
π License
MIT β see LICENSE file.
Made with β€οΈ in Georgia π¬πͺ