Checkbox API

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

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