PAID fiscalization module. Standalone, payment-method-agnostic integration with Checkbox ПРРО API: sale and return receipts, shift lifecycle, tax sync, webhook, and admin receipt management.
| Component | Version |
|---|---|
| Magento Open Source / Adobe Commerce | 2.4.4+ |
| PHP | 8.1+ |
| ext-json | any |
| guzzlehttp/guzzle | ^7.5 |
| MaGuru_Core | ^1.0 |
composer require maguru/module-checkbox-fiscal
bin/magento module:enable MaGuru_CheckboxFiscal
bin/magento setup:upgrade
bin/magento cache:flushStores → Configuration → MaGuru → Checkbox Fiscal
| Field | Description |
|---|---|
| Enabled | Enable/disable the integration |
| API URL | Checkbox API base URL |
| Login | Cashier login |
| Password | Cashier password (encrypted) |
| License Key | Cash register license key (encrypted) |
| Tax Codes | Tax code mapping (VAT groups) |
| Debug | Write detailed request/response logs to var/log/checkbox_fiscal.log |
| Max Retries | Number of retry attempts for failed receipts |
| Pending Timeout | Minutes before a pending receipt is considered stale |
| HTTP Timeout / Connect Timeout | Guzzle request and TCP timeouts |
| Webhook Secret | HMAC secret for incoming Checkbox webhook validation. Auto-populated — when you register the webhook URL via MaGuru → Checkbox Fiscal → Shift Management → Webhook section, Checkbox generates and returns this key, and the module saves it automatically (encrypted). No manual entry needed. |
| Auto Open Shift | Automatically open shift on first receipt of the day |
| Auto Close Time | Cron time for automatic shift close (HH:MM) |
| Fiscalize Only These Payment Methods | Multiselect of Magento payment methods. Empty = fiscalize all methods (default). Select specific methods to fiscalize only those — use this if another module already fiscalizes some payment methods on its own (e.g. MaGuru MonoFiscal for monopay), to avoid double-fiscalizing the same sale |
| Cash Payment Methods | Magento payment method codes treated as cash for fiscal purposes |
| Send Email / Phone | Include customer email/phone in the fiscal receipt |
- Sale receipts — fiscal receipt created automatically on invoice payment; async via message queue
- Return receipts — fiscal return created automatically on credit memo; async via message queue
- Customer-facing receipts — completed receipts with a link to the official State Tax Service verification page appear on the customer's order view
- Manual recovery tools — "Create Receipt" / "Create Return Receipt" / "Validate Receipt" buttons on the admin order view, plus a status-sync CLI command and cron job that reconciles pending receipts against Checkbox as a webhook fallback
- Shift management — open and close shifts from admin panel (
MaGuru → Checkbox Fiscal → Shift Management); shift history; auto-open on first receipt; cron-based auto-close - Billing status monitoring — daily check of account billing status and SMS balance; admin notification before the account is blocked or SMS delivery stops
- Cash register info — view connected cash register details from admin config
- Tax sync — pull tax codes from Checkbox API via admin action or CLI
- Webhook —
POST /checkbox_fiscal/checkbox/webhookfor incoming Checkbox status pushes with HMAC-SHA256 signature validation; register/inspect/delete it from MaGuru → Checkbox Fiscal → Shift Management → Webhook — Checkbox generates the signing secret and it's saved automatically - Receipt grid — dedicated admin grid (
MaGuru → Checkbox Fiscal → Receipts) with QR code view, PDF download, service receipt creation, and mass retry - Fatal notifications — admin alert when a receipt fails beyond max retries (
FatalReceiptNotifier) - Queue —
SaleReceiptConsumer,ReturnReceiptConsumer(async, defaultdbbackend; switchable toamqpviaenv.php) - Cron — auto-close shift; cleanup stale pending receipts; retry failed receipts; sync pending receipt statuses; check billing status
- CLI —
checkbox:auth:ping,checkbox:shift:open,checkbox:shift:close,checkbox:shift:status,checkbox:receipt:retry,checkbox:receipt:sync-status,checkbox:receipt:validate,checkbox:report:x-report,checkbox:tax:sync - Exception hierarchy —
CheckboxApiException
Inject interfaces, never concrete classes:
use MaGuru\CheckboxFiscal\Api\CheckboxReceiptServiceInterface;
use MaGuru\CheckboxFiscal\Api\ShiftManagementInterface;Token is stored encrypted in core_config_data and managed via TokenManager. All API calls go through typed client interfaces (AuthClientInterface, ReceiptClientInterface, ShiftClientInterface, TaxClientInterface, ReportClientInterface, WebhookClientInterface, CashRegisterClientInterface).
bin/clinotty php vendor/bin/phpunit -c app/code/MaGuru/CheckboxFiscal/Test/Unit/phpunit.xml394 unit tests · PHPStan Level 8 ✅
- Email: maguru.sup@gmail.com
- Issues: via Magento Marketplace order page
Proprietary