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.
The SDC exposes one fiscalization protocol at a time, chosen automatically by which tax authority's certificate is installed — it is not something your POS selects per request. Use the country selector below to see the endpoints, fields, and validation rules for your market.
Base URL
http://127.0.0.1:8888
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. - The protocol is certificate-bound. A production certificate for Fiji, Samoa or Vanuatu only exposes
/api/v3/...routes —/api/v4/...routes answer404. A production certificate for Eswatini is the reverse. A sandbox certificate exposes both protocols at once for testing. - 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, and it only lists the routes your current certificate actually exposes.

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. /api/Reports/* and /api/Advanced/* are not protocol-versioned — they respond the same way regardless of whether the device is running v3 or v4.
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/v4/status, GET /api/v4/environment-parameters, GET /api/v4/attention, GET /api/v4/invoices/pdf/{invoiceNumber} and POST /api/v4/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/v4/invoices |
Fiscalize an invoice (extended v4 request/response) | no |
GET |
/api/v4/invoices/{requestId} |
Re-read a recently signed invoice | no |
GET |
/api/v4/invoices/pdf/{invoiceNumber} |
Render a fiscal receipt as PDF | no |
POST |
/api/v4/pin |
Verify the smart card PIN | no |
GET |
/api/v4/status |
Device status and current tax rates | no |
GET |
/api/v4/environment-parameters |
Organization and environment details | no |
GET |
/api/v4/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. /api/Reports/* and /api/Advanced/* are not protocol-versioned — they respond the same way regardless of whether the device is running v3 or v4.
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": 2and"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.sdcDateTimein responses is UTC. RequestIdis a header, not a body field. Send it as an HTTP header on the create call (max 32 characters). It is echoed back in theRequestIdresponse header and lets you re-read the invoice afterwards.Accept-Languageselects the language of the printed journal text. The value is matched against the languages the tax authority environment supports (seesupportedLanguageson the status endpoint); an unmatched or missing header falls back to the environment's default. Send the culture code for your certificate's country:en-FJ(Fiji),en-WS(Samoa),en-VU(Vanuatu),en-SZ(Eswatini).
RequestIdis not an idempotency key. Re-sending a create request with the sameRequestIdsigns a second fiscal invoice. Build your own duplicate protection before retrying.
Create an Invoice
POST /api/v3/invoices
Content-Type: application/json
RequestId: order-10432
Accept-Language: en-FJ
Use the culture code for your certificate's country instead: en-FJ (Fiji), en-WS (Samoa), or
en-VU (Vanuatu).
{
"invoiceType": "Normal",
"transactionType": "Sale",
"cashier": "Maria",
"buyerId": "123456789",
"dateAndTimeOfIssue": "2026-08-13T10:15:00",
"payment": [
{ "amount": 112.00, "paymentType": "Cash" }
],
"items": [
{
"name": "Room service",
"quantity": 2,
"unitPrice": 56.00,
"totalAmount": 112.00,
"labels": ["A"],
"gtin": "09781234567897"
}
]
}
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 |
"options": { "omitQRCodeGen": "1" }
Response
200 OK with the signed invoice:
{
"requestedBy": "ABC1234",
"sdcDateTime": "2026-08-13T10:15:33Z",
"invoiceCounter": "12345/67890NS",
"invoiceCounterExtension": "NS",
"invoiceNumber": "ABC1234-XY7Z9Q8W-67890",
"taxItems": [
{ "label": "A", "rate": 15.0, "amount": 14.61, "categoryName": "VAT", "categoryType": 0 }
],
"verificationUrl": "https://vsdc.../v/?vl=...",
"verificationQRCode": "iVBORw0KGgoAAAANSUhEUg...",
"journal": " ============ FISCAL INVOICE ============\n ...",
"messages": "Success",
"signedBy": "XY7Z9Q8W",
"encryptedInternalData": "...",
"signature": "...",
"totalCounter": 67890,
"transactionTypeCounter": 12345,
"totalAmount": 112.00,
"taxGroupRevision": 3,
"businessName": "Pacific Hotels Ltd",
"tin": "123456789",
"locationName": "Suva Branch",
"address": "12 Victoria Parade",
"district": "Central",
"mrc": "..."
}
| 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:
{
"message": "Bad Request",
"modelState": [
{ "property": "items[0].labels[0]", "errors": ["2310"] },
{ "property": "payment", "errors": ["2800"] }
]
}
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.
Create an Invoice
POST /api/v4/invoices
Content-Type: application/json
RequestId: order-10432
Accept-Language: en-SZ
{
"invoiceType": "Normal",
"transactionType": "Sale",
"invoiceCategory": "B2B",
"cashier": "Maria",
"buyerId": "100123456",
"dateAndTimeOfIssue": "2026-08-13T10:15:00",
"dateOfSupply": "2026-08-13",
"payment": [
{ "amount": 112.00, "paymentType": "Cash" }
],
"items": [
{
"name": "Room service",
"quantity": 2,
"unitPrice": 56.00,
"unitPriceTaxExcluded": 48.70,
"totalAmount": 112.00,
"taxableAmount": 97.39,
"labels": ["A"],
"gtin": "09781234567897",
"itemAdditionalFields": { "unit": "pcs", "itemCode": "235687" }
}
]
}
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 |
invoiceCategory |
enum | yes | See Enums. Missing or blank → 2800. Undefined value → 2805. B2B, B2G, G2B or G2G make buyerId required → 2800 on buyerId |
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. *Required whenever invoiceCategory is B2B/B2G/G2B/G2G, or dateOfSupply is set |
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 |
dateOfSupply |
date | no | Unparseable → 2805. Out of range → 2804. Requires buyerId — see above |
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, invoiceType is Copy, or documentFunction is set → 2800. Max 50 characters → 2803. Malformed → 2806. When documentFunction is CancellationInvoice/ReplacementInvoice, a malformed value also triggers a second, separate 2805 |
referentDocumentDT |
datetime | no | The sdcDateTime of the referenced document. Sending it without referentDocumentNumber → 2800 |
documentFunction |
enum | no | See Enums. Undefined value → 2805. Requires referentDocumentNumber — see above |
options |
object | no | String-to-string map, see Options |
invoiceAdditionalFields |
map of string to string | no | Not a flat object → 2805. Blank key → 2800 on invoiceAdditionalFields.Key. Key over 64 characters → 2801 on invoiceAdditionalFields['{key}'].Key. Value over 256 characters → 2801 on invoiceAdditionalFields['{key}'].Value |
buyerIdcan be required by two rules at once.invoiceCategoryanddateOfSupplyeach check it independently — aB2Brequest withdateOfSupplyset but nobuyerIdgets two2800entries onbuyerIdin the same response, since there is no de-duplication between the two checks.
payment[]
| Property | Type | Required | Rules |
|---|---|---|---|
amount |
decimal | yes | Unparseable → 2805 |
paymentType |
enum | yes | See Enums. Invalid → 2805 |
paymentAdditionalFields |
map of string to string | no | Same rules as invoiceAdditionalFields, on payment[i].paymentAdditionalFields['{key}'].Key/.Value |
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 |
unitPriceTaxExcluded |
decimal | yes | 0 – 999,999,999,999.99. Missing → 2800. Out of range or unparseable → 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 |
taxableAmount |
decimal | yes | 0 – 999,999,999,999.99. Missing → 2800. Out of range or unparseable → 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 |
itemAdditionalFields |
map of string to string | no | Same rules as invoiceAdditionalFields, on items[i].itemAdditionalFields['{key}'].Key/.Value |
labels accepts a JSON array (["A"]) or a plain string ("A"). Read the valid labels for your certificate from GET /api/v4/status rather than hardcoding them — rates and labels change over time.
unitPrice/totalAmount are tax-inclusive; unitPriceTaxExcluded/taxableAmount are their tax-exclusive counterparts. v4 requires both pairs on every item — note the stricter 2805 (not 2804) for an out-of-range or unparseable tax-exclusive amount.
Known itemAdditionalFields keys
| Key | Meaning | Tax authority field spec |
|---|---|---|
unit |
Item's unit of measure, printed as its own column on the extended item table | Max 5 characters |
itemCode |
Unique product/service code for the item, printed as its own column on the extended item table | Max 20 characters |
Both are optional and case-insensitive. The SDC does not itself enforce these two lengths — only the
generic itemAdditionalFields limits apply (key ≤ 64 characters, value ≤ 256 characters, per the
invoiceAdditionalFields rule above). A longer unit/itemCode value is accepted; the printed
column just widens to fit it, so keep to the tax authority's lengths if you want the receipt to
print with fixed-width columns.
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 |
"options": { "omitQRCodeGen": "1" }
Response
200 OK with the signed invoice — same shape as v3, with one addition: every entry in taxItems[] also carries taxableAmountPerLabel.
{
"requestedBy": "ABC1234",
"sdcDateTime": "2026-08-13T10:15:33Z",
"invoiceCounter": "12345/67890NS",
"invoiceCounterExtension": "NS",
"invoiceNumber": "ABC1234-XY7Z9Q8W-67890",
"taxItems": [
{ "label": "A", "rate": 15.0, "amount": 14.61, "taxableAmountPerLabel": 97.39, "categoryName": "VAT", "categoryType": 0 }
],
"verificationUrl": "https://vsdc.../v/?vl=...",
"verificationQRCode": "iVBORw0KGgoAAAANSUhEUg...",
"journal": " ============ FISCAL INVOICE ============\n ...",
"messages": "Success",
"signedBy": "XY7Z9Q8W",
"encryptedInternalData": "...",
"signature": "...",
"totalCounter": 67890,
"transactionTypeCounter": 12345,
"totalAmount": 112.00,
"taxGroupRevision": 3,
"businessName": "Pacific Hotels Ltd",
"tin": "123456789",
"locationName": "Suva Branch",
"address": "12 Victoria Parade",
"district": "Central",
"mrc": "..."
}
| 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 — carries extra columns/lines under the en-SZ layout (item code, unit, taxable amount, date of supply, project name/number) |
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 |
taxableAmountPerLabel |
decimal | Sum of every item's taxableAmount that carries this tax label |
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:
{
"message": "Bad Request",
"modelState": [
{ "property": "items[0].taxableAmount", "errors": ["2800"] },
{ "property": "buyerId", "errors": ["2800"] }
]
}
property is the JSON path of the offending field — including map entries like invoiceAdditionalFields['branch'].Value — 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 a Signed Invoice
GET /api/v4/invoices/{requestId}
Returns the same InvoiceResult body as the create call (including taxableAmountPerLabel), 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 asfiscal-{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.
Get an Invoice PDF
GET /api/v4/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 asfiscal-{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.
The printed journal carries more detail than v3: item code, unit, a taxable-amount column, and Date of Supply/Project Name/Project Number lines are always shown (even blank) under the en-SZ locale Eswatini's tax authority uses. This only affects the rendered text/PDF — the JSON response shape is unchanged.
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.
POST /api/v3/pin
Content-Type: text/plain
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.
Verify the PIN
POST /api/v4/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.
POST /api/v4/pin
Content-Type: text/plain
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 |
Device Status
GET /api/v4/status
The endpoint your POS should poll. It reports device health and — importantly — the authoritative tax labels and rates for the current certificate. The response shape is identical to v3.
| 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 — always reports the legacy 1.0.0.0, even with v4 active. Don't use this field to detect v4; the fact that /api/v4/... routes answer (instead of 404) is the only signal |
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 |
Environment Parameters
GET /api/v4/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. The response shape is identical to v3.
| 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.
Health Check
GET /api/v4/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/v4/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
{
"uid": "XY7Z9Q8W",
"totalInvoices": 142,
"totalSales": 18240.50,
"totalRefunds": 320.00,
"nettoSales": 17920.50,
"totalTax": 2337.46,
"taxes": [ { "label": "A", "amount": 2337.46 } ],
"payments": [ { "type": "Cash", "amount": 9120.25 } ]
}
| 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
{ "invoiceNumber": "ABC1234-XY7Z9Q8W-67890" }
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 |
invoiceCategory — v4 only, required on every invoice
| Value | Name | Meaning |
|---|---|---|
| 0 | B2C |
Business to consumer |
| 1 | B2B |
Business to business — requires buyerId |
| 2 | B2G |
Business to government — requires buyerId |
| 3 | G2C |
Government to consumer |
| 4 | G2B |
Government to business — requires buyerId |
| 5 | G2G |
Government to government — requires buyerId |
documentFunction — v4 only, optional
| Value | Name | Meaning |
|---|---|---|
| 0 | DebitNote |
Increases a previously issued invoice — requires referentDocumentNumber |
| 1 | CreditNote |
Reduces a previously issued invoice — requires referentDocumentNumber |
| 2 | CancellationInvoice |
Cancels a previously issued invoice — requires a well-formed referentDocumentNumber |
| 3 | ReplacementInvoice |
Replaces a previously issued invoice — requires a well-formed referentDocumentNumber |
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, one with no journal text, or a route from a protocol the current certificate doesn't expose |
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. The same set of codes is used by both protocol versions — v4 does not introduce any new codes, it just applies some of them (2805 in particular) to its new fields.
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