Developer API

The iDoklad plugin exposes services, an invoice provider, an order-edit UI component, and MCP tools for integration with yStore's invoicing system and external/automation clients.

Services

Access services via the plugin instance:

use Yui\IDoklad\Plugin;

$idoklad = Plugin::getInstance();
$api = $idoklad->getApi();
$invoices = $idoklad->getInvoices();
$dashboard = $idoklad->getDashboard();
$license = $idoklad->getLicense();

ApiService

Handles the OAuth2 handshake with iDoklad: builds the authentication URL, exchanges the authorization code for an access/refresh token pair, and persists the resulting credentials to storage/idoklad/credentials.json. If the OAuth response is missing an access/refresh token, the stored credentials file is cleared and the error is exposed via getLastAuthErrorMessage() (shown on the Settings page as a CP error notice). getConnection() builds the authenticated iDoklad API client used by every other service.

InvoiceService

Creates, updates, and downloads iDoklad invoices from order data.

• createInvoice(int $orderId, ?string $orderStatus, bool $manualCreate = false) -- creates an invoice for an order. When $manualCreate is false, it only proceeds if $orderStatus is one of the configured Generate invoice when statuses. Returns false on failure, true on success, or an array of error messages. Refuses to create a duplicate invoice for an order that already has one.
• createInvoiceFromData(array $invoiceData, bool $manualCreate = false) -- the invoice-provider entry point; builds the invoice from a normalized $invoiceData array (with an order_id/order_status under meta) instead of loading the order directly. Used by IDokladInvoiceProvider::createInvoice().
• updateInvoice(int $orderId, ?string $orderStatus, bool $manualUpdate = false) -- re-sends the invoice data as a PATCH for an order that already has a recorded invoice, and clears the cached PDF asset so the next download fetches the updated document.
• downloadInvoice(int $orderId) -- returns the invoice PDF as a Craft Asset. If the PDF hasn't been fetched yet, it requests it from iDoklad (Reports/IssuedInvoice/{id}/Pdf) and stores it under idoklad/invoices/{year}/{month}/{day} in the store's asset volume; subsequent calls reuse the stored asset. Returns false on failure.

Every invoice/order/client/item detail sent to iDoklad is assembled from the order (address, line items, shipping, payment) and the plugin's settings (invoice name/number template, due date, tax class, signature/payment-info/By-Square toggles, and whether shipping/payment are added as line items). VAT is toggled by the store-wide Tax Payer setting (yStore core), not the plugin's own Tax Payer field. Contact country, report language, and currency are currently hard-coded to Slovakia in InvoiceService, and the plugin's Tax Payer, Rounding type, Send Invoice when order is Paid, and Sandbox Mode settings are not yet read by this service -- see Settings for the full list of settings that don't yet affect behavior in v1.3.0.

DashboardService

Extends the shared yui\craftcore\services\CoreDashboardService to build the iDoklad → Dashboard modules: Total invoices, In this period, and This month KPI tiles, and a Recent invoices table (date, order, type, invoice ID; latest 12). Dashboard layout (module order/visibility) is persisted back onto the plugin's own settings (dashboardLayout).

LicenseService

Backs the iDoklad → License CP page (shared yui/craft-core license activation/status UI).

Invoice provider

Yui\IDoklad\providers\IDokladInvoiceProvider registers itself with handle idoklad on yui\craft\services\sales\InvoiceService::EVENT_REGISTER_INVOICE_PROVIDERS, so it appears alongside any other invoice provider yStore has registered.

public function isEnabled(): bool
{
    return (bool)(Plugin::getInstance()?->getSettings()?->enabled ?? false);
}

The provider is enabled purely based on the Enabled settings toggle. createInvoice() delegates to InvoiceService::createInvoiceFromData(), and getAttachments() returns the invoices already recorded for the order via InvoiceService::getInvoicesByOrderId().

Order-edit component

When Show iDoklad Button is on, the plugin hooks into the order-edit-extra-actions template hook and renders an iDoklad menu button on the order edit page (idoklad/components/order/edit/manage-invoice.twig). The menu offers:

• Create Invoice -- shown when the order has no recorded invoice yet.
• Update Invoice -- shown when the order already has one.
• Download Invoice -- always shown; links to idoklad/invoice/download/{orderId}.

These map to InvoiceController::actionCreate(), actionUpdate(), and actionDownload().

MCP Tools

When the yui/craft-mcp plugin is installed, iDoklad registers three MCP tools on yui\mcp\Plugin::EVENT_REGISTER_TOOLS, all extending the shared AbstractInvoiceTool base (also used by other invoice-provider plugins), which accepts an order identifier (order_id and/or increment_id).

idoklad_get_invoices

Lists all iDoklad invoices for a given order.

Output:

{
  "order_id": 123,
  "count": 1,
  "invoices": ["..."]
}

idoklad_create_invoice

Manually creates an iDoklad invoice for an order, bypassing the order-status trigger and forcing creation. Fails if an invoice already exists for the order. Requires WRITE permission.

idoklad_download_invoice

Downloads (or returns the already-cached asset for) the iDoklad invoice PDF for an order. Returns the asset URL and filename, or success: false with an error message if the PDF could not be fetched.

{
  "success": true,
  "order_id": 123,
  "url": "https://.../invoice.pdf",
  "filename": "invoice.pdf"
}

Requires WRITE permission.

Settings model

Yui\IDoklad\models\Settings (extends yui\craftcore\models\BasePluginSettingsModel) holds every field documented in Settings. Validation: clientId, clientSecret, and redirectUri are required whenever the plugin is enabled (Settings::rules()).

CP Routes

Route	Purpose
idoklad / idoklad/dashboard	Dashboard
idoklad/invoices	Invoice list
idoklad/invoice/create/<orderId>, /update/<orderId>, /download/<orderId>	Manual invoice actions from the order edit page
idoklad/settings	Settings
idoklad/settings/test-connection	Diagnostics connection test
idoklad/license	License activation/status
idoklad/license/redeem, /revoke, /activate, /delete, /copy-token	License actions

Compatibility

• Craft CMS 5+
• yui/craft-core ^1
• mervit/idoklad-v3 1.*
• Optional: yui/craft-mcp, for the MCP tools described above