Kros

Kros connects yStore orders to KROS Fakturácia (Economy API), the Slovak accounting/invoicing service. It registers as an invoice provider for yStore's invoicing system, authenticates against the KROS OpenAPI with a bearer token, and adds a Kros section to the Craft control panel with a dashboard, an invoice list, settings, and license pages.

What it does

• Registers a kros invoice provider on yStore's invoicing system (yui\craft\services\sales\InvoiceService::EVENT_REGISTER_INVOICE_PROVIDERS), so KROS can act as one of potentially several invoicing backends available to the store.
• Authenticates with the KROS OpenAPI using a bearer API Token generated in KROS Fakturácia ("API prepojenia"), sent against a configurable API Base URL.
• Automatically creates an invoice when an order reaches one of the configured order statuses, or the invoice can be created/updated manually from the order edit page.
• Downloads the generated invoice PDF and stores it as a Craft asset.
• Receives KROS webhook events (invoice created/updated/deleted/sent/paid) and, when enabled, keeps a local copy of remote invoices in the database in sync with those events.
• Tracks the KROS API rate limit (limit/remaining/reset) reported on every response and shows it read-only in the settings sidebar.
• Adds a Kros → Dashboard page with invoice totals (total, this period, synced, pending) and a recent invoices table, and a Kros → Invoices page listing every invoice the plugin has created, with search and pagination.
• Exposes invoice listing, manual creation, and PDF download as MCP tools for AI-agent-driven operations (see Developer API).

Use Cases

Admin / Craft CP

• Configure the API Base URL (defaults to https://api-economy.kros.sk) and the API Token from KROS Fakturácia's "API prepojenia" screen (API Credentials tab), then click Test Credentials to confirm they work before relying on automatic invoice creation.
• Choose which order statuses should trigger automatic invoice creation (Generate invoice when). A Send Invoice when order is Paid toggle is also present, but as of v1.3.0 it isn't wired to any behavior yet -- use Generate invoice when for automatic creation instead.
• Turn on Show Kros Button to add a Kros menu button to the order edit page, from which an admin can manually create, update, or download the invoice for that order (see order-edit component below).
• Set the invoice Due date days, the KROS Invoice PDF Report ID (17 black and white, 19 color, 101 editable), an optional Numbering Sequence code, and optional Opening/Closing Text shown around the invoice items.
• Choose the invoice Language, VAT Payer Type, and Tax Class, and whether the shipping method and/or payment method should be added to the invoice as their own line items.
• Decide how configurable-product pricing is handled on the invoice (Configurable Product Pricing): fold configuration prices into the main product price, or list them as separate items.
• Enable Store Remote Invoices in Database to cache invoices fetched via the API locally (fewer KROS API requests for the Kros → Invoices list), and Increment the last remote invoice number to let KROS auto-increment invoice numbers instead of using the order number as the variable symbol.
• Turn on Enable Webhooks so the plugin accepts and processes incoming KROS invoice events; a Webhook Secret must be set or all incoming webhook requests are rejected (the settings page shows a security warning until one is configured). As of v1.3.0 the plugin does not automatically register the webhook on the KROS side when this is saved -- the webhook must be created manually in KROS Fakturácia, pointed at the URL from Webhook URL (or the default action URL). See Webhooks for the full flow.
• Decide whether an invoice should still be generated for a zero-total order (Zero Total Orders).
• Review Kros → Dashboard for invoice totals and the most recent invoices, or Kros → Invoices for the full, searchable, paginated list -- both hidden unless Show in CP Section is enabled in the settings sidebar.
• Activate the plugin license from Kros → License.
• Monitor the read-only Rate Limit / Remaining / Reset fields in the settings sidebar, updated automatically from the headers of the last KROS API response.

Developer / Integrator

• Read the plugin's settings and services from Yui\Kros\Plugin::getInstance() to build custom invoicing logic on top of the same API credentials, VAT/tax configuration, and order-status trigger.
• Call the kros_get_invoices, kros_create_invoice, and kros_download_invoice MCP tools from an AI agent or automation to inspect, trigger, or fetch KROS invoices for a given order (see Developer API).
• Consume KROS webhook events (invoice.created, invoice.updated, invoice.deleted, invoice.sent, invoice.paid) to keep a locally cached invoice in sync without polling the KROS API.

Installation & Requirements

Requirements

• Craft CMS 5
• yui/craft-core ^1
• A KROS Fakturácia account with API access enabled and a bearer token generated under "API prepojenia"
• Optional: yui/craft-mcp, for the MCP invoice tools

Installation

composer require yui/craft-kros

After installing, enable the plugin in Settings → Plugins, then open Kros → Settings and configure at minimum:

1. API Base URL and API Token (API Credentials tab), then Test Credentials to confirm them.
2. Generate invoice when (General tab) -- the order status(es) that should trigger invoice creation.
3. Invoice PDF Report ID and Due date days (General tab).

See Settings for the full field reference.

Documentation

• Settings -- full settings reference, organized by CP form tab
• Developer API -- services, invoice provider, webhooks, order-edit component, and MCP tools
• Release Notes -- version history