SDC API Reference

The SDC exposes a local REST API that your POS system calls to fiscalize invoices. This is the complete endpoint reference: every request and response model, every property, and every error code.

If you are new to the SDC, start with the SDC Overview and make sure the device is installed, initialized, and licensed first — most endpoints refuse to work until it is.

Base URL

The API listens on port 8888 by default. You can change the port from the SDC window (Change Port), and the user interface always shows the address the API is currently running on.

A few things worth knowing before you write any code:

HTTP only, no TLS. The API is not served over HTTPS.
No authentication. Any client that can reach the port can fiscalize invoices with your certificate.
It listens on all network interfaces, not just the loopback address. A POS running on another machine on the same network can reach the SDC at http://{sdc-machine-ip}:8888. That also means anything else on the network can reach it, so keep the SDC on a trusted local network and restrict port 8888 in your firewall to the machines that actually need it.
Interactive documentation is built in at http://127.0.0.1:8888/swagger — you can try every endpoint from the browser while the SDC is running.

Swagger UI listing the SDC API endpoints, served from the running SDC application

Before Your Requests Will Succeed

Most endpoints call ValidSE() first, which checks the Secure Element in this order and rejects the request with 400 Bad Request and a response code as soon as one check fails:

Check	Response code
Smart card inserted	`1300`
Card not locked	`2110`
PIN verified this session	`1500`
Device initialized	`2400`
Certificate not expired	`2809`

These endpoints enforce it: create invoice, get signed invoice, all Reports endpoints, all Advanced endpoints. GET /api/v3/status, GET /api/v3/environment-parameters, GET /api/v3/attention, GET /api/v3/invoices/pdf/{invoiceNumber} and POST /api/v3/pin do not — they are the endpoints you use to diagnose a device that is not ready.

Reports and Advanced endpoints additionally require a Pro licence and return 2008 on a Lite licence. Fiscalizing with an unlicensed (free) SDC against a production card is rejected with 2007 — see Applying a License.

Endpoints

Method	Endpoint	Purpose	Pro only
`POST`	`/api/v3/invoices`	Fiscalize an invoice	no
`GET`	`/api/v3/invoices/{requestId}`	Re-read a recently signed invoice	no
`GET`	`/api/v3/invoices/pdf/{invoiceNumber}`	Render a fiscal receipt as PDF	no
`POST`	`/api/v3/pin`	Verify the smart card PIN	no
`GET`	`/api/v3/status`	Device status and current tax rates	no
`GET`	`/api/v3/environment-parameters`	Organization and environment details	no
`GET`	`/api/v3/attention`	Health check	no
`GET`	`/api/Reports/GetDailyReport`	Daily totals for a period	yes
`GET`	`/api/Reports/GetPaymentTypes`	Totals per payment type	yes
`GET`	`/api/Reports/GetTaxAmounts`	Totals per tax label	yes
`GET`	`/api/Reports/GetListOfItems`	Items sold in a period	yes
`GET`	`/api/Advanced/GetAllCollections`	All advance-invoice collections	yes
`GET`	`/api/Advanced/GetOpenedCollections`	Open advance-invoice collections	yes
`POST`	`/api/Advanced/GetCollectionById`	One advance collection in full	yes
`POST`	`/api/Advanced/GetCalculatedAdvancedReportById`	Calculated totals for a collection	yes

Paths are matched case-insensitively, so /api/reports/getdailyreport also works.

Conventions

JSON in, JSON out. Response property names are camelCase.
Request fields are permissive. Every field on the invoice request accepts either a native JSON type or its string form — "quantity": 2 and "quantity": "2" are both fine, as are "invoiceType": "Normal" and "invoiceType": 0. Enum names are matched case-insensitively.
Dates are parsed with DateTime.Parse; ISO 8601 (2026-08-13T10:15:00) is the safe format. sdcDateTime in responses is UTC.
RequestId is a header, not a body field. Send it as an HTTP header on the create call (max 32 characters). It is echoed back in the RequestId response header and lets you re-read the invoice afterwards.
Accept-Language selects the language of the printed journal text. The value is matched against the languages the tax authority environment supports (see supportedLanguages on the status endpoint); an unmatched or missing header falls back to the environment's default.

RequestId is not an idempotency key. Re-sending a create request with the same RequestId signs a second fiscal invoice. Build your own duplicate protection before retrying.

Create an Invoice

POST /api/v3/invoices

Request properties

Property	Type	Required	Rules
`invoiceType`	enum	yes	See Enums. Invalid or missing → `2805`
`transactionType`	enum	yes	`Sale` or `Refund`. Invalid or missing → `2805`
`payment`	array	yes	At least one entry
`items`	array	yes	At least one entry
`cashier`	string	no	Max 50 characters → `2803`
`buyerId`	string	no	Max 20 characters → `2803`. Must not be an empty string → `2805`
`buyerCostCenterId`	string	no	Max 50 characters → `2801`. Only valid together with `buyerId` — either one without the other → `2800`
`dateAndTimeOfIssue`	datetime	no	Unparseable → `2805`. Defaults to the signing time
`invoiceNumber`	string	no	Your own reference, max 60 characters → `2804`. Must not be an empty string → `2805`. Not the fiscal number — that is assigned during signing
`referentDocumentNumber`	string	no	Required when `transactionType` is `Refund` or `invoiceType` is `Copy` → `2800`. Max 50 characters → `2803`. Malformed → `2806`
`referentDocumentDT`	datetime	no	The `sdcDateTime` of the referenced document. Sending it without `referentDocumentNumber` → `2800`
`options`	object	no	String-to-string map, see Options

`payment[]`

Property	Type	Required	Rules
`amount`	decimal	yes	Unparseable → `2805`
`paymentType`	enum	yes	See Enums. Invalid → `2805`

When an invoice carries more than one payment, the invoice's own payment type is recorded as Other.

`items[]`

Property	Type	Required	Rules
`name`	string	yes	1–2048 characters. Missing → `2800`, wrong length → `2803`
`quantity`	decimal	yes	0.001 – 99,999,999,999.9999. Missing → `2800`, out of range → `2804`, unparseable → `2805`
`unitPrice`	decimal	yes	Max 2 decimal places and non-negative → `2804`. Missing → `2800`. Absolute value must stay under 999,999,999,999.99 → `2805`
`totalAmount`	decimal	yes	Max 2 decimal places and non-negative → `2804`. Missing → `2800`. Must stay within −999,999,999,999 to 99,999,999,999 → `2805`
`labels`	array of characters	yes	At least one tax label. Missing → `2800`. Duplicate labels within one item → `2805`. A label that is not in the certificate's active tax rate group → `2310`
`gtin`	string	no	8–14 characters → `2803`

labels accepts a JSON array (["A"]) or a plain string ("A"). Read the valid labels for your certificate from GET /api/v3/status rather than hardcoding them — rates and labels change over time.

Options

options is a map of string keys to the string values "0" or "1". Any other value → 2805.

Key	Effect when set to `"1"`
`omitQRCodeGen`	`verificationQRCode` is returned as `null`
`omitTextualRepresentation`	`journal` is not generated

Response

200 OK with the signed invoice:

Property	Type	Meaning
`requestedBy`	string	UID of the certificate that requested the invoice
`sdcDateTime`	datetime	Signing time in UTC — this is the legally binding timestamp
`invoiceCounter`	string	Composed as `{transactionTypeCounter}/{totalCounter}{invoiceCounterExtension}`
`invoiceCounterExtension`	string	Two-character counter suffix identifying the invoice/transaction type combination
`invoiceNumber`	string	The fiscal invoice number, composed as `{requestedBy}-{signedBy}-{totalCounter}`. Use this to look up the PDF
`taxItems`	array	Calculated tax per label — see below
`verificationUrl`	string	Public tax authority verification link; this is what the QR code encodes
`verificationQRCode`	string	The QR code as a base64-encoded PNG, ready to print on the receipt
`journal`	string	The plain-text fiscal receipt, formatted for the printer
`messages`	string	`"Success"` on a signed invoice
`signedBy`	string	UID of the Secure Element that signed
`encryptedInternalData`	string	Base64 internal data block required on the printed receipt
`signature`	string	Base64 digital signature
`totalCounter`	integer	Running count of all invoices signed by this Secure Element
`transactionTypeCounter`	integer	Running count for this transaction type
`totalAmount`	decimal	Invoice total, rounded to 4 decimal places
`taxGroupRevision`	integer	Revision of the tax rate group used
`businessName`, `tin`, `locationName`, `address`, `district`, `mrc`	string	Taxpayer details taken from the certificate, for the receipt header

taxItems[]

Property	Type	Meaning
`label`	character	Tax label the amount was calculated for
`rate`	decimal	Rate applied
`amount`	decimal	Tax amount, rounded to 4 decimal places
`categoryName`	string	Tax category name, printed on the receipt
`categoryType`	integer	See `CategoryType` in Enums

taxItems[] also carries taxItemId, invoiceId, categoryId and categoryOrderId. These are internal bookkeeping values — ignore them.

Validation errors

Any validation failure returns 400 Bad Request with a ModelErrors body listing every problem at once:

property is the JSON path of the offending field, and errors holds four-digit response codes. Secure Element and licence problems use the check name as the property instead — Warning, Error or license.

Get a Signed Invoice

GET /api/v3/invoices/{requestId}

Returns the same InvoiceResult body as the create call, for an invoice you sent with that RequestId header.

Only the five most recent invoices per certificate are kept. The SDC stores signed invoices in a small rolling cache and prunes older entries, so this endpoint is a short-term safety net for a POS that lost the create response — not an invoice archive. Store the response when you receive it. Older invoices are still available as PDFs.

Returns 204 No Content when no cached invoice matches the request ID.

Get an Invoice PDF

GET /api/v3/invoices/pdf/{invoiceNumber}

Renders a previously fiscalized invoice — journal text plus verification QR code — as a printable PDF. {invoiceNumber} is the fiscal invoice number from the create response (URL-encode it; it contains hyphens but no slashes).

200 OK — application/pdf, delivered as fiscal-{invoiceNumber}.pdf
404 Not Found — unknown invoice number, or the invoice has no stored journal text (for example, it was created with omitTextualRepresentation)

Unlike the request-ID lookup, this endpoint reads the SDC's full local invoice database, so it works for older invoices too.

Verify the PIN

POST /api/v3/pin

Unlocks the Secure Element for the session. Send the PIN as the raw request body — any non-digit characters are stripped, so 1234, "1234" and {"pin":"1234"} all resolve to 1234.

The response is always 200 OK with a four-character response code as the body — check the code, not the status:

Body	Meaning
`0100`	PIN accepted, Secure Element unlocked
`2100`	Wrong PIN, or not exactly 4 digits
`2110`	Card locked after repeated wrong PINs
`1300`	No smart card in the reader

Never retry a rejected PIN automatically. Each failed attempt burns one try on the card's PIN counter, and the card locks permanently once it runs out. Prompt a human instead.

Device Status

GET /api/v3/status

The endpoint your POS should poll. It reports device health and — importantly — the authoritative tax labels and rates for the current certificate.

Property	Type	Meaning
`isPinRequired`	boolean	The Secure Element needs a PIN before it can sign
`auditRequired`	boolean	The Secure Element has used ¾ of its audit storage and must submit an audit
`sdcDateTime`	datetime	Current SDC time
`lastInvoiceNumber`	string	Fiscal number of the most recent invoice, or empty
`protocolVersion`	string	POS-to-SDC protocol version
`secureElementVersion`	string	Smart card applet version
`hardwareVersion`, `softwareVersion`	string	SDC versions
`deviceSerialNumber`	string	Device serial with the certificate UID appended
`make`, `model`	string	Device make and model
`mssc`	array of strings	Manufacturer-specific status codes
`gsc`	array of strings	General status codes — `1400` audit required, `1100` storage 90% full, `2001` counter limit reached
`taxCoreApi`	string	Tax authority API the device is registered against
`currentTaxRates`	object	Tax rate group in force now — see below
`allTaxRates`	array	All known tax rate groups, past and future
`supportedLanguages`	array of strings	Languages accepted in `Accept-Language`
`uid`	string	Unique identifier of the certificate

TaxRateGroup

Property	Type	Meaning
`validFrom`	datetime	When the group takes effect
`groupId`	integer	Group revision identifier
`taxCategories`	array	Categories in the group

TaxCategory

Property	Type	Meaning
`name`	string	Category name printed on the receipt
`categoryType`	enum	How tax is calculated — see Enums
`orderId`	integer	Display/calculation order
`taxRates`	array	Rates in the category

TaxRate

Property	Type	Meaning
`label`	character	The label you put in `items[].labels`
`rate`	decimal	Percentage, or a fixed amount for `AmountPerQuantity` categories

Environment Parameters

GET /api/v3/environment-parameters

Organization and environment details, used for receipt headers and for linking to the taxpayer portal. Returns an object with empty fields if the device is not initialized yet.

Property	Type	Meaning
`organizationName`	string	Registered taxpayer name
`serverTimeZone`	string	Tax authority server time zone
`street`, `city`, `country`	string	Registered address
`environmentName`	string	Environment label, for example the sandbox or production name
`logo`	string	Tax authority logo
`ntpServer`	string	Time source the SDC synchronizes against
`supportedLanguages`	array of strings	Languages available for journal text
`endpoints`	object	Environment URLs

endpoints

Property	Type	Meaning
`taxpayerAdminPortal`	string	Taxpayer admin portal URL
`taxCoreApi`	string	Tax authority API URL
`vsdc`	string	Virtual SDC URL
`root`	string	Environment root URL

Health Check

GET /api/v3/attention

Returns 200 OK with an empty body whenever the SDC's API is running. Use it as a liveness probe — it performs no Secure Element checks, so a 200 here means "the SDC is reachable", not "the SDC is ready to sign". Poll GET /api/v3/status for readiness.

Reports

All four report endpoints require a Pro licence and take the same query parameters:

Parameter	Type	Required	Meaning
`from`	datetime	yes	Start of the period, inclusive
`to`	datetime	yes	End of the period, inclusive
`uid`	string	no	Restrict to one certificate UID; omit for all

Reports count Normal and Advance invoices only — proforma, copy and training invoices are excluded. Refund amounts are subtracted from the totals. If report generation fails, the endpoint returns an empty report object rather than an error.

`GET /api/Reports/GetDailyReport`

Property	Type	Meaning
`uid`	string	The UID filter that was applied, or `null`
`totalInvoices`	integer	Number of invoices counted
`totalSales`	decimal	Sum of sale invoices
`totalRefunds`	decimal	Sum of refund invoices
`nettoSales`	decimal	`totalSales − totalRefunds`
`totalTax`	decimal	Sum of `taxes[].amount`, rounded to 2 decimals
`taxes[]`	array	`label` (character), `amount` (decimal)
`payments[]`	array	`type` (payment type name), `amount` (decimal)

`GET /api/Reports/GetPaymentTypes`

Property	Type	Meaning
`paymentTypes[].name`	enum	Payment type
`paymentTypes[].total`	decimal	Net total for that type
`total`	decimal	Sum across all types

`GET /api/Reports/GetTaxAmounts`

Property	Type	Meaning
`taxAmounts[].label`	character	Tax label
`taxAmounts[].total`	decimal	Net tax collected for that label
`total`	decimal	Sum across all labels

`GET /api/Reports/GetListOfItems`

Items sold in the period, grouped by name and GTIN.

Property	Type	Meaning
`items[].name`	string	Item name
`items[].gtin`	string	GTIN, empty if none
`items[].unitPrice`	decimal	Unit price
`items[].quantity`	decimal	Net quantity sold
`items[].total`	decimal	Net amount

Advanced

Advance-invoice collections: chains of Advance invoices that eventually close with a final Normal invoice. All four endpoints require a Pro licence and operate on the certificate currently in the reader.

`GET /api/Advanced/GetAllCollections`

Every collection, open and closed. Returns an array of:

Property	Type	Meaning
`dateAndTime`	datetime	When the collection was opened
`invoiceNumber`	string	Fiscal number of the first invoice in the chain — the collection's identifier
`isClosed`	boolean	A final invoice has been issued

`GET /api/Advanced/GetOpenedCollections`

The same shape, filtered to collections that are still open.

`POST /api/Advanced/GetCollectionById`

Returns the full chain, oldest first:

Property	Type	Meaning
`dateAndTime`	datetime	Invoice timestamp
`invoiceNumber`	string	Fiscal number
`referenceNumber`	string	Fiscal number of the previous invoice in the chain, `null` for the first
`isClosed`	boolean	Whether the collection is closed
`uid`	string	Certificate UID
`invoiceType`	enum	See Enums
`transactionType`	enum	`Sale` or `Refund`
`amount`	decimal	Invoice amount

`POST /api/Advanced/GetCalculatedAdvancedReportById`

Same request body; returns the collection's totals:

Property	Type	Meaning
`firstInvoiceDateAndTime`	datetime	Timestamp of the first invoice
`lastInvoiceDateAndTime`	datetime	Timestamp of the last invoice
`firstInvoiceNumber`	string	Fiscal number of the first invoice
`lastInvoiceNumber`	string	Fiscal number of the last invoice
`isClosed`	boolean	Whether the collection is closed
`uid`	string	Certificate UID
`totalAdvanceSaleAmount`	decimal	Sum of advance sales
`totalAdvanceRefundAmount`	decimal	Sum of advance refunds
`finalAmount`	decimal	Final invoice amount, `null` while the collection is open

Advance chains are validated when you fiscalize them. A final Normal invoice must reference the last Advance refund in its chain, and a new Advance invoice must reference the most recent link — see codes 2009, 2010 and 2011.

Enums

Enum fields accept the name ("Cash", case-insensitive) or the number (1).

invoiceType

Value	Name	Meaning
0	`Normal`	Standard fiscal invoice
1	`Proforma`	Not a fiscal invoice — quote or pre-bill
2	`Copy`	Fiscal copy of a previous document; requires `referentDocumentNumber`
3	`Training`	Test invoice, marked as not a fiscal invoice
4	`Advance`	Advance payment

transactionType

Value	Name
0	`Sale`
1	`Refund`

paymentType

Value	Name
0	`Other`
1	`Cash`
2	`Card`
3	`Check`
4	`WireTransfer`
5	`Voucher`
6	`MobileMoney`

categoryType

Value	Name	Meaning
0	`TaxOnNet`	Percentage of the net amount
1	`TaxOnTotal`	Percentage of the total amount
2	`AmountPerQuantity`	Fixed amount per unit sold

HTTP Status Codes

Status	When
`200 OK`	Success. Note that `POST /api/v3/pin` also returns 200 for a rejected PIN — read the response code in the body
`204 No Content`	`GET /api/v3/invoices/{requestId}` found no cached invoice
`400 Bad Request`	Validation failure, Secure Element not ready, or licence restriction. Body is `ModelErrors`
`404 Not Found`	PDF requested for an unknown invoice, or one with no journal text
`500 Internal Server Error`	Unhandled error. The body is empty — check the SDC logs, and see Exporting Logs

There is no retry-after or rate limiting. A device that is not ready answers 400, not 503, so treat 400 with a Secure Element code as "retry once the operator fixes the device" rather than a permanent failure.

Response Codes

Every code is four digits. The first digit gives the severity: 0xxx informational, 1xxx warning, 2xxx error.

Informational

Code	Meaning
`0000`	All OK
`0100`	PIN verified
`0210`	Internet available
`0220`	Internet unavailable

Warnings

Code	Meaning
`1100`	Secure Element storage 90% full
`1300`	No smart card in the reader
`1400`	Audit required
`1500`	PIN required before signing
`1999`	Undefined warning

Device and licence errors

Code	Meaning
`2000`	Maximum number of tax categories exceeded
`2001`	A Secure Element counter reached its limit — the card must be replaced
`2003`	End Audit sent with no active audit
`2004`	Audit data must be 256 bytes
`2005`	Proof of Audit does not match the expected Start Audit
`2006`	Payload is not a valid Proof of Audit
`2007`	Unlicensed SDC cannot fiscalize with a production card — only `Training` invoices are allowed
`2008`	This endpoint requires a Pro licence
`2009`	Referenced invoice is not the correct one in the advance chain
`2010`	Referenced advance invoice is not a refund
`2011`	Referenced invoice is not an advance invoice
`2100`	Wrong PIN
`2110`	Card locked after repeated wrong PINs
`2210`	Secure Element locked
`2220`	Secure Element communication failed
`2230`	Secure Element protocol mismatch
`2310`	Tax label is not valid for this certificate
`2400`	Device not configured — initialize it first
`2809`	Certificate expired

Field validation errors

Code	Meaning
`2800`	Required field missing
`2801`	Field length exceeded
`2802`	Field too short
`2803`	Field length invalid
`2804`	Field out of range — including more than 2 decimal places on an amount
`2805`	Field value invalid
`2806`	Invalid data format
`2807`	List shorter than expected
`2808`	List longer than expected

Next Steps

Initialize the SDC — get the device to a state where the API will sign
Applying a License — Lite versus Pro, and what Pro unlocks
Exporting Logs — what to collect when a request fails unexpectedly