API Overview

Introduction

The API section provides essential information for integrating with SoftSDC via its REST API interface. The API allows external applications to communicate with SoftSDC for fiscalization purposes.

Architecture

SoftSDC exposes a REST API that:

• Runs as an embedded HTTP server
• Processes JSON-formatted requests and responses
• Operates locally on the device
• Continues running in the background even when the UI is minimized

Base URL

The API runs locally on your device:

http://localhost:8431/api/v3

Default port: 8431 (configurable in settings)

Authentication

SoftSDC API uses PIN-based authentication with the smart card. Before processing invoices, you must verify the PIN using the /pin endpoint.

Communication Protocol

Request Format

All requests must include appropriate headers:

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

Optional Headers

• RequestId - Unique identifier for request tracking (max 32 characters)
• Accept-Language - Preferred language for responses (see supported languages in status response)

Key Endpoints

SoftSDC exposes several key endpoints for fiscal operations:

Core Operations

• POST /api/v3/pin - Verify PIN code
• POST /api/v3/invoices - Submit receipts for fiscalization
• GET /api/v3/status - Check system operational status

Information

• GET /api/v3/environment-parameters - Retrieve environment information
• GET /api/v3/attention - Check service availability

Response Format

All responses use standard HTTP status codes and JSON formatting:

Success Responses

• 200 OK - Request successful
• 201 Created - Invoice created successfully

Error Responses

• 400 Bad Request - Invalid request format
• 401 Unauthorized - PIN verification required
• 500 Internal Server Error - Server error

Error Handling

The API uses a comprehensive error code system. Errors are returned with:

• HTTP status code
• Error code (4-digit numeric code)
• Human-readable message
• Additional context where applicable

See Error Codes for the complete list.

Data Types

Invoice Types

• Normal - Standard sale
• Copy - Invoice copy
• Training - Training mode invoice
• Proforma - Proforma invoice
• Advance - Advance payment

Transaction Types

• Sale - Standard sale transaction
• Refund - Return/refund transaction

Payment Types

• Cash - Cash payment
• Card - Credit/debit card
• Check - Check payment
• Wire Transfer - Bank transfer
• Other - Other payment methods

Best Practices

Request Handling

1. Always include RequestId - For request tracking and recovery
2. Implement retry logic - For transient network errors
3. Store responses - Keep fiscalization responses for audit purposes
4. Handle timeouts gracefully - API operations may take time during signing

Error Recovery

1. Check status before sending - Verify system is ready
2. Verify PIN first - Ensure PIN is verified before invoice submission
3. Handle all error codes - Implement handlers for all possible error conditions
4. Log all transactions - Maintain audit trail of API calls

Performance

1. Reuse connections - Keep HTTP connection alive when possible
2. Batch when appropriate - But note each invoice must be individually fiscalized
3. Monitor system status - Check for warnings before they become errors
4. Respect rate limits - Don't overwhelm the service

Integration Testing

Before going live:

1. Use the Create Test Invoice function to verify configuration
2. Test both online and offline modes
3. Verify QR code generation and validation
4. Test error handling and recovery scenarios
5. Validate with the Tax Authority test environment

Support

For API integration support:

• Review the Examples section
• Check Error Codes for troubleshooting
• Contact technical support with your integration questions