Integration guide

This guide shows how a POS works with SoftSDC. For every endpoint and field, see the API reference.

How the API runsCopy Anchor Link

SoftSDC runs a small HTTP server on the device:

• It serves JSON requests and responses.
• It runs locally, at http://localhost:8431/api/v3 by default.
• It keeps running in the background when the app is minimized.
• It serves one POS. The POS can be on the same device or on another device on the network.

SoftSDC follows the communication protocol in the Technical Instructions for E-SDC developers. You cannot change the protocol parameters.

To learn how SoftSDC signs, stores and reports each invoice, read how it works.

Request flowCopy Anchor Link

Sample clientsCopy Anchor Link

class SoftSDCClient {
  constructor(baseUrl = 'http://localhost:8431/api/v3') {
    this.baseUrl = baseUrl;
  }

  async verifyPin(pin) {
    const response = await fetch(`${this.baseUrl}/pin`, {
      method: 'POST',
      headers: { 'Content-Type': 'text/plain' },
      body: pin
    });
    return await response.text();
  }

  async createInvoice(invoice) {
    const response = await fetch(`${this.baseUrl}/invoices`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      },
      body: JSON.stringify(invoice)
    });
    return await response.json();
  }
}

Best practicesCopy Anchor Link

RequestsCopy Anchor Link

• Verify the PIN first, before you send invoices.
• Send a RequestId with every request, for tracking and recovery.
• Use timeouts. Signing can take time. A 30-second timeout is a good start.
• Retry network failures with exponential backoff.
• Store responses. Keep the fiscalization responses for your audit trail.

ErrorsCopy Anchor Link

• Check the status before sending. Make sure SoftSDC is ready.
• Handle every status code. See error codes for the list and sample handlers.
• Log every API call.

PerformanceCopy Anchor Link

• Reuse connections with HTTP keep-alive.
• Fiscalize each invoice on its own. You can batch work in your POS, but SoftSDC signs one invoice per request.
• Cache status responses for 30 to 60 seconds.
• Watch the status for warnings before they become errors, and track response times.
• Do not flood the service. Respect its limits and use circuit breakers.

TestingCopy Anchor Link

Training invoicesCopy Anchor Link

Use the Training invoice type to test without fiscal effect. Training invoices are clearly marked and do not count in fiscal reporting.

{
  "invoiceType": "Training"
}

Send the rest of the invoice fields as usual.

Test endpointsCopy Anchor Link

• GET /api/v3/attention checks that the service is running.
• POST /api/v3/test-invoice creates a test invoice, if enabled.

Before you go liveCopy Anchor Link

Need help?Copy Anchor Link

• Error codes for status codes and fixes
• Troubleshooting for common invoice errors
• Glossary for terms such as GSC, MRC and tax label
• Support for integration questions