POS to SDC Protocol Integration Guide

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

---

Required API Endpoints

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

---

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

• Accept: application/json
• Content-Type: application/json
• RequestId (optional): Unique identifier for request tracking (max 32 chars)
• Accept-Language (optional): Language preference for invoice journal

Key Request Fields

Item Structure

• name (required): Product/service name (max 2048 chars)
• quantity (required): Quantity with max 3 decimals (min 0.001)
• unitPrice (required): Unit price
• totalAmount (required): Gross price (unitPrice × quantity)
• labels[] (required): Tax rate labels (min 1)
• gtin (optional): Global Trade Item Number (8-14 chars)

Response Fields

• invoiceNumber: SDC invoice number (requestedBy-signedBy-totalCounter)
• invoiceCounter: Counter in format transactionTypeCounter/totalCounter
• sdcDateTime: Local date/time from E-SDC (ISO 8601)
• verificationUrl: URL for invoice verification
• verificationQRCode: Base64 encoded QR code image (GIF)
• journal: Textual representation for printing
• signature: Base64 encoded digital signature
• taxItems[]: Calculated tax breakdown per category

---

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

• "0100": PIN correct, Secure Element unlocked
• "2100": Wrong PIN
• "2110": Card locked (too many attempts)
• "1300": Smart card not inserted
• "2400": SDC not fully configured

---

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

• isPinRequired: true if PIN needs to be entered
• auditRequired: true if audit threshold reached (75% of limit)
• sdcDateTime: Current local date/time (ISO 8601)
• lastInvoiceNumber: Last invoice signed
• deviceSerialNumber: MRC format serial number
• supportedLanguages[]: Supported language codes
• currentTaxRates: Active tax rate configuration
• gsc[]: General status codes
• mssc[]: Manufacturer-specific codes

---

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

• organizationName: Tax authority name
• environmentName: Environment identifier (e.g., SANDBOX, PRODUCTION)
• endpoints: Available API endpoints (taxpayerAdminPortal, taxCoreApi, root)
• supportedLanguages[]: Language codes
• serverTimeZone: Server timezone
• ntpServer: NTP server for time sync

---

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)

• 0000: All OK
• 0100: PIN OK
• 0210: Internet Available
• 0220: Internet Unavailable

Warning Codes (1xxx)

• 1100: Storage 90% Full
• 1300: Smart Card Not Present
• 1400: Audit Required
• 1500: PIN Code Required

Error Codes (2xxx)

• 2100: PIN Not OK
• 2110: Card Locked
• 2210: Secure Element Locked
• 2220: SE Communication Failed
• 2310: Invalid Tax Labels
• 2400: SDC Not Configured
• 2800-2809: Field validation errors
• 2809: Secure Element Expired

---

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:

• All endpoints use /api/v3/ prefix
• No authentication required for E-SDC endpoints
• PIN verification is required once per session
• Invoice creation returns complete fiscalized invoice with signature and QR code
• Use RequestId header for invoice request tracking and retry
• Monitor status codes for audit requirements and error handling
• Multiple payment methods are supported per invoice
• Tax calculation is performed by SDC based on item labels

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