POS to SDC Protocol Integration Guide

Complete API Documentation for E-SDC Integration

This document describes the API exposed by E-SDC devices to POS and invoicing systems for fiscal invoice creation and Secure Element management.

API Documentation

E-SDC provides interactive API documentation via Swagger UI:

Swagger UI: http://localhost:8888/swagger/index.html

Required API Endpoints

POS systems must integrate the following endpoints for full SDC compliance:

Category Endpoint Method Purpose
Invoice /api/v3/invoices POST Create and fiscalize invoices
Invoice /api/v3/invoices/{requestId} GET Retrieve signed invoice by request ID
Secure Element /api/v3/pin POST Verify PIN to unlock Secure Element
Secure Element /api/v3/status GET Get SDC and Secure Element status
Secure Element /api/v3/environment-parameters GET Get environment configuration
Connectivity /api/v3/attention GET Verify E-SDC availability

1. Invoice Endpoints

1.1 Create Invoice – POST /api/v3/invoices

Creates a fiscal invoice and processes it through the Secure Element. Returns a digitally signed invoice with verification URL and QR code.

Endpoint Format

http://{ESDC_IP}:{PORT}/api/v3/invoices

Example: http://localhost:8888/api/v3/invoices

Authentication

No authentication required

Required Headers

Key Request Fields

Field Required Description
invoiceType Yes 0=Normal, 1=Proforma, 2=Copy, 3=Training, 4=Advance
transactionType Yes 0=Sale, 1=Refund
payment[] Yes Array of payment methods with amounts
items[] Yes Array of invoice items (min 1, supports 250-500)
cashier Optional* Cashier ID (mandatory in some jurisdictions)
buyerId Optional* Buyer identification (max 20 chars)

Item Structure

Response Fields

1.2 Get Invoice – GET /api/v3/invoices/{requestId}

Retrieves a previously signed invoice using its request identifier. Used when POS didn't receive the initial response.

http://{ESDC_IP}:{PORT}/api/v3/invoices/{requestId}

Example: http://localhost:8888/api/v3/invoices/4c5730b50eb7b50e7a0292600a67ce16

Returns the same structure as Create Invoice, or null if not found.

2. Secure Element Endpoints

2.1 Verify PIN – POST /api/v3/pin

Verifies the PIN entered by cashier to unlock the Secure Element. PIN is stored in RAM until card is removed or device is powered off.

Endpoint

http://{ESDC_IP}:{PORT}/api/v3/pin

Example: http://localhost:8888/api/v3/pin

Request

Plain text string containing 4 ASCII digits (0-9). Example: "1234"

Response Codes

2.2 Get Status – GET /api/v3/status

Retrieves current status of SDC and Secure Element, including tax rates, PIN requirements, and device information.

Endpoint

http://{ESDC_IP}:{PORT}/api/v3/status

Example: http://localhost:8888/api/v3/status

Response Fields

2.3 Get Environment Parameters – GET /api/v3/environment-parameters

Returns environment configuration including tax authority information, endpoints, and supported languages.

Endpoint

http://{ESDC_IP}:{PORT}/api/v3/environment-parameters

Example: http://localhost:8888/api/v3/environment-parameters

Response Fields

3. Connectivity Endpoint

3.1 Attention – GET /api/v3/attention

Used by POS to verify E-SDC availability before sending invoice or PIN requests. Reduces communication errors and timeouts.

Endpoint

http://{ESDC_IP}:{PORT}/api/v3/attention

Example: http://localhost:8888/api/v3/attention

Response

HTTP 200 OK if SDC is available.

4. Status and Error Codes

Info Codes (0xxx)

Warning Codes (1xxx)

Error Codes (2xxx)

5. Error Message Format

SDC returns structured error messages in the following format:

{
  "message": "The request is invalid.",
  "modelState": [
    {
      "property": "invoiceType",
      "errors": ["2805"]
    },
    {
      "property": "items[0].labels[0]",
      "errors": ["2310"]
    }
  ]
}

6. Integration Checklist

  1. Implement /api/v3/attention to check SDC availability
  2. Implement /api/v3/status to check PIN requirements and audit status
  3. Implement /api/v3/pin for PIN verification (E-SDC)
  4. Implement /api/v3/invoices (POST) for invoice fiscalization
  5. Implement /api/v3/invoices/{requestId} (GET) for retry scenarios
  6. Implement /api/v3/environment-parameters for environment config
  7. Handle all status and error codes appropriately
  8. Support multiple payment methods in payment[] array
  9. Ensure all items include required tax labels
  10. Store RequestId for each invoice request for retry capability

Summary

Key Points for POS Developers:

Complete integration of all these endpoints ensures full fiscal compliance and optimal POS-to-SDC communication.