RS.ge API Java Library - Complete Monitoring Solution

A comprehensive Java library for integrating with Georgia's Government APIs - RS.ge (Revenue Service) and NTOS (Invoice API), featuring complete logging, monitoring, and web API capabilities.

🎯 Project Overview

This project provides a complete ecosystem for Georgian government API integration:

• 🚛 RS.ge API Library (rsge-api-java/) - Core API client for RS.ge Electronic Waybill system with 36 endpoints (97.2% success rate)
• 🧾 NTOS API Library (ntos-api-java/) - Standalone API client for NTOS invoice management with universal SOAP response parsing
• 📊 ELK Logging Integration (rsge-logging-elk/, ntos-logging-elk/) - Production-ready Elasticsearch, Logstash, Kibana monitoring
• 🌐 Unified Web API Gateway (rsge-web-api/) - RESTful wrapper with OpenAPI/Swagger documentation for both systems
• 🧪 Test Applications (rsge-test-app/) - Comprehensive testing suites and real-world examples
• 📈 Monitoring Dashboard (kibana/) - Pre-configured Kibana dashboards with 5 specialized views
• 📚 Complete Documentation - Extensive guides, API references, and integration examples

🔗 Unified Authentication

Both RS.ge and NTOS APIs use the same username format (USER:XXXXXXX) and credentials, providing seamless integration across Georgian government services.

🚀 Quick Start

Prerequisites

• Java 8+
• Docker & Docker Compose (for monitoring)
• Gradle 7+
• 4GB+ RAM (for ELK stack)

1. Setup and Build

# Clone the repository
git clone git@github.com:rvardiashvili/rsge-api-java.git
cd rsge-api-java

# Build all modules
./gradlew build

# Build library JARs
./rebuildlib.sh

2. Start Monitoring (Optional but Recommended)

# Start ELK stack for logging
./start-elk.sh

# Setup Kibana dashboards
./kibana-setup.sh

3. Run Test Application

cd rsge-test-app
./run.sh

4. Access Monitoring

• Kibana Dashboards: http://localhost:5601
• Elasticsearch: http://localhost:9200
• API Documentation: See individual module READMEs

📁 Project Structure

rsge-api-java/
├── 📚 rsge-api-java/           # Core RS.ge API Java library
│   ├── src/main/java/          # Main library source code
│   ├── documentation/          # API documentation and guides
│   └── examples/               # Usage examples
├── 📊 rsge-logging-elk/        # ELK Stack integration
│   └── src/main/java/          # Elasticsearch logging implementation
├── 🌐 rsge-web-api/           # REST API wrapper
│   ├── src/main/java/          # Spring Boot web application
│   └── src/main/resources/     # Configuration files
├── 🧪 rsge-test-app/          # Test and demonstration app
│   ├── src/main/java/          # Test application source
│   └── *.sh                   # Test execution scripts
├── 🐳 docker/                 # Docker configurations
│   └── elk/                   # ELK stack Docker setup
├── 📈 kibana/                 # Kibana monitoring setup
│   ├── config/                # Dashboard configurations
│   ├── scripts/               # Setup and maintenance scripts
│   └── README.md              # Detailed monitoring guide
├── 🛠️ start-elk.sh            # Start ELK stack
├── 🎨 kibana-setup.sh         # Complete Kibana setup
└── 📖 Project documentation    # This and other guides

🔧 Core Components

🚛 RS.ge API Java Library

Advanced Electronic Waybill API client with:

• Complete API Coverage: All 36 endpoints implemented (97.2% success rate)
• Waybill Management: Create, read, update, delete, and lifecycle management
• Advanced Features: PDF generation, buyer operations, template management
• Reference Data: Complete access to waybill types, units, transportation types, wood types
• Builder Patterns: Fluent WaybillBuilder with enhanced functionality
• Foreign Citizen Support: Handle both Georgian and international TINs

Key Features:

• Type Safety: Full enum coverage for all RS.ge constants and error codes (152+ mapped)
• Enhanced XML Parsing: Proper data extraction and comprehensive response handling
• Automatic Error Handling: Complete error code mapping with detailed descriptions
• Time-based Filtering: Smart waybill queries with 3-day limit enforcement
• Internal Transfer Fix: Critical buyer TIN validation issues resolved (August 2025)

🧾 NTOS API Java Library

Comprehensive Invoice API client featuring:

• Universal SOAP Parser: Single parser handles all known NTOS response tags dynamically
• Complete Operation Coverage: Authentication, invoice management, user operations, declarations
• Flexible Architecture: Stateless service design with maximum flexibility
• Type Conversion: Automatic data type handling (string, int, long, boolean, decimal, datetime)
• Enhanced Error Handling: Robust error detection and detailed failure information

Recent Enhancements:

• Universal Response Parsing: Consolidated multiple parsers into single, comprehensive solution
• Auto-populated Authentication: User IDs automatically filled from authentication responses
• Invoice Description Support: Complete get_invoice_desc functionality implemented
• Enhanced Logging: Comprehensive business and system event tracking

📊 ELK Logging Integration

Production-ready logging solution:

• Structured Logging to Elasticsearch
• Real-time Monitoring with Kibana
• Performance Metrics and alerting
• Business Intelligence dashboards

Automatic Tracking:

• API call performance and success rates
• Authentication and authorization events
• Business operations (waybill processing)
• Error analysis and troubleshooting data

🌐 Unified Web API Gateway

Advanced RESTful wrapper providing:

• Dual API Support: Single gateway for both RS.ge and NTOS operations
• OpenAPI/Swagger: Interactive documentation and testing interface
• Spring Security: Integrated authentication with session management
• Unified Authentication: Shared credentials across both government systems
• Comprehensive Validation: Server-side validation with detailed error responses
• ELK Integration: Real-time monitoring and structured logging

API Features:

• RS.ge Operations: Complete waybill lifecycle management via REST
• NTOS Operations: Full invoice management through unified interface
• Foreign Citizen Support: Handle international TINs and validation
• Template Management: Save and retrieve waybill templates
• Reference Data: Access all government reference data through REST endpoints

🧪 Test Applications & Validation

Production-ready testing infrastructure:

• Comprehensive Test Suite: Automated testing for all 36+ endpoints
• Interactive Testing Tools: Command-line interfaces for manual testing
• Performance Benchmarking: Response time and throughput analysis
• Real-world Examples: Georgian business scenarios with actual data patterns
• Validation Scripts: Automated validation of API responses and data integrity

Testing Coverage:

• Success Rate Tracking: 97.2% success rate across all RS.ge endpoints
• Error Scenario Testing: Comprehensive error handling validation
• Integration Testing: Cross-system testing between RS.ge and NTOS
• Load Testing: Performance validation under concurrent usage

📊 Monitoring & Analytics

Pre-configured Dashboards

1. 🎯 Overview Dashboard - High-level metrics and KPIs
2. 🔐 Authentication Dashboard - Login and security monitoring
3. ❌ Error Analysis Dashboard - Detailed error tracking
4. 📄 Waybill Operations Dashboard - Business process monitoring
5. ⚡ Performance Dashboard - Response time and throughput analysis

Key Metrics Tracked

• Performance: Response times, throughput, slow operations
• Reliability: Success rates, error types, failure patterns
• Usage: User activity, operation frequency, peak times
• Business: Waybill processing, transaction volumes

🛠️ Development Setup

Build Individual Modules

# Build core library
cd rsge-api-java && ./gradlew build

# Build ELK integration  
cd rsge-logging-elk && ./gradlew build

# Build web API
cd rsge-web-api && ./gradlew build

Run Tests

# Run all tests
./gradlew test

# Run integration tests
cd rsge-test-app && ./demo_comprehensive_testing.sh

Development with Monitoring

# Start monitoring stack
./start-elk.sh

# Run development application with logging
cd rsge-test-app && ./run.sh

# View logs in real-time
# Open http://localhost:5601

🔐 Configuration

Core Library Configuration

RsGeConfig config = RsGeConfig.builder()
    .baseUrl("https://rs.ge/soap/waybill")
    .username("your-username")
    .password("your-password")
    .timeout(30000)
    .retryCount(3)
    .build();

ELK Integration

# application.yml
rsge:
  logging:
    elk:
      enabled: true
      elasticsearch-url: http://localhost:9200
      index-prefix: rsge-api-logs

🆕 Recent Improvements (2025 Updates)

RS.ge API Enhancements

• ✅ Internal Transfer Fix: Resolved critical buyer TIN validation issues for internal waybill operations
• ✅ Enhanced XML Parsing: Improved data extraction with proper response handling for all endpoints
• ✅ Foreign Citizen Support: Complete support for international drivers and buyers with TIN validation bypass
• ✅ Performance Optimization: 97.2% success rate achieved across all 36 endpoints

NTOS API Major Updates

• 🚀 Universal SOAP Parser: Revolutionary single parser handles all known NTOS response tags dynamically
• 🔄 Enhanced Authentication: Auto-populated user IDs from authentication responses for seamless integration
• 📋 Invoice Description API: Complete implementation of get_invoice_desc functionality
• 🔧 Type Safety: Advanced type conversion system for all SOAP response data types

Infrastructure Improvements

• 📊 Dual ELK Integration: Separate logging systems for RS.ge and NTOS with specialized dashboards
• 🌐 Unified Web Gateway: Single REST API for both government systems with shared authentication
• 🧪 Enhanced Testing: Comprehensive validation suites with real Georgian business scenarios
• 📚 Complete Documentation: Extensive guides, examples, and reference materials

📚 Documentation

🚀 Quick Start Guides

• RS.ge Library README - Comprehensive RS.ge API documentation with latest features
• NTOS Library README - Complete NTOS API guide with universal parser details
• Web API README - REST API documentation with dual-system support
• Integration Guide - Step-by-step integration for both systems

📖 Technical References

• API Endpoints Guide - Complete endpoint reference (36 RS.ge endpoints)
• Waybill Workflow Guide - Business process documentation
• Logging Guide - Complete logging configuration options
• Testing Guide - Testing strategies and validation

🛠️ Operations & Monitoring

• Kibana Setup Guide - Complete monitoring setup with 5 specialized dashboards
• ELK Integration - Production-ready monitoring stack configuration
• Performance Optimization - Tuning guides for high-throughput scenarios

🤝 Contributing

Getting Started

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature
3. Make your changes with tests
4. Run the test suite: ./gradlew test
5. Submit a pull request

Development Guidelines

• Follow Java 8+ coding standards
• Write comprehensive tests for new features
• Update documentation for API changes
• Ensure ELK monitoring works for new operations
• Test integration scenarios thoroughly

Code Quality

• Use provided code style configurations
• Run linting: ./gradlew checkstyleMain
• Maintain test coverage above 80%
• Document public APIs with Javadoc

🚀 Deployment

Production Deployment

# Build production JARs
./gradlew clean build -Pprofile=production

# Deploy ELK stack (production configuration)
docker-compose -f docker/elk/docker-compose.elk.yml up -d

# Deploy web API
java -jar rsge-web-api/build/libs/rsge-web-api-*.jar

Docker Deployment

# Build Docker images
docker build -t rsge-web-api ./rsge-web-api

# Run with Docker Compose
docker-compose up -d

🐛 Troubleshooting

Common Issues & Solutions

1. API Connection Issues

Symptoms: Connection timeouts, authentication failures Solutions:

• Verify RS.ge/NTOS service status and credentials
• Check username format: USER:XXXXXXX (both systems use same format)
• Validate network connectivity and firewall settings
• Review API endpoint URLs in configuration

2. ELK Stack Issues

Symptoms: Kibana inaccessible, no log data visible Solutions:

• Ensure Docker has sufficient memory (4GB+ recommended)
• Verify all containers are running: docker ps
• Check Elasticsearch health: curl "http://localhost:9200/_cluster/health"
• Restart ELK stack: ./start-elk.sh

3. Build & Compilation Issues

Symptoms: Gradle build failures, dependency issues Solutions:

• Verify Java 8+ and Gradle 7+ versions
• Clean and rebuild: ./gradlew clean build
• Check library dependencies in libs/ directories
• Run ./rebuildlib.sh to regenerate library JARs

4. NTOS Universal Parser Issues

Symptoms: Parsing errors, missing response data Solutions:

• Check SOAP response format against known tags in parseNtosSoapResponse
• Verify data type conversion for new response fields
• Enable SOAP logging to debug response structure

5. RS.ge Internal Transfer Issues (Resolved in 2025)

Symptoms: Buyer TIN validation errors for internal waybills Solution: ✅ Fixed - Internal transfer validation now properly handles same-organization waybills

🔧 Diagnostic Tools

• Health Checks: Use /actuator/health endpoints in web API
• SOAP Logging: Enable detailed request/response logging
• ELK Dashboards: Real-time error monitoring and analysis
• Test Scripts: Use rsge-test-app/ for validation and debugging

📞 Support Resources

• 📖 Documentation: Comprehensive guides in each module with examples
• 🧪 Examples: Working code examples in rsge-test-app/ and examples/
• 📊 Monitoring: Real-time debugging with specialized ELK dashboards
• 🔍 Issue Tracking: Detailed error logging with correlation IDs
• 📋 Validation Scripts: Automated testing tools for system validation

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🏷️ Version Information

• Current Version: 2.0.0 (2025 Release)
• Java Compatibility: 8+ (Web API requires Java 17+)
• Spring Boot Version: 2.7+ (Web API uses 3.0+)
• ELK Stack Version: 8.8.0
• RS.ge API Coverage: 36 endpoints (97.2% success rate)
• NTOS API Coverage: 25+ operations with universal parsing

📋 Module Versions

• RS.ge API Library: v2.0.0 (Enhanced XML parsing, foreign citizen support)
• NTOS API Library: v2.0.0 (Universal SOAP parser, auto-populated auth)
• Web API Gateway: v2.0.0 (Dual-system support, unified authentication)
• ELK Integration: v2.0.0 (Specialized dashboards, enhanced monitoring)

🎯 Compatibility Matrix

Component	Java 8	Java 11	Java 17+	Spring Boot 2.7+	Spring Boot 3.0+
RS.ge API Library	✅	✅	✅	✅	✅
NTOS API Library	✅	✅	✅	✅	✅
ELK Integration	✅	✅	✅	✅	✅
Web API Gateway	❌	❌	✅	❌	✅
Test Applications	✅	✅	✅	✅	✅

---

🎯 Next Steps

For New Users

1. 📖 Start with Documentation: Review module READMEs for your specific use case
2. 🚀 Quick Setup: Follow the Quick Start guide for immediate results
3. 🧪 Run Examples: Use test applications to understand functionality
4. 📊 Setup Monitoring: Configure ELK stack for production visibility

For Developers

1. 🔧 Integration: Begin with the appropriate module (RS.ge, NTOS, or Web API)
2. 🧪 Testing: Use comprehensive test suites for validation
3. 📈 Monitoring: Implement ELK logging for operational insight
4. 📚 Documentation: Refer to extensive guides and API references

📞 Need Help? Check the documentation in each module's README or create an issue for support.

🔄 Stay Updated: Watch this repository for the latest features, bug fixes, and improvements.

⭐ Found it Useful? Star the repository to show your support for continued development!