Skip to main content
Version: 2.0.0

Szamlazz

Szamlazz connects yStore orders to Szamlazz.hu (also known as Számla Agent), the Hungarian online invoicing service, using the unofficial benjaminhu/szamlazz-php-api client. It registers as an invoice provider on yStore's shared invoicing system, authenticates with a single API key, and adds a Szamlazz.hu section to the Craft control panel with a dashboard, an invoice list, settings, and a license page.

What it does​

  • Registers a szamlazz invoice provider (Yui\Szamlazz\providers\SzamlazzInvoiceProvider) on yStore's shared invoicing system, so Szamlazz.hu can act alongside any other invoice provider the store has configured, driven by the same order-status triggers as the rest of the invoicing suite.
  • Authenticates against the Szamlazz.hu Agent API using a single API Key; API Key, Log E-mail, Sandbox Mode, Company ID, Invoice Language, and Market (Country) are all site-overridable on a multi-site install.
  • An admin can create, preview, download, delete, or regenerate the invoice manually from the order edit page in addition to the automatic order-status-driven creation.
  • Generates a storno (reverse) invoice against Szamlazz.hu whenever an invoice is deleted or regenerated, so the accounting trail on Szamlazz.hu's side stays correct instead of just discarding the local record.
  • Automatically deletes (stornoes) the invoice when an order reaches a configured "delete" status, e.g. when an order is canceled.
  • Downloads the generated invoice PDF and stores it as a Craft asset, linked to the order.
  • Optionally emails the invoice PDF to the customer as an attachment once it's created.
  • Can generate invoices asynchronously via Craft's queue, so invoice creation never blocks order completion.
  • Can soft-delete (archive) invoices instead of permanently removing their local records, keeping a read-only trail for admins.
  • Lets an admin resync invoice PDFs that exist on disk but are missing their asset link in the database, via a background job triggered from Settings.
  • Adds a Szamlazz.hu → Dashboard page with invoice totals, a status breakdown, and recent invoices, and a Szamlazz.hu → Invoices page listing invoices with search, sorting, pagination, and bulk delete.
  • Reports invoice creation outcomes (invoice.created, invoice.failed, invoice.error) through yui/craft-core's shared notification system.
  • Exposes invoice listing, preview, creation, sending, regeneration, and deletion as MCP tools for AI-agent-driven operations (see Developer API).
  • Activates the plugin license from Szamlazz.hu → License.
  • Exposes the same create/download/regenerate actions as Craft console commands for scripting and ops tooling.

Use Cases​

Admin / Craft CP​

  • Enter your API Key on the API Credentials tab to connect the store to your Szamlazz.hu account, and optionally set a Log E-mail to be notified by Szamlazz.hu if something goes wrong during an Agent operation.
  • Choose Generate invoice when -- the order status(es) that trigger automatic invoice creation through yStore's shared invoicing system -- and, separately, Delete invoice when the order status is -- the status(es) that trigger an automatic storno/deletion (for example when an order is canceled).
  • Set Hide Szamlazz controls when an order has one of these statuses to hide the plugin's order-edit buttons and restrict the manual create/preview/download/regenerate/delete actions on orders in states where invoicing doesn't make sense (fraud, on hold, etc.). This only affects the CP controls and manual actions -- it does not stop automatic invoice creation or deletion, which are governed independently by Generate invoice when and Delete invoice when the order status is.
  • Turn on Show Szamlazz Button to add a menu to the order edit page for manually creating, previewing, downloading, deleting, or regenerating the invoice for that order.
  • Turn on Send Invoice to customer in email and pick Send invoice when (order status list) to have the plugin email the invoice PDF to the customer automatically once it's issued.
  • Choose whether invoice generation runs through Craft's queue (Use queue for invoice generation), so a slow Szamlazz.hu API call doesn't delay the customer-facing checkout/order flow.
  • Decide whether deleted invoices are soft-deleted (Soft delete invoices) -- archived and kept read-only for admins -- or removed outright.
  • Set the invoice Name (internal Szamlazz.hu label), the Invoice number (Formatted) pattern (YYYY/OOOO placeholders), and the number of Due date days used to calculate the due date from the invoice creation date.
  • Choose the Invoice Creation Type: Order (one invoice per order) or Item (a separate invoice per line item -- useful for multi-supplier/partner fulfillment).
  • Set the Market (Country) (Slovak or Czech Szamlazz.hu service) and the Language the invoice is issued in.
  • Set Tax Payer (select "No" to omit VAT entirely) and the Tax Class used to calculate VAT on invoice items.
  • Choose whether the Shipping Method and/or Payment Method are added as their own invoice line items, and how Configurable Product Pricing is represented (folded into the main product line, or listed as separate configuration lines).
  • Decide whether an invoice should still be created for Zero Total Orders (fully discounted/free orders).
  • Review Szamlazz.hu → Dashboard for invoice totals, a status breakdown, and the most recent invoices, or Szamlazz.hu → Invoices for a searchable, sortable, paginated list with bulk delete -- shown by default via Show in CP Section.
  • Use Sandbox Mode to reduce Szamlazz.hu API logging while testing, and use Resync invoices on the Settings page to relink invoice PDFs that exist on disk but lost their database link (for example after a restore).
  • Activate the plugin license from Szamlazz.hu → License.

Developer / Integrator​

  • Read the plugin's settings and services from Yui\Szamlazz\Plugin::getInstance() to build custom invoicing or reporting logic on top of the same API credentials, tax configuration, and order-status triggers -- see Developer API.
  • Hook into ApiService::EVENT_BEFORE_API_CONNECTION to inspect or override the settings used to build the Szamlazz.hu API connection (for example to route different sites/brands to different API keys at connection time) -- see Developer API.
  • Listen for invoice.created, invoice.failed, and invoice.error notifications (registered via NotificationService::EVENT_REGISTER_NOTIFICATION_TYPES) to surface Szamlazz.hu invoicing outcomes elsewhere in the CP.
  • Call the szamlazz_get_invoices, szamlazz_preview_invoice, szamlazz_create_invoice, szamlazz_send_invoice, szamlazz_regenerate_invoice, and szamlazz_delete_invoice MCP tools from an AI agent or automation to inspect, preview, trigger, email, regenerate, or delete Szamlazz.hu invoices for a given order (see Developer API).
  • Use the szamlazz/invoices/regenerate and szamlazz/invoices/download console commands to regenerate or export invoices from scripts, cron jobs, or deploy tooling.

Installation & Requirements​

Requirements​

  • Craft CMS 5 (craftcms/cms ^5.2.0)
  • yui/craft-core ^1, declared in require and provided by every yStore installation; its Settings model extends yui\craftcore\models\BasePluginSettingsModel at runtime
  • A Szamlazz.hu account with an Agent API key generated for the account
  • Optional: yui/craft-mcp, for the MCP invoice tools

Installation​

composer require yui/craft-szamlazz

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

  1. API Key on the API Credentials tab.
  2. Market (Country) and Language on the Settings tab.
  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 tab
  • Developer API -- services, invoice provider, events, MCP tools, and console commands
  • Release Notes -- notable changes between releases