Superfaktura

Superfaktura connects yStore orders to SuperFaktura, the Slovak/Czech online invoicing service. It registers as an invoice provider for yStore's invoicing system, authenticates against the SuperFaktura API with an account email + API key, and adds a Superfaktúra section to the Craft control panel with a dashboard, an invoice list, settings, and a license page.

What it does

• Registers a superfaktura invoice provider on yStore's invoicing system (yui\craft\services\sales\InvoiceService::EVENT_REGISTER_INVOICE_PROVIDERS), so SuperFaktura can act as one of potentially several invoicing backends available to the store.
• Authenticates against the SuperFaktura API using an account Email and API Key, scoped to a Company ID and a Market (Country) (Slovak or Czech SuperFaktura).
• Automatically creates a regular invoice and/or a proforma invoice when an order reaches one of the configured order statuses, or the invoice/proforma/credit note can be created, updated, downloaded, or emailed manually from the order edit page.
• Creates a credit note (storno) against an existing regular invoice, e.g. for cancellations/refunds.
• Downloads generated invoice, proforma, and credit note PDFs and stores them as Craft assets.
• Applies B2B validation (company ID, tax ID, VAT ID format) and EU reverse-charge VAT handling for cross-border B2B orders when enabled.
• Tracks SuperFaktura's daily/monthly API request limits (limit/remaining/reset) reported by the API and shows them read-only in the settings sidebar.
• Adds a Superfaktúra → Dashboard page with invoice totals and recent invoices/failures, and a Superfaktúra → Invoices page listing invoices with search, pagination, and a manual sync action.
• Records invoice-creation failures per order/type so they can be inspected and retried from the CP or via automation, instead of silently failing.
• Exposes invoice listing, creation, email, and retry as MCP tools for AI-agent-driven operations (see Developer API).

Use Cases

Admin / Craft CP

• Configure Title, Email, API Key, and Company ID (API Credentials) plus the Market (Country) (Slovak or Czech) and Language the invoice should be issued in, then use Test Connection on the Diagnostics tab to confirm the credentials work for a given site before relying on automatic invoice creation.
• Choose which order statuses trigger automatic invoice creation (Generate invoice when) and which trigger a proforma invoice (Generate proforma invoice when), each optionally narrowed further to specific payment methods (Limit invoice/proforma creation to payment methods).
• Turn on Show Superfaktúra Button to add a Superfaktúra menu button to the order edit page, from which an admin can manually create, update, download, or email the invoice, proforma, or credit note for that order (see order-edit component).
• Turn on Send Invoice when Order is Paid and/or Send Proforma Invoice when Generated to email the document to the customer automatically, and set Invoice email BCC recipients to always copy internal addresses.
• Set the Invoice name (internal SuperFaktura label) and Invoice number (Formatted) pattern, the Due date days, whether the plugin should Disable Craft auto-incrementing invoice numbers (let SuperFaktura number invoices instead), and whether an invoice is still created for Zero Total Orders.
• Choose the Rounding type (Whole document / Per item / Retail) used for VAT calculations, whether the invoice shows a Signature, Payment Info, and/or By Square QR payment code, and whether the Shipping Method and/or Payment Method are added as their own invoice line items.
• Decide how configurable-product pricing is represented on the invoice (Configurable Product Pricing) and how order discounts/coupons are represented (Discount Handling).
• Choose whether a local order note is sent to SuperFaktura at all, which note is used (Order Note Source), and where it lands on the SuperFaktura document (Order Note Target).
• Turn on Validate B2B Details and, optionally, Require VAT ID for B2B Orders and EU Reverse Charge to enforce company/tax/VAT-ID data quality and apply zero-VAT reverse-charge invoicing to qualifying cross-border EU B2B orders.
• Enable Store Remote Invoices in Database to cache invoices fetched via the API locally (fewer SuperFaktura API requests for the Superfaktúra → Invoices list, with a manual Sync Invoices action), and Increment the last remote invoice number to let SuperFaktura auto-increment invoice numbers instead of using the configured pattern.
• Set Tax Payer/Tax Class for the store's VAT status and default invoice tax category.
• Review Superfaktúra → Dashboard for invoice totals and recent failures, or Superfaktúra → Invoices for the full, searchable, paginated list -- both hidden unless Show in CP Section is enabled.
• Use the settings Diagnostics tab to pick a site, run Test Connection, and review/clear Recent API Errors logged by the plugin (sensitive fields such as API keys and emails are redacted).
• Activate the plugin license from Superfaktúra → License.
• Monitor the read-only daily/monthly Limit / Remaining / Reset fields, updated automatically from the SuperFaktura API.

Developer / Integrator

• Read the plugin's settings and services from Yui\Superfaktura\Plugin::getInstance() to build custom invoicing logic on top of the same API credentials, VAT/tax configuration, and order-status triggers.
• Call the superfaktura_get_invoices, superfaktura_create_invoice, superfaktura_create_credit_note, superfaktura_send_invoice_email, and superfaktura_retry_failed MCP tools from an AI agent or automation to inspect, trigger, email, or retry SuperFaktura documents for a given order (see Developer API).
• Register a multi-site store's SuperFaktura credentials per site: Title, Email, API Key, Company ID, Market (Country), and Invoice Language are all site-overridable.

Installation & Requirements

Requirements

• Craft CMS 5 (craftcms/cms ^5.6.11)
• yui/craft-core ^1
• A SuperFaktura account (Slovak or Czech) with an API key generated for the account
• Optional: yui/craft-mcp, for the MCP invoice tools

Installation

composer require yui/craft-superfaktura

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

1. Title, Email, API Key, and Company ID (API Credentials), then Test Connection on the Diagnostics tab to confirm them.
2. Market (Country) and Invoice Language.
3. Generate invoice when -- the order status(es) that should trigger invoice creation.

See Settings for the full field reference.

Documentation

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