FiscoBridge Help Main Site

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 answer 404. 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.

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. /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": 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. Send the culture code for your certificate's country: en-FJ (Fiji), en-WS (Samoa), en-VU (Vanuatu), en-SZ (Eswatini).

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

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.

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.

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.

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

{
  "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

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