Java SDK

Complyance Java SDK v3.0

Production-ready Java SDK with LogicalDocType enum support, automatic B2B/B2C classification, multi-country compliance (SA, MY), and enterprise-grade features. Built for real-world e-invoicing applications.

24 Types

LogicalDocType enum values

Multiple Countries

Saudi Arabia, Malaysia, and more

v3.0

Production Ready

Automated Setup (Recommended)

One-command setup that automatically detects your OS and installs Java 8, Maven, and configures environment variables

# Download and run the automated setup script
curl -O https://raw.githubusercontent.com/your-repo/complyance-unified/main/test-project/setup-java8.sh
chmod +x setup-java8.sh
./setup-java8.sh

The automated script detects your operating system and handles all dependencies, environment variables, and verification automatically.

Manual Installation by Platform

Step-by-step installation guide for each operating system

macOS Installation

Option A: Using Homebrew (Recommended)

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Java 8 (OpenJDK) and Maven
brew install openjdk@8 maven

# Verify installation
/usr/local/opt/openjdk@8/bin/java -version

Environment Configuration

# Open your zsh configuration file
nano ~/.zshrc

# Add these lines for Homebrew installation:
export JAVA_8_HOME="/usr/local/opt/openjdk@8"
export JAVA_HOME="$JAVA_8_HOME"
export PATH="$JAVA_8_HOME/bin:$PATH"

# Complyance SDK Environment Variables
export COMPLYANCE_API_BASE_URL="http://127.0.0.1:4000"
export COMPLYANCE_JWT_TOKEN="your-jwt-token-here"

# Create convenient aliases
alias java8="export JAVA_HOME=$JAVA_8_HOME && export PATH=$JAVA_8_HOME/bin:$PATH && java -version"
alias mvn8="export JAVA_HOME=$JAVA_8_HOME && mvn"

# Reload your shell configuration
source ~/.zshrc

Interactive Code Examples

Copy-paste ready examples demonstrating key SDK functionality

// Maven dependency (pom.xml)
<dependency>
    <groupId>io.complyance</groupId>
    <artifactId>unify-sdk</artifactId>
    <version>3.0.0-beta</version>
</dependency>

// Basic SDK Setup
import io.complyance.sdk.*;
import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;

public class ComplyanceSDKSetup {
    public static void main(String[] args) {
        try {
            // Configure source information (name, version, type)
            Source source = new Source(
                "example-source",           // Source name
                "1.1"          // Source version
            );

            // Create SDK configuration
            SDKConfig config = new SDKConfig(
                "ak_5ddc725b240f9fa39a336e65ceb4",
                Environment.SANDBOX,
                Arrays.asList(source)
            );

            // Initialize the SDK
            GETSUnifySDK.configure(config);
            
            System.out.println("✅ SDK configured successfully!");
            
        } catch (Exception e) {
            System.err.println("❌ SDK Configuration failed: " + e.getMessage());
        }
    }
}

Current API Methods

Available methods in the current SDK version

Primary Method: pushToUnify()

// Full control with LogicalDocType
UnifyResponse response = GETSUnifySDK.pushToUnify(
    String sourceName,           // Source identifier
    String sourceVersion,        // Source version  
    LogicalDocType logicalType,  // Document type (TAX_INVOICE, etc.)
    Country country,             // Target country (SA, MY)
    Operation operation,         // SINGLE
    Mode mode,                   // DOCUMENTS
    Purpose purpose,             // INVOICING or MAPPING
    Map<String, Object> payload, // Business data
    List<Destination> destinations // Optional: auto-generated if null
);

Available pushToUnify() Overloads

pushToUnify(sourceName, sourceVersion, logicalType, country, operation, mode, purpose, payload, destinations)

pushToUnify(sourceName, sourceVersion, logicalType, country, operation, mode, purpose, payload)

pushToUnify(sourceRef, logicalType, country, operation, mode, purpose, payload, destinations)

pushToUnify(sourceRef, logicalType, country, operation, mode, purpose, payload)

pushToUnify(unifyRequest) - For queue retry

Configuration Methods

GETSUnifySDK.configure(SDKConfig) - Initialize SDK

new SDKConfig(apiKey, environment, sources) - Main config

new Source(name, version, type) - Create source

Queue Management

getQueueStatus() - Check queue status

retryFailedSubmissions() - Retry failed items

processPendingSubmissions() - Process queue now

Current Implementation Status: The SDK currently only supports pushToUnify() methods with LogicalDocType. Convenience methods mentioned in v3.1 improvement docs (like submitInvoice(), createMapping(), and pushToUnifyLogical()) are commented out in the current codebase. Use the available pushToUnify() overloads.

SDK Usage Guide

Best practices and common patterns for using the Complyance Java SDK in production

Basic SDK Usage

// Configure SDK once at application startup
Source source = new Source("my-app", "1.0", SourceType.FIRST_PARTY);
SDKConfig config = new SDKConfig("your-api-key", Environment.SANDBOX, Arrays.asList(source));
GETSUnifySDK.configure(config);

// Submit invoices using LogicalDocType
UnifyResponse response = GETSUnifySDK.pushToUnify(
    "my-app", "1.0", LogicalDocType.TAX_INVOICE, 
    Country.SA, Operation.SINGLE, Mode.DOCUMENTS, 
    Purpose.INVOICING, payload);

Success Response Structure

UnifyResponse {
  status: "success",
  message: "Invoice processed successfully",
  data: {
    source: { sourceId: "src_123", name: "my-app", version: "1.0" },
    payload: { payloadId: "pl_456", documentType: "TAX_INVOICE", country: "SA" },
    template: { templateId: "tmpl_789", mappingCompleted: true },
    logicalDocumentType: { 
      originalType: "TAX_INVOICE",
      metaConfig: { isB2B: true, isExport: false, isPrepayment: false }
    },
    conversion: { success: true, conversionTime: 250 },
    document: { documentId: "doc_101", status: "created" },
    validation: { overallSuccess: true, methods: ["schema", "business"] },
    submission: { 
      submissionId: "req_1234567890_0.123456", 
      status: "accepted",
      response: { uuid: "uuid_123", qrCode: "qr_data", hash: "hash_456" }
    },
    processing: { purpose: "invoicing", totalProcessingTime: 1250 }
  },
  metadata: { requestId: "req_123", timestamp: "2024-01-15T10:30:00Z" }
}

Error Response Structure

UnifyResponse {
  status: "error",
  message: "Validation failed",
  error: {
    code: "VALIDATION_FAILED",
    message: "Required field 'invoice_number' is missing",
    suggestion: "Please provide a valid invoice number",
    field: "invoice_number",
    retryable: false,
    timestamp: "2024-01-15T10:30:00Z",
    context: { country: "SA", documentType: "TAX_INVOICE" }
  }
}

Key Features

24 LogicalDocType values - Complete document type coverage

Automatic B2B/B2C detection - Based on document type

Country restrictions - Environment-based validation

Payload Structure

invoice_data - Header fields and totals

seller_info - Supplier party details

buyer_info - Customer party details

line_items - Invoice line items

saudi_compliance - Country-specific flags

LogicalDocType Enum (24 Values)

Complete LogicalDocType enum with automatic B2B/B2C classification and meta configuration

B2B Document Types (12)

TAX_INVOICE - Standard B2B tax invoice
TAX_INVOICE_CREDIT_NOTE - B2B credit note
TAX_INVOICE_DEBIT_NOTE - B2B debit note
TAX_INVOICE_PREPAYMENT - B2B prepayment
TAX_INVOICE_PREPAYMENT_ADJUSTED - Adjusted prepayment
TAX_INVOICE_EXPORT_INVOICE - B2B export invoice
TAX_INVOICE_EXPORT_CREDIT_NOTE - Export credit note
TAX_INVOICE_EXPORT_DEBIT_NOTE - Export debit note
TAX_INVOICE_THIRD_PARTY_INVOICE - Third party invoice
TAX_INVOICE_SELF_BILLED_INVOICE - Self-billed invoice
TAX_INVOICE_NOMINAL_SUPPLY_INVOICE - Nominal supply
TAX_INVOICE_SUMMARY_INVOICE - Summary invoice

B2C Document Types (12)

SIMPLIFIED_TAX_INVOICE - Standard B2C simplified invoice
SIMPLIFIED_TAX_INVOICE_CREDIT_NOTE - B2C credit note
SIMPLIFIED_TAX_INVOICE_DEBIT_NOTE - B2C debit note
SIMPLIFIED_TAX_INVOICE_PREPAYMENT - B2C prepayment
SIMPLIFIED_TAX_INVOICE_PREPAYMENT_ADJUSTED - Adjusted prepayment
SIMPLIFIED_TAX_INVOICE_EXPORT_INVOICE - B2C export invoice
SIMPLIFIED_TAX_INVOICE_EXPORT_CREDIT_NOTE - Export credit note
SIMPLIFIED_TAX_INVOICE_EXPORT_DEBIT_NOTE - Export debit note
SIMPLIFIED_TAX_INVOICE_THIRD_PARTY_INVOICE - Third party invoice
SIMPLIFIED_TAX_INVOICE_SELF_BILLED_INVOICE - Self-billed invoice
SIMPLIFIED_TAX_INVOICE_NOMINAL_SUPPLY_INVOICE - Nominal supply
SIMPLIFIED_TAX_INVOICE_SUMMARY_INVOICE - Summary invoice

Automatic Configuration

The SDK automatically sets meta.config flags based on the LogicalDocType:

• isB2B - true for TAX_INVOICE types, false for SIMPLIFIED types
• documentType - uppercase enum mapping
• document_type - lowercase string for destinations
• isExport - true for EXPORT variants
• isPrepayment - true for PREPAYMENT variants

SDK Features & Capabilities

Enterprise-grade features for production applications

Core Features

Logical document type system with automatic B2B/B2C detection
Multi-country compliance (SA, MY with environment restrictions)
Automatic field mapping and validation
Comprehensive payload structure with 100% field coverage
Enhanced retry mechanisms with persistent queuing

Enterprise Features

Environment-based URL routing (DEV, TEST, STAGE, PROD)
Country restrictions by environment for compliance
Comprehensive logging and debugging
Circuit breaker pattern for API resilience
Thread-safe and scalable design

Troubleshooting Guide

Common issues and their solutions

Java Version Issues

# Check current Java version
java -version

# Switch to Java 8 (if multiple versions)
export JAVA_HOME=$JAVA_8_HOME        # Linux/macOS
$env:JAVA_HOME = $env:JAVA_8_HOME    # Windows

Compilation Issues

# Clean and rebuild
mvn clean compile

# Force clean if needed
rm -rf target/ && mvn compile        # Linux/macOS
Remove-Item -Recurse target/         # Windows PowerShell