API reference

The SoftSDC API lets your POS send receipts for fiscalization and check the system status. It uses REST with JSON over HTTP.

New to the API? Start with the integration guide. To learn what SoftSDC does with each receipt after it signs it, read how it works.

Base URLCopy Anchor Link

http://localhost:8431/api/v3

The default port is 8431. You can change it in the app settings.

HeadersCopy Anchor Link

Required:

Accept: application/json
Content-Type: application/json

Optional:

AuthenticationCopy Anchor Link

The API uses the smart card PIN. Verify the PIN with POST /api/v3/pin before you send invoices.

EndpointsCopy Anchor Link

Verify PINCopy Anchor Link

POST /api/v3/pin unlocks the smart card so SoftSDC can sign invoices.

POST /api/v3/pin
Accept: application/json
Content-Type: application/json

{
  "pin": "1234"
}

POST /api/v3/pin
Content-Type: text/plain

1234

Create invoiceCopy Anchor Link

POST /api/v3/invoices sends a receipt for fiscalization.

POST /api/v3/invoices

{
  "dateAndTimeOfIssue": "2024-01-15T10:30:00.000Z",
  "cashier": "123456789",
  "buyerId": "RS34564565",
  "buyerCostCenterId": "567546",
  "invoiceType": "Normal",
  "transactionType": "Sale",
  "payment": [
    {
      "amount": 68.46,
      "paymentType": "Cash"
    }
  ],
  "invoiceNumber": "POS2024/001",
  "referentDocumentNumber": "",
  "options": {
    "omitQRCodeGen": "0",
    "omitTextualRepresentation": "0"
  },
  "items": [
    {
      "name": "Product Name",
      "quantity": 2,
      "unitPrice": 34.23,
      "labels": ["A"],
      "totalAmount": 68.46
    }
  ]
}

Get statusCopy Anchor Link

GET /api/v3/status returns the current state of SoftSDC, including tax rates and status codes.

GET /api/v3/status
Accept: application/json

Get environment parametersCopy Anchor Link

GET /api/v3/environment-parameters returns the environment configuration.

{
  "organizationName": "Tax Authority",
  "serverTimeZone": "Europe/Belgrade",
  "street": "Main Street 1",
  "city": "Belgrade",
  "country": "RS",
  "endpoints": {
    "taxpayerAdminPortal": "https://portal.taxcore.com/",
    "taxCoreApi": "https://api.taxcore.com/",
    "vsdc": "https://vsdc.taxcore.com/",
    "root": "https://verify.taxcore.com/"
  },
  "environmentName": "PRODUCTION",
  "ntpServer": "http://time.nist.gov/",
  "supportedLanguages": ["en-US", "sr-Latn-RS"]
}

Health checkCopy Anchor Link

GET /api/v3/attention returns 200 OK when the service is running.

Test invoiceCopy Anchor Link

POST /api/v3/test-invoice creates a test invoice, if this endpoint is enabled.

Value listsCopy Anchor Link

Invoice typesCopy Anchor Link

Transaction typesCopy Anchor Link

Payment typesCopy Anchor Link

Tax labelsCopy Anchor Link

Each item carries one or more tax labels that set its tax category. The valid labels and rates come from currentTaxRates in the status response. Common labels:

Responses and errorsCopy Anchor Link

HTTP status codesCopy Anchor Link

SoftSDC status codesCopy Anchor Link

Responses also carry 4-digit status codes in gsc (general) and mssc (manufacturer-specific). The glossary explains these and other terms.

{
  "gsc": ["2100"],
  "mssc": [],
  "messages": "PIN verification failed. 3 attempts remaining."
}

The full list is in error codes. For fixes to common invoice errors, see troubleshooting.