PHPackages sashalenz/vchasno-kasa-api - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. sashalenz/vchasno-kasa-api ActiveLibrary[API Development](/categories/api) sashalenz/vchasno-kasa-api ========================== Laravel client for Вчасно.Каса Orders API (deferred fiscal receipts / ПРРО) 087PHP Since Apr 26Pushed 1mo agoCompare [ Source](https://github.com/sashalenz/vchasno-kasa-api)[ Packagist](https://packagist.org/packages/sashalenz/vchasno-kasa-api)[ RSS](/packages/sashalenz-vchasno-kasa-api/feed)WikiDiscussions main Synced 1w ago READMEChangelogDependenciesVersions (1)Used By (0) Vchasno.Kasa API — Laravel Package ================================== [](#vchasnokasa-api--laravel-package) [![Latest Version on Packagist](https://camo.githubusercontent.com/0edf02786fa26e53297102f1a80be449dad9beeb59d31c66aaed6a42a35ad568/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f73617368616c656e7a2f76636861736e6f2d6b6173612d6170692e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/sashalenz/vchasno-kasa-api)[![Tests](https://camo.githubusercontent.com/0d398eeed6c723bcbcccbc899f6d20982a5ed03dce1843d57fcfced668a41238/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f73617368616c656e7a2f76636861736e6f2d6b6173612d6170692f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/sashalenz/vchasno-kasa-api/actions/workflows/run-tests.yml)[![PHP Version](https://camo.githubusercontent.com/99ece6cf61d7990975db23add7b957034867366880132a315fa1935694dd5d03/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f73617368616c656e7a2f76636861736e6f2d6b6173612d6170692e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/sashalenz/vchasno-kasa-api)[![License](https://camo.githubusercontent.com/7c88f137b8d2128420228355b4a12d2af3ad77a4bbb8977b1c7057c7e81ba187/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f73617368616c656e7a2f76636861736e6f2d6b6173612d6170692e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/sashalenz/vchasno-kasa-api) Laravel package for integrating with the [Vchasno.Kasa](https://kasa.vchasno.ua) Orders API. Supports deferred fiscal receipts (ETTN) via Nova Poshta, Ukrposhta and Meest, as well as direct cash and IBAN payments. --- Requirements ------------ [](#requirements) - PHP 8.4+ - Laravel 11 / 12 / 13 --- Installation ------------ [](#installation) ``` composer require sashalenz/vchasno-kasa-api ``` Publish the config file: ``` php artisan vendor:publish --tag="vchasno-kasa-config" ``` Add variables to your `.env`: ``` VCHASNO_KASA_TOKEN=your-api-token VCHASNO_KASA_RRO_FN=1234567890 ``` --- Configuration ------------- [](#configuration) ``` // config/vchasno-kasa.php return [ 'token' => env('VCHASNO_KASA_TOKEN'), 'rro_fn' => env('VCHASNO_KASA_RRO_FN'), 'base_url' => env('VCHASNO_KASA_URL', 'https://kasa.vchasno.ua/api/v1'), 'timeout' => 30, 'retry' => [ 'times' => 3, 'sleep' => 150, ], ]; ``` OptionDescription`token`API token from the Vchasno cabinet: Settings → API`rro_fn`Fiscal number of the software cash register (PRRO). Visible in the cabinet or via `GET /api/v1/rro``base_url`Orders API base URL (change only if necessary)--- Usage ----- [](#usage) ### Via Facade [](#via-facade) ``` use Sashalenz\VchasnoKasaApi\Facades\VchasnoKasa; ``` ### Via DI / app() [](#via-di--app) ``` use Sashalenz\VchasnoKasaApi\VchasnoKasaApi; $api = app(VchasnoKasaApi::class); ``` --- Orders API ---------- [](#orders-api) ### 1. Deferred receipt — Nova Poshta (COD) [](#1-deferred-receipt--nova-poshta-cod) The primary use case: the customer pays upon parcel pickup. The receipt is fiscalized automatically when the customer collects the shipment. ``` use Sashalenz\VchasnoKasaApi\Facades\VchasnoKasa; use Sashalenz\VchasnoKasaApi\Data\Requests\Orders\CreatePostalOrderData; use Sashalenz\VchasnoKasaApi\Data\Requests\Orders\GoodItemData; use Sashalenz\VchasnoKasaApi\Enums\PostalType; $order = VchasnoKasa::orders()->createPostal( new CreatePostalOrderData( ttn: '59000123456789', // Nova Poshta tracking number rroFn: config('vchasno-kasa.rro_fn'), tag: "order-{$order->id}-{$shipment->id}", // unique idempotency key postalType: PostalType::NovaPoshta, goods: [ new GoodItemData( name: 'BMW E46 front left headlight', quantity: 1.0, price: 350000, // in kopecks (3500.00 UAH) code: 'SKU-12345', ), ], totalSum: 350000, // in kopecks ) ); echo $order->id; // order ID in Vchasno echo $order->status; // OrderStatus::Created ``` ### 2. Deferred receipt — Ukrposhta / Meest [](#2-deferred-receipt--ukrposhta--meest) ``` use Sashalenz\VchasnoKasaApi\Enums\PostalType; $order = VchasnoKasa::orders()->createPostal( new CreatePostalOrderData( ttn: '0312345678901', rroFn: config('vchasno-kasa.rro_fn'), tag: "order-{$order->id}-ukrposhta", postalType: PostalType::UkrPoshta, // or PostalType::Meest goods: [...], totalSum: 120000, ) ); ``` ### 3. Direct cash / card payment [](#3-direct-cash--card-payment) ``` use Sashalenz\VchasnoKasaApi\Data\Requests\Orders\CreateOrderData; use Sashalenz\VchasnoKasaApi\Enums\PaymentType; $order = VchasnoKasa::orders()->create( new CreateOrderData( rroFn: config('vchasno-kasa.rro_fn'), tag: "cash-order-{$order->id}", goods: [ new GoodItemData(name: 'Rear bumper', quantity: 1.0, price: 180000), ], totalSum: 180000, paymentType: PaymentType::Cash, // or PaymentType::Card ) ); ``` ### 4. IBAN bank transfer [](#4-iban-bank-transfer) ``` use Sashalenz\VchasnoKasaApi\Data\Requests\Orders\CreateIbanOrderData; $order = VchasnoKasa::orders()->createIban( new CreateIbanOrderData( rroFn: config('vchasno-kasa.rro_fn'), tag: "iban-payment-{$payment->id}", goods: [...], totalSum: 250000, iban: 'UA123456789012345678901234567', comment: 'Payment for order #12345', ) ); ``` ### 5. Get order status [](#5-get-order-status) ``` $order = VchasnoKasa::orders()->get($fiscalOrderId); if ($order->status->isSuccess()) { $yourOrder->update([ 'fiscal_receipt_url' => $order->receiptUrl, 'fiscal_code' => $order->fiscalCode, 'fiscalized_at' => $order->fiscalizedAt, ]); } ``` ### 6. List orders (cursor pagination) [](#6-list-orders-cursor-pagination) ``` use Sashalenz\VchasnoKasaApi\Data\Requests\Orders\ListOrdersData; use Sashalenz\VchasnoKasaApi\Enums\OrderStatus; $result = VchasnoKasa::orders()->list( new ListOrdersData( pageSize: 50, status: OrderStatus::Fiscalized, dateFrom: '2026-04-01T00:00:00Z', dateTo: '2026-04-30T23:59:59Z', ) ); foreach ($result->items as $order) { echo "{$order->id}: {$order->status->label()}"; } // Next page if ($result->hasMore) { $next = VchasnoKasa::orders()->list( new ListOrdersData(cursor: $result->nextCursor, pageSize: 50) ); } ``` ### 7. Cancel an order [](#7-cancel-an-order) ``` $cancelled = VchasnoKasa::orders()->cancel($fiscalOrderId); echo $cancelled->status->label(); // "Cancelled" ``` --- Receipts API ------------ [](#receipts-api) ### Get a receipt by ID [](#get-a-receipt-by-id) ``` $receipt = VchasnoKasa::receipts()->get($receiptId); echo $receipt->receiptUrl; // PDF URL echo $receipt->fiscalCode; // fiscal code from the tax authority ``` ### Poll for new receipts [](#poll-for-new-receipts) Useful for a background job that syncs fiscalization statuses: ``` use Sashalenz\VchasnoKasaApi\Data\Requests\Receipts\ListReceiptsData; $cursor = cache('vchasno_receipts_cursor'); do { $result = VchasnoKasa::receipts()->list( new ListReceiptsData(cursor: $cursor, pageSize: 100) ); foreach ($result->items as $receipt) { Order::where('fiscal_order_id', $receipt->orderId) ->update([ 'fiscal_receipt_url' => $receipt->receiptUrl, 'fiscal_code' => $receipt->fiscalCode, 'fiscalized_at' => $receipt->createdAt, ]); } $cursor = $result->nextCursor; } while ($result->hasMore); cache()->put('vchasno_receipts_cursor', $cursor); ``` --- Enums ----- [](#enums) ### `OrderStatus` [](#orderstatus) CaseValueDescription`Created``0`Created, awaiting processing`WaitingForPickup``10`NP: waiting for customer pickup`Delivered``11`NP: delivered, fiscalization in progress`Fiscalized``101`✅ Successfully fiscalized`Cancelled``2000`Cancelled`Returned``2001`Returned`Expired``2002`Expired``` $status->isSuccess(); // true if Fiscalized $status->isFinal(); // true if Fiscalized / Cancelled / Returned / Expired $status->isPending(); // true if Created / WaitingForPickup / Delivered $status->label(); // 'Fiscalized' ``` ### `PostalType` [](#postaltype) CaseValue`paymentType()``NovaPoshta``nova_poshta``PaymentType::NovaPoshta` (20)`UkrPoshta``ukr_poshta``PaymentType::PostalOther` (15)`Meest``meest``PaymentType::PostalOther` (15)### `PaymentType` [](#paymenttype) CaseValueDescription`Cash``1`Cash`Card``2`Card / terminal`PostalOther``15`Ukrposhta / Meest COD`NovaPoshta``20`Nova Poshta COD--- Error handling -------------- [](#error-handling) ``` use Sashalenz\VchasnoKasaApi\Exceptions\VchasnoKasaRequestException; try { $order = VchasnoKasa::orders()->createPostal($data); } catch (VchasnoKasaRequestException $e) { if ($e->shouldRetry()) { // res_action=1 or 2: request can be retried // res_action=2 (collision): retry with the same tag retry($job); } if ($e->needsDataFix()) { // res_action=3: bad request data, retrying will not help Log::error('Vchasno fiscal error', [ 'message' => $e->getMessage(), 'res_action' => $e->getResAction(), ]); } } ``` ### `res_action` codes [](#res_action-codes) ValueMethodAction`0`—Success`1``shouldRetry()`Retry the request`2``isCollision()`Collision — retry with the same `tag``3``needsDataFix()`Bad data — fix the request payload--- Idempotency (`tag`) ------------------- [](#idempotency-tag) The `tag` field is a required unique key for every order. If a request is repeated with the same `tag`, Vchasno returns the existing order instead of creating a new one. **Recommended format:** ``` // Nova Poshta shipment $tag = "order-{$order->id}-{$shipment->id}"; // Cash payment $tag = "cash-{$order->id}"; // IBAN payment $tag = "iban-{$payment->id}"; ``` --- Testing ------- [](#testing) ``` composer test ``` ``` composer analyse # PHPStan composer format # Pint ``` --- License ------- [](#license) MIT. See [LICENSE](LICENSE) for details. ### Health Score 23 — LowBetter than 26% of packages Maintenance60 Regular maintenance activity Popularity13 Limited adoption so far Community6 Small or concentrated contributor base Maturity11 Early-stage or recently created project Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Community Maintainers ![](https://avatars.githubusercontent.com/u/13202688?v=4)[Oleksandr Petrovskyi](/maintainers/sashalenz)[@sashalenz](https://github.com/sashalenz) --- Top Contributors [![sashalenz](https://avatars.githubusercontent.com/u/13202688?v=4)](https://github.com/sashalenz "sashalenz (1 commits)") ### Embed Badge ![Health badge](/badges/sashalenz-vchasno-kasa-api/health.svg) ``` [![Health](https://phpackages.com/badges/sashalenz-vchasno-kasa-api/health.svg)](https://phpackages.com/packages/sashalenz-vchasno-kasa-api) ``` ### Alternatives [facebook/php-business-sdk PHP SDK for Facebook Business 90923.5M35](/packages/facebook-php-business-sdk)[hubspot/api-client Hubspot API client 24015.5M18](/packages/hubspot-api-client)[botman/driver-telegram Telegram driver for BotMan 93452.6k6](/packages/botman-driver-telegram) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)