Doc/comprehensive improvements

README.md

@@ -1,18 +1,109 @@
-# fiskaltrust interface documentation
+# fiskaltrust Interface Documentation
 _Welcome to the open-source documentation of the fiskaltrust interface!_
 
-This repository aims to provide a detailed technical specification of the fiskaltrust data interface used by POS-Systems to interact with the fiskaltrust.Middleware, so that PosCreators can integrate the fiskaltrust.Middleware into their systems without further support in most cases.
+This repository provides a comprehensive technical specification of the fiskaltrust data interface used by POS-Systems to interact with the fiskaltrust.Middleware. Our goal is to enable PosCreators to integrate the fiskaltrust.Middleware into their systems efficiently and independently.
 
-The technical specification of the data interface described in this document provides information regarding the following areas:
-1. Access to the fiskaltrust.Middleware
-2. Integration into the receipt based cash register workflow
-3. The data structure
-4. Function structure of the interface
-5. Types of communication with fiskaltrust.Middleware
-6. Operating categories
-Interface specification is provided by fiskaltrust.Interface NuGet package, which can be found at https://www.nuget.org/packages/fiskaltrust.interface
+## Quick Links
+- [Getting Started Guide](doc/general/getting-started.md)
+- [POS System API](doc/general/pos-system-api.md)
+- [API Reference](doc/general/api-reference.md)
+- [Troubleshooting Guide](doc/general/troubleshooting.md)
+- [Style Guide](doc/templates/style-guide.md)
 
-Official PDF documents that are built from the source in this repository can be found on the [Releases page](https://github.com/fiskaltrust/interface-doc/releases).
+## Documentation Structure
+
+### General Documentation
+- Installation and Setup
+- Configuration Options
+- Security Guidelines
+- Performance Optimization
+- Testing and Certification
+
+### API Documentation
+- [POS System API](doc/general/pos-system-api.md)
+  - Receipt Signing
+  - Journal Operations
+  - Configuration Management
+  - Error Handling
+- Integration Patterns
+- Authentication
+- Versioning
+
+### Country-Specific Documentation
+- [Austria (AT-RKSV)](doc/middleware-at-rksv/)
+- [Germany (DE-KassenSichV)](doc/middleware-de-kassensichv/)
+- [France (FR-BOI-TVA-DECL)](doc/middleware-fr-boi-tva-decl-30-10-30/)
+- [Italy (IT-RT)](doc/middleware-it-registratore-telematico/)
+
+### Technical Reference
+- API Specifications
+- Data Structures
+- Integration Patterns
+- Error Handling
+- Compliance Requirements
+
+## Contributing
+
+We welcome contributions from the community! Please follow these steps:
+
+1. Read our [Style Guide](doc/templates/style-guide.md)
+2. Fork the repository
+3. Create a feature branch
+4. Make your changes
+5. Submit a pull request
+
+### Documentation Standards
+- Use clear, concise language
+- Include practical examples
+- Provide complete code samples
+- Keep content up-to-date
+- Follow the style guide
+
+## Building the Documentation
+
+### Prerequisites
+- Node.js 14+
+- DocFX
+- PowerShell 5.1+
+
+### Build Steps
+1. Clone the repository
+   ```bash
+   git clone https://github.com/fiskaltrust/interface-doc.git
+   ```
+
+2. Install dependencies
+   ```bash
+   npm install
+   ```
+
+3. Build the documentation
+   ```bash
+   npm run build
+   ```
+
+### Testing Links
+```bash
+npm run test:links
+```
+
+## Support and Community
+
+- [GitHub Issues](https://github.com/fiskaltrust/interface-doc/issues)
+- [Support Portal](https://portal.fiskaltrust.cloud)
+- [Community Forum](https://forum.fiskaltrust.cloud)
+
+## License
+
+This documentation is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Version History
+
+| Version | Release Date | Major Changes |
+|---------|--------------|---------------|
+| 1.3     | 2024-01-01  | Added new country support |
+| 1.2     | 2023-06-01  | Enhanced API documentation |
+| 1.1     | 2023-01-01  | Initial release |
 
 ## Contributions
 By reviewing this README file in order to understand its structure and which tools are being used, you are contributing to improving this documentation.

doc/general/api-reference.md

@@ -0,0 +1,66 @@
+---
+slug: /api-reference
+title: API Reference
+---
+
+# API Reference
+
+## Available APIs
+
+### [POS System API](./pos-system-api.md)
+The POS System API is the central entry point to the fiskaltrust.Middleware. It provides:
+- Receipt signing and fiscalization
+- Journal operations
+- Configuration management
+- Error handling
+
+[Learn more about the POS System API](./pos-system-api.md)
+
+## API Overview
+
+### Authentication
+All APIs require proper authentication using:
+- CashBoxId
+- AccessToken
+
+### Versioning
+Our APIs follow semantic versioning:
+- Major version changes (v1 -> v2) include breaking changes
+- Minor version changes (v2.1 -> v2.2) are backward compatible
+- Latest version is used by default
+- Explicit version can be specified in URL
+
+### Common Headers
+| Header | Required | Description |
+|--------|----------|-------------|
+| x-operation-id | Yes | Idempotency key |
+| Authorization | Yes | Bearer token |
+| Content-Type | Yes | application/json |
+
+### Error Handling
+All APIs use standard HTTP status codes and return detailed error messages:
+```json
+{
+    "error": "error_code",
+    "message": "Human readable message",
+    "details": {
+        "field": "Specific field with error",
+        "reason": "Detailed explanation"
+    }
+}
+```
+
+## Integration Support
+
+### SDKs
+- [.NET SDK](https://github.com/fiskaltrust/middleware-interface-dotnet)
+- [Java SDK](https://github.com/fiskaltrust/middleware-interface-java)
+- [Node.js SDK](https://github.com/fiskaltrust/middleware-interface-nodejs)
+
+### Sample Code
+Find implementation examples in our [samples repository](https://github.com/fiskaltrust/middleware-demo).
+
+## Need Help?
+- [API Documentation](https://docs.fiskaltrust.cloud)
+- [Support Portal](https://portal.fiskaltrust.cloud)
+- [GitHub Issues](https://github.com/fiskaltrust/interface-doc/issues) 

doc/general/getting-started.md

@@ -0,0 +1,180 @@
+---
+slug: /getting-started
+title: Getting Started with fiskaltrust
+---
+
+# Getting Started with fiskaltrust
+
+Welcome to fiskaltrust! This guide will help you get started with integrating our solutions into your point-of-sale system.
+
+## Quick Start Guide
+
+### 1. Prerequisites
+Before you begin, ensure you have:
+- A fiskaltrust account
+- Your POS system requirements documented
+- Development environment setup
+- Required certificates (if applicable for your country)
+
+### 2. Choose Your Integration Path
+fiskaltrust offers multiple integration options:
+
+#### REST API
+Best for:
+- Web-based POS systems
+- Cross-platform applications
+- Modern architecture
+
+#### SOAP
+Best for:
+- Legacy systems
+- Windows-based applications
+- Systems requiring WS-* standards
+
+#### gRPC
+Best for:
+- High-performance requirements
+- Bi-directional streaming
+- Modern microservices
+
+### 3. Basic Implementation Steps
+
+1. **Install the Middleware**
+   ```powershell
+   # Windows installation example
+   ./fiskaltrust-middleware-setup.exe --mode=install
+   ```
+
+2. **Configure Your Environment**
+   ```json
+   {
+     "cashboxid": "your-cashbox-id",
+     "accesstoken": "your-access-token",
+     "endpoint": "your-endpoint"
+   }
+   ```
+
+3. **Test Your Connection**
+   ```csharp
+   // C# example
+   var client = new FiskaltrustClient(configuration);
+   var response = await client.Echo("test");
+   ```
+
+### 4. First Receipt
+Here's a minimal example of creating your first receipt:
+
+```csharp
+var request = new ReceiptRequest
+{
+    ftCashBoxID = "your-cashbox-id",
+    ftPosSystemId = "your-pos-id",
+    cbTerminalID = "your-terminal-id",
+    cbReceiptReference = "receipt-001",
+    cbReceiptMoment = DateTime.UtcNow,
+    ftReceiptCase = 0x4445000000000001,
+    cbPayItems = new[]
+    {
+        new PayItem
+        {
+            Quantity = 1.0m,
+            Description = "Test Item",
+            Amount = 10.00m,
+            VATRate = 19.00m
+        }
+    }
+};
+
+var response = await client.Sign(request);
+```
+
+## Next Steps
+
+After completing the basic setup, explore these topics:
+
+1. [Detailed Configuration Guide](./configuration.md)
+2. [Security Best Practices](./security.md)
+3. [Testing and Certification](./testing.md)
+4. [Country-Specific Requirements](./country-requirements.md)
+
+## Common Integration Patterns
+
+### Queue-based Processing
+```csharp
+// Example of queue-based receipt processing
+public async Task ProcessReceiptQueue()
+{
+    while (await _queue.HasItems())
+    {
+        var receipt = await _queue.Dequeue();
+        await _client.Sign(receipt);
+    }
+}
+```
+
+### Error Handling
+```csharp
+try
+{
+    var response = await client.Sign(request);
+}
+catch (FiskaltrustException ex)
+{
+    // Handle fiskaltrust-specific errors
+    Logger.Error($"Fiskaltrust error: {ex.Message}");
+}
+catch (Exception ex)
+{
+    // Handle general errors
+    Logger.Error($"General error: {ex.Message}");
+}
+```
+
+## Troubleshooting
+
+### Common Issues
+1. Connection Problems
+   - Check network connectivity
+   - Verify endpoint configuration
+   - Validate credentials
+
+2. Signing Errors
+   - Verify receipt format
+   - Check required fields
+   - Validate amounts and calculations
+
+### Getting Help
+- [Documentation](https://docs.fiskaltrust.cloud)
+- [Support Portal](https://support.fiskaltrust.cloud)
+- [GitHub Issues](https://github.com/fiskaltrust/interface-doc/issues)
+
+## Best Practices
+
+1. **Performance**
+   - Implement proper queuing
+   - Use connection pooling
+   - Cache when appropriate
+
+2. **Security**
+   - Secure credential storage
+   - Regular updates
+   - Audit logging
+
+3. **Reliability**
+   - Implement retry logic
+   - Handle offline scenarios
+   - Regular backups
+
+## Version Compatibility
+
+| Middleware Version | Features | Supported Until |
+|-------------------|----------|-----------------|
+| 1.3.x            | Basic    | 2024-12-31     |
+| 1.2.x            | Legacy   | 2023-12-31     |
+
+## Need Help?
+
+If you need assistance:
+1. Check our [FAQ](./faq.md)
+2. Search [existing issues](https://github.com/fiskaltrust/interface-doc/issues)
+3. Contact [support](mailto:support@fiskaltrust.cloud)