README

Laravel client for the Checkbox RRO API — full coverage of all 145 endpoints from the official API v2.94.1.

Requirements

PHP 8.4+
Laravel 11 / 12 / 13

Installation

composer require sashalenz/checkbox-api

Publish the config file:

php artisan vendor:publish --tag="checkbox-api-config"

Configuration

.env:

CHECKBOX_TOKEN=your-jwt-token
CHECKBOX_LICENSE_KEY=your-license-key

config/checkbox-api.php:

return [
    'base_url'       => env('CHECKBOX_API_URL', 'https://api.checkbox.in.ua/api/v1/'),
    'token'          => env('CHECKBOX_TOKEN'),
    'license_key'    => env('CHECKBOX_LICENSE_KEY'),
    'timeout'        => 30,
    'retry'          => ['times' => 3, 'sleep' => 150],
    'client_name'    => env('CHECKBOX_CLIENT_NAME', 'sashalenz/checkbox-api'),
    'client_version' => env('CHECKBOX_CLIENT_VERSION', '1.0.0'),
];

Usage

Facade

use Sashalenz\CheckboxApi\Facades\Checkbox;

$token = Checkbox::cashier()->signIn(
    new SignInData(login: 'login@example.com', password: 'secret')
)->access_token;

Checkbox::setToken($token);

Dependency Injection

use Sashalenz\CheckboxApi\CheckboxApi;

class FiscalService
{
    public function __construct(private readonly CheckboxApi $api) {}

    public function openShift(): ShiftData
    {
        return $this->api->shifts()->create();
    }
}

Resources

Cashier (`cashier()`)

$api->cashier()->signIn(SignInData $data): AccessTokenData
$api->cashier()->signInPinCode(SignInPinCodeData $data): AccessTokenData
$api->cashier()->signOut(): bool
$api->cashier()->me(): CashierData
$api->cashier()->shift(): ShiftData
$api->cashier()->checkSignature(): SignatureStatusData
$api->cashier()->taxes(): DataCollection

Shifts (`shifts()`)

$api->shifts()->list(int $limit, int $offset): PaginatedData
$api->shifts()->create(?CreateShiftData $data): ShiftData
$api->shifts()->get(string $shiftId): ShiftData
$api->shifts()->shortShift(string $shiftId): array
$api->shifts()->close(string $shiftId, ?array $payload): ShiftData
$api->shifts()->closeCurrentShift(?array $payload): ShiftData

Receipts (`receipts()`)

$api->receipts()->list(...): PaginatedData
$api->receipts()->search(array $params): PaginatedData
$api->receipts()->get(string $receiptId): ReceiptData
$api->receipts()->sell(SellReceiptData $data): ReceiptData
$api->receipts()->sellOffline(SellReceiptData $data): ReceiptData
$api->receipts()->bulkSell(array $payload): array
$api->receipts()->service(ServiceReceiptData $data): ReceiptData
$api->receipts()->serviceCurrency(array $payload): ReceiptData
$api->receipts()->cashWithdrawal(array $payload): ReceiptData
$api->receipts()->currencyExchange(array $payload): ReceiptData
$api->receipts()->validate(array $payload): array
$api->receipts()->html(string $receiptId): string
$api->receipts()->pdf(string $receiptId): string
$api->receipts()->text(string $receiptId): string
$api->receipts()->png(string $receiptId): string
$api->receipts()->qrCode(string $receiptId): string
$api->receipts()->xml(string $receiptId): string
$api->receipts()->sendEmail(string $receiptId, string $email): array
$api->receipts()->sendSms(string $receiptId, string $phone): array

Prepayment Receipts (`prepaymentReceipts()`)

$api->prepaymentReceipts()->search(array $params): PaginatedData
$api->prepaymentReceipts()->get(string $relationId): array
$api->prepaymentReceipts()->create(array $payload): ReceiptData
$api->prepaymentReceipts()->createAfterPayment(string $relationId, array $payload): ReceiptData
$api->prepaymentReceipts()->return(string $relationId, array $payload): array

Goods (`goods()`)

$api->goods()->list(...): PaginatedData
$api->goods()->get(string $goodId): GoodData
$api->goods()->getByCode(string $code): GoodData
$api->goods()->create(CreateGoodData $data): GoodData
$api->goods()->update(string $goodId, array $payload): GoodData
$api->goods()->delete(string $goodId): array
$api->goods()->leftoversById(array $goodIds): array

// Groups
$api->goods()->groups(...): PaginatedData
$api->goods()->getGroup(string $groupId): GoodGroupData
$api->goods()->createGroup(CreateGoodGroupData $data): GoodGroupData
$api->goods()->updateGroup(string $groupId, array $payload): GoodGroupData
$api->goods()->deleteGroup(string $groupId): array
$api->goods()->moveGoods(string $groupId, string $toGroupId): array

// Export / Import
$api->goods()->exportGoods(string $extension): array          // csv|excel|json
$api->goods()->exportTaskStatus(string $taskId): array
$api->goods()->exportFile(string $taskId, ?int $chunk): string
$api->goods()->importUpload(string $contents, string $filename, bool $ignoreBarcodes, bool $autoSupply): array
$api->goods()->importTaskStatus(string $taskId): array
$api->goods()->importApplyChanges(string $taskId): array

Orders (`orders()`)

$api->orders()->list(...): PaginatedData
$api->orders()->get(string $orderId): OrderData
$api->orders()->create(CreateOrderData $data): OrderData
$api->orders()->cancel(string $orderId): array
$api->orders()->close(string $orderId): array
$api->orders()->delete(array $orderIds): array
$api->orders()->setCustomStatus(string $orderId, string $newStatus): array
$api->orders()->sync(): array
$api->orders()->getIntegration(): array
$api->orders()->setIntegration(string $url): array
$api->orders()->deleteIntegration(): array
$api->orders()->editIntegrationOrder(array $payload): array

Invoices / Acquiring (`invoices()`)

$api->invoices()->list(...): array
$api->invoices()->get(string $invoiceId): InvoiceData
$api->invoices()->create(CreateInvoiceData $data): InvoiceData
$api->invoices()->fiscalize(CreateInvoiceData $data): InvoiceData
$api->invoices()->cancel(string $invoiceId): array      // PATCH
$api->invoices()->cancelById(string $invoiceId): array  // DELETE
$api->invoices()->refund(string $invoiceId): array
$api->invoices()->remove(string $invoiceId): array
$api->invoices()->terminals(): array

Reports (`reports()`)

$api->reports()->list(...): PaginatedData
$api->reports()->search(...): PaginatedData
$api->reports()->get(string $reportId): ReportData
$api->reports()->create(): ReportData          // X-report
$api->reports()->periodical(...): string
$api->reports()->addExternal(array $payload): ReportData
$api->reports()->text(string $reportId): string
$api->reports()->png(string $reportId): string

Extended Reports (`extendedReports()`)

$api->extendedReports()->zReport(ZReportData $data): array
$api->extendedReports()->goodsReport(array $payload): array
$api->extendedReports()->actualRevenue(array $payload): array
$api->extendedReports()->netTurnover(array $payload): array
$api->extendedReports()->bookkeeperZReport(array $payload): array
$api->extendedReports()->dailyCashFlow(array $payload): array
$api->extendedReports()->receiptReport(array $payload): array
$api->extendedReports()->smsReceipts(array $payload): array
$api->extendedReports()->bookkeeperPayments(array $payload): array
$api->extendedReports()->fuibAggregated(array $payload): array
$api->extendedReports()->getTask(string $taskId): array
$api->extendedReports()->getTaskFile(string $taskId, string $extension): string

Transactions (`transactions()`)

$api->transactions()->list(...): PaginatedData
$api->transactions()->get(string $transactionId): TransactionData

Cash Registers (`cashRegisters()`)

$api->cashRegisters()->list(...): PaginatedData
$api->cashRegisters()->info(): CashRegisterData
$api->cashRegisters()->get(string $cashRegisterId): CashRegisterData
$api->cashRegisters()->shifts(...): PaginatedData
$api->cashRegisters()->goOnline(): array
$api->cashRegisters()->goOffline(): array
$api->cashRegisters()->pingTaxService(): array
$api->cashRegisters()->askOfflineCodes(): array
$api->cashRegisters()->getOfflineCodes(): array
$api->cashRegisters()->getOfflineCodesCount(): array
$api->cashRegisters()->getOfflineTime(): array

Organization (`organization()`)

$api->organization()->get(): OrganizationData
$api->organization()->receiptConfig(): array
$api->organization()->logo(): string
$api->organization()->textLogo(): string
$api->organization()->smsBilling(): array
$api->organization()->cashiers(...): PaginatedData
$api->organization()->billingStatus(): BillingStatusData

Currency Rates (`currency()`)

$api->currency()->rates(): array
$api->currency()->rateByCode(string $code): CurrencyRateData
$api->currency()->setup(SetupCurrencyRateData $data): array

Webhook (`webhook()`)

$api->webhook()->get(): WebhookData
$api->webhook()->set(SetWebhookData $data): array
$api->webhook()->delete(): array

eTTN (`ettn()`)

$api->ettn()->list(...): array
$api->ettn()->create(array $payload): EttnData
$api->ettn()->get(string $orderId): EttnData
$api->ettn()->update(string $orderId, array $payload): EttnData
$api->ettn()->delete(string $orderId): array
$api->ettn()->fiscalizeManually(string $orderId): EttnData
$api->ettn()->createPrepayment(array $payload): EttnData
$api->ettn()->getPrepayment(string $orderId): EttnData
$api->ettn()->deletePrepayment(string $orderId, string $relationId): array

Nova Poshta eTTN — deprecated (`npEttn()`)

Identical interface to ettn() using the /np/ettn endpoint. Migrate to ettn().

AirCheck / PayLink (`payLink()`)

$api->payLink()->authClient(array $payload): array
$api->payLink()->terminals(...): PaginatedData
$api->payLink()->getTerminal(string $terminalId): PayLinkTerminalData
$api->payLink()->removeTerminal(string $terminalId): array

Taxes (`tax()`)

$api->tax()->list(): DataCollection   // GET /api/v1/tax — requires X-License-Key

Branches (`branches()`)

$api->branches()->list(?bool $isActive, int $limit, int $offset): PaginatedData

System Status

$api->status(): array   // GET /status — public health check

Example: Sell Receipt

use Sashalenz\CheckboxApi\CheckboxApi;
use Sashalenz\CheckboxApi\Data\Requests\Receipts\SellReceiptData;
use Sashalenz\CheckboxApi\Data\Requests\Receipts\GoodItemData;
use Sashalenz\CheckboxApi\Data\Requests\Receipts\CashPaymentData;

$receipt = app(CheckboxApi::class)->receipts()->sell(
    new SellReceiptData(
        goods: [
            new GoodItemData(
                good: ['name' => 'Coffee', 'price' => 5000, 'code' => 'COFFEE-001', 'taxes' => []],
                quantity: 1000,
            ),
        ],
        payments: [
            new CashPaymentData(value: 5000),
        ],
    )
);

echo $receipt->fiscal_code;

Enums

Enum	Values
`ReceiptType`	`SELL`, `RETURN`, `SERVICE_IN`, `SERVICE_OUT`, `SERVICE_CURRENCY`, `CURRENCY_EXCHANGE`, `PAWNSHOP`, `CASH_WITHDRAWAL`
`ReceiptStatus`	`CREATED`, `DONE`, `ERROR`, `CANCELLATION`, `CANCELLED`
`ShiftStatus`	`CREATED`, `OPENING`, `OPENED`, `CLOSING`, `CLOSED`
`PaymentType`	`CASH`, `CARD`, `CASHLESS`
`TransactionType`	`SHIFT_OPEN`, `X_REPORT`, `Z_REPORT`, `PING`, `RECEIPT`, `GO_OFFLINE`, `GO_ONLINE`, …
`TransactionStatus`	`CREATED`, `PENDING`, `SIGNED`, `DELIVERED`, `DONE`, `ERROR`, `CANCELLED`, `OFFLINE`
`InvoiceStatus`	`CREATED`, `PROCESSING`, `HOLD`, `SUCCESS`, `FAILURE`, `REVERSED`, `REQUEST_TO_CANCEL`, `EXPIRED`
`OrderStatus`	`PENDING`, `SAVING`, `SUCCESS`, `CANCELLED`
`CustomOrderStatus`	`NEW`, `IN_WORK`, `APPROVED`, `PREPARING`, `DELIVERING`, `DELIVERED`, `DONE`, `CANCELED`, `TEST`, …
`SignatureType`	`AGENT`, `UKEY`, `DEPOSITSIGN`, `SMARTSIGN`, `CLOUD_SIGNATURE`, `TEST`, …
`ServiceOperationType`	`ADVANCE`, `REINFORCEMENT`, `COLLECTION`
`GoodsExportExtension`	`csv`, `excel`, `json`
`ReportStatus`	`NEW`, `PENDING`, `ERROR`, `DONE`, `UNKNOWN`
`EttnProvider`	`novapost`, `ukrpost`
`GoodsType`	`good`, `service`
`DiscountType`	`DISCOUNT`, `EXTRA_CHARGE`
`DiscountMode`	`PERCENT`, `VALUE`
`FiscalApiType`	`FSCO_EC`, `EVPEZ`, `EVPEZ_EXTERNAL`
`RoundingMode`	`ROUND_10`, `ROUND_50`, `NO_ROUND`

Testing

./vendor/bin/pest
./vendor/bin/phpstan analyse
./vendor/bin/pint

API Reference

Official documentation: https://api.checkbox.in.ua/api/redoc

OpenAPI spec: https://api.checkbox.in.ua/api/openapi.json

License

MIT

sashalenz / checkbox-api

Maintainers

Package info

Statistics

Security

README

Requirements

Installation

Configuration

Usage

Facade

Dependency Injection

Resources

Cashier (`cashier()`)

Shifts (`shifts()`)

Receipts (`receipts()`)

Prepayment Receipts (`prepaymentReceipts()`)

Goods (`goods()`)

Orders (`orders()`)

Invoices / Acquiring (`invoices()`)

Reports (`reports()`)

Extended Reports (`extendedReports()`)

Transactions (`transactions()`)

Cash Registers (`cashRegisters()`)

Organization (`organization()`)

Currency Rates (`currency()`)

Webhook (`webhook()`)

eTTN (`ettn()`)

Nova Poshta eTTN — deprecated (`npEttn()`)

AirCheck / PayLink (`payLink()`)

Taxes (`tax()`)

Branches (`branches()`)

System Status

Example: Sell Receipt

Enums

Testing

API Reference

License

sashalenz / checkbox-api

Maintainers

Package info

Statistics

Security

README

Requirements

Installation

Configuration

Usage

Facade

Dependency Injection

Resources

Cashier (cashier())

Shifts (shifts())

Receipts (receipts())

Prepayment Receipts (prepaymentReceipts())

Goods (goods())

Orders (orders())

Invoices / Acquiring (invoices())

Reports (reports())

Extended Reports (extendedReports())

Transactions (transactions())

Cash Registers (cashRegisters())

Organization (organization())

Currency Rates (currency())

Webhook (webhook())

eTTN (ettn())

Nova Poshta eTTN — deprecated (npEttn())

AirCheck / PayLink (payLink())

Taxes (tax())

Branches (branches())

System Status

Example: Sell Receipt

Enums

Testing

API Reference

License

Cashier (`cashier()`)

Shifts (`shifts()`)

Receipts (`receipts()`)

Prepayment Receipts (`prepaymentReceipts()`)

Goods (`goods()`)

Orders (`orders()`)

Invoices / Acquiring (`invoices()`)

Reports (`reports()`)

Extended Reports (`extendedReports()`)

Transactions (`transactions()`)

Cash Registers (`cashRegisters()`)

Organization (`organization()`)

Currency Rates (`currency()`)

Webhook (`webhook()`)

eTTN (`ettn()`)

Nova Poshta eTTN — deprecated (`npEttn()`)

AirCheck / PayLink (`payLink()`)

Taxes (`tax()`)

Branches (`branches()`)