Complyance Java SDK v3.0.9-beta

Production-ready Java SDK for multi-country e-invoicing across KSA, Malaysia, Belgium, Germany, and UAE, with enterprise-grade features built for real-world applications.

Feature Summary

34 Types - Registered DocType support
5 Countries - KSA, Malaysia, Belgium, Germany, UAE supported
5 Overloads - Good Comply methods
v3.0 - Production ready

Installation

Automated Setup (Recommended)

The automated setup will detect your operating system and provide the correct instructions.

macOS & Linux

Install Java (JDK 11 or higher)
```
brew install openjdk@11
```

Set JAVA_HOME environment variable

export JAVA_HOME=$(/usr/libexec/java_home -v 11)

Verify installation
```
java -version
```

Windows

Download and install OpenJDK 11+
Set JAVA_HOME environment variable
Add Java to PATH

Manual Installation

Maven

Add the dependency to your pom.xml:

<dependency>
  <groupId>io.complyance</groupId>
  <artifactId>unify-sdk</artifactId>
  <version>3.0.9-beta</version>
</dependency>

Gradle

implementation 'io.complyance:unify-sdk:3.0.9-beta'

Windows Installation

Using Chocolatey (Recommended)

# Install Chocolatey (run as Administrator)
Set-ExecutionPolicy Bypass -Scope Process -Force
iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

# Install OpenJDK 11 and Maven
choco install openjdk11 maven -y

# Verify installation
java -version
mvn -version

PowerShell Profile Configuration

# Edit PowerShell profile
notepad $PROFILE

# Add these lines to your PowerShell profile:
$env:JAVA_HOME = "C:\Program Files\OpenJDK\openjdk-11"
$env:M2_HOME = "C:\Program Files\Apache\maven"
$env:PATH = "$env:JAVA_HOME\bin;$env:M2_HOME\bin;$env:PATH"

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



## Linux Installation

### Ubuntu/Debian

```bash
sudo apt update && sudo apt install -y openjdk-11-jdk maven
export JAVA_HOME="/usr/lib/jvm/java-11-openjdk-amd64"

CentOS/RHEL

sudo yum install java-1.8.0-openjdk-devel maven

Arch Linux

sudo pacman -S jre8-openjdk maven

Quickstart (Correct Workflow)

The SDK follows a structured Configure → API Key → Purpose (Payload) → Field Mapping → Test Bed → Invoicing flow. This process ensures your document data correctly translates to regulatory standards across all supported countries (KSA, Malaysia, UAE, etc.).

1) Configure the SDK (once per application)

Connect to the Complyance platform by providing your API key and defining your application source.

import io.complyance.sdk.Environment;
import io.complyance.sdk.GETSUnifySDK;
import io.complyance.sdk.SDKConfig;
import io.complyance.sdk.Source;
import io.complyance.sdk.SourceType;
import java.util.Arrays;

Source source = new Source("SourceName", "SourceVersion", SourceType.FIRST_PARTY);
SDKConfig config = new SDKConfig(
    "YOUR_API_KEY",
    Environment.SANDBOX, // Change to PRODUCTION when going live
    Arrays.asList(source)
);

GETSUnifySDK.configure(config);

2) Generate API Key

Use this quick flow to create and use your API key.

Sign in to the Complyance portal.
Go to Developer Portal.
Open Integration Engine.
Click Create Mapping.
Select country and document type, then click Next.
On the API/authentication step, click Generate API Key.
Choose the environment:
- Sandbox for testing
- Production for live submission
Copy the key and store it securely (secret manager or environment variable).
Use this key in your Java SDK config as YOUR_API_KEY.

3) Purpose Workflow (Payload)

The integration requires a specific logical sequence for the Purpose parameter to ensure data accuracy and compliance.

Step 1: MAPPING (Setup & Template Creation)

Set the Purpose to Purpose.MAPPING to push your raw payload data to the Complyance platform. This stage is used for field discovery and blueprinting.

Note: Before running mapping, update the country code based on your target country:

SA - Saudi Arabia

AE - UAE

BE - Belgium

DE - Germany

MY - Malaysia

In Code: Submit your payload using Purpose.MAPPING. At this stage, you may use null for the source name and version.
In Portal: Locate the uploaded payload in the Complyance portal, complete the field mapping until validations pass, and save it as a Template.
Final Step: Register and bind your unique sourceName and sourceVersion (e.g., my-app / 1.0) to this saved template.

import io.complyance.sdk.Country;
import io.complyance.sdk.BASE;
import io.complyance.sdk.MODIFIER;
import io.complyance.sdk.Mode;
import io.complyance.sdk.Operation;
import io.complyance.sdk.Purpose;
import io.complyance.sdk.UnifyResponse;
import io.complyance.sdk.GetsDocumentType;
import java.util.List;
import java.util.Map;

// Build your business payload
Map<String, Object> payload = Map.of(
    "invoice_data", Map.of(
        "document_number", "INV-2026-0001",
        "invoice_date", "2026-02-18",
        "currency_code", "SAR"
    ),
    "seller_info", Map.of("seller_name", "My Company"),
    "buyer_info", Map.of("buyer_name", "My Customer"),
    "line_items", List.of(
        Map.of("item_name", "Consulting", "quantity", 1, "unit_price", 1000.00)
    )
);

// Push for initial mapping
GetsDocumentType documentType = GetsDocumentType.builder()
  .base(BASE.TAX_INVOICE)
  .modifiers(MODIFIER.EXPORT)
  .build();

UnifyResponse mappingResponse = GETSUnifySDK.pushToUnify(
    null,            // sourceName
    null,            // sourceVersion
    documentType,
    Country.SA,      // Specify target country
    Operation.SINGLE,
    Mode.DOCUMENTS,
    Purpose.MAPPING,
    payload
);

Request example (MAPPING)

{
  "source": {
    "name": "pyke",
    "version": "16",
    "type": "FIRST_PARTY",
    "id": "pyke:16",
    "identity": "pyke:16"
  },
  "country": "AE",
  "operation": "SINGLE",
  "mode": "DOCUMENTS",
  "payload": {
    "supporting_documents": [
      {
        "id": "PO-2024-001234",
        "type": "purchaseOrderReference"
      }
    ],
    "invoice_data": {
      "prepaid_amount": 0.0,
      "document_number": "UAE-DBT-20260409185121294",
      "exchange_rate": 1.0,
      "total_allowances": 0.0,
      "due_date": "2026-05-09",
      "invoice_time": "14:30:00Z",
      "period_frequency": "MONTHLY",
      "debit_note_reason": "Additional charges",
      "document_id": "b7620dff-b440-4924-ba8a-aa3abdf5e8ac",
      "original_reference_id": "UAE-INV-ORIG-001",
      "currency_code": "AED",
      "invoice_date": "2026-04-09",
      "total_charges": 0.0,
      "rounding_amount": 0.0,
      "credit_note_reason": "Goods returned",
      "total_amount": 10500.0,
      "period_end_date": "2026-04-09",
      "line_extension_amount": 10000.0,
      "tax_exclusive_amount": 10000.0,
      "period_start_date": "2026-03-10",
      "total_tax_amount": 500.0,
      "amount_due": 10500.0,
      "tax_currency_code": "AED",
      "document_type": "tax_invoice"
    },
    "seller_info": {
      "additional_address": "Building 123",
      "seller_email": "contact@abctrading.ae",
      "seller_contact_name": "Ahmed Al Maktoum",
      "vat_number": "100819867100003",
      "registration_number": "CN-1234567",
      "peppol_id": "0235:1008213264",
      "vat_number_type": "TRN",
      "tax_scheme": "VAT",
      "state_province": "DUBAI",
      "registration_type": "TL",
      "street_name": "Sheikh Zayed Road",
      "country_code": "AE",
      "city_name": "Dubai",
      "seller_name": "ABC Trading LLC",
      "seller_trade_name": "ABC Trading",
      "seller_party_id": "SELLER-UAE-001",
      "seller_phone": "+971-4-1234567",
      "registration_scheme": "AE:TL",
      "authority_name": "Dubai Department of Economic Development",
      "postal_code": "00000",
      "building_number": "123"
    },
    "buyer_info": {
      "buyer_email": "purchasing@xyzcorp.ae",
      "buyer_country": "AE",
      "buyer_vat_type": "TRN",
      "buyer_building_number": "456",
      "buyer_registration_type": "TL",
      "buyer_phone": "+971-2-9876543",
      "buyer_name": "XYZ Corporation LLC",
      "buyer_state_province": "DUBAI",
      "buyer_street_name": "Al Wasl Road",
      "buyer_city": "Dubai",
      "buyer_additional_address": "Tower 2",
      "buyer_tax_scheme": "VAT",
      "buyer_authority_name": "Abu Dhabi Department of Economic Development",
      "buyer_trade_name": "XYZ Corp",
      "buyer_party_id": "BUYER-UAE-001",
      "buyer_registration_scheme": "TL",
      "buyer_peppol_id": "0235:1008213264",
      "buyer_vat_number": "100889867100003",
      "buyer_registration_number": "CN-9876543",
      "buyer_contact_name": "Fatima Al Mansouri",
      "buyer_postal_code": "00000"
    },
    "uae_extensions": {
      "unique_identifier": "b7620dff-b440-4924-ba8a-aa3abdf5e8ac",
      "buyer_authority_name": "Abu Dhabi Department of Economic Development",
      "business_process_type": "urn:peppol:bis:billing",
      "invoiced_object_id": "OBJECT-2024-001",
      "specification_identifier": "urn:peppol:pint:ae:invoice:v1",
      "taxpoint_date": "2026-04-09",
      "authority_name": "Dubai Department of Economic Development",
      "total_amount_including_tax_in_aed": 10500.0
    },
    "line_items": [
      {
        "tax_amount": 250.0,
        "quantity": 10.0,
        "batch_number": "BATCH-2024-001",
        "line_taxable_value": 5000.0,
        "item_type": "GOODS",
        "classification_code": "8471",
        "country_of_origin": "AE",
        "tax_category": "S",
        "item_name": "Office Equipment",
        "net_price": 5000.0,
        "unit_price": 5000.0,
        "line_id": "1",
        "tax_rate": 5.0,
        "line_total": 5250.0,
        "seller_item_code": "SKU-001",
        "unit_code": "EA",
        "gross_price": 5000.0,
        "classification_scheme": "HS",
        "item_description": "Professional office equipment package",
        "buyer_item_code": "BUYER-SKU-001"
      }
    ],
    "payment_info": {
      "account_id": "AE123456789012345678901",
      "payment_means_code": "IN_CASH",
      "payment_id": "PAY-001",
      "bank_id": "AEBN0001",
      "account_name": "ABC Trading LLC",
      "payment_means_text": "Bank Transfer",
      "remittance_info": "Payment for Invoice UAE-DBT-20260409185121294"
    },
    "payment_terms": [
      {
        "note": "Net 30 days",
        "amount": 10500.0,
        "due_date": "2026-05-09",
        "instructions_id": "TERMS-001"
      }
    ]
  },
  "apiKey": "ak_d13b9df3d4d1514ca1430d489a54",
  "requestId": "req_1775740881475_0.2917229556371743",
  "timestamp": "2026-04-09T13:21:21.475977Z",
  "env": "sandbox",
  "destinations": [
    {
      "type": "TAX_AUTHORITY",
      "details": {
        "country": "AE",
        "authority": "FTA",
        "documentType": "tax_invoice"
      }
    }
  ],
  "correlationId": null,
  "purpose": "mapping",
  "sourceOrigin": "SDK",
  "documentType": {
    "base": "tax_invoice",
    "modifiers": [
      "export"
    ]
  }
}

Success response example

{
  "status": "success",
  "message": "Unify request processed successfully",
  "data": {
    "source": {
      "sourceid": "680b1d0b-fc74-474f-a077-55103998f5b3",
      "id": "pyke",
      "created": false
    },
    "payload": {
      "payloadId": "01KNS6F3P5DDA6M2YTGWAFWT7D",
      "analysis": {
        "hasNested": true,
        "keys": [
          "supporting_documents",
          "invoice_data",
          "seller_info",
          "buyer_info",
          "uae_extensions",
          "line_items",
          "payment_info",
          "payment_terms",
          "meta",
          "documentType"
        ],
        "size": 3570
      }
    },
    "destinations": {
      "count": 1,
      "stored": true,
      "types": [
        "TAX_AUTHORITY"
      ],
      "valid": 1
    },
    "processing": {
      "processedAt": "2026-04-09T13:21:22.609Z",
      "requestId": "req_1775740881475_0.2917229556371743",
      "status": "completed"
    }
  },
  "metadata": {
    "requestId": "req_1775740881475_0.2917229556371743",
    "timestamp": "2026-04-09T13:21:22.609Z",
    "processingTime": 39,
    "version": "1.0"
  }
}

Error response

API authentication error (HTTP 401)

{
  "status": "error",
  "httpStatus": 401,
  "apiResponseBody": "Invalid API key",
  "errorCode": "AUTHENTICATION_FAILED",
  "message": "API request failed with HTTP 401",
  "suggestion": "Check your API key and ensure it is valid for the target environment"
}

Step 2: INVOICING (Production Submission)

After your template is successfully bound to your source identifiers on the portal, switch the Purpose to Purpose.INVOICING.

Action: The platform now recognizes your sourceName/sourceVersion and applies the saved template logic to transform and officially submit your payload data.
Requirement: You must provide the exact sourceName and sourceVersion that were bound to the template.

// Submit for production invoicing
GetsDocumentType documentType = GetsDocumentType.builder()
  .base(BASE.TAX_INVOICE)
  .modifiers(MODIFIER.EXPORT)
  .build();

UnifyResponse invoiceResponse = GETSUnifySDK.pushToUnify(
    "my-app",        // Registered sourceName
    "1.0",           // Registered sourceVersion
    documentType,
    Country.SA,
    Operation.SINGLE,
    Mode.DOCUMENTS,
    Purpose.INVOICING,
    payload
);

if (invoiceResponse != null && invoiceResponse.isSuccess()) {
    System.out.println("✅ Invoice submitted: " + invoiceResponse.getData().getSubmission().getSubmissionId());
}

Invoicing validation error response

{
  "status": "success",
  "message": "Invoicing request processed successfully",
  "data": {
    "source": {
      "sourceId": null,
      "sourceid": "19cf68b2-b1c3-423f-8f0f-11a90a951635",
      "type": null,
      "name": null,
      "version": null,
      "created": false,
      "id": "69a55cbf1908480073745005"
    },
    "payload": {
      "payloadId": "01KMMV73598W76YNYMVASNTDYH",
      "documentType": null,
      "country": null,
      "environment": null,
      "storedAt": null,
      "analysis": {
        "hasNested": true,
        "keys": [
          "additional_data",
          "buyer_info",
          "invoice_data",
          "line_items",
          "meta",
          "payment_info",
          "payment_terms",
          "seller_info",
          "supporting_documents",
          "uae_extensions"
        ],
        "size": 8231
      }
    },
    "template": {
      "templateId": "01KKJZBEG4C6NAX02X8P9P2QVZ",
      "templateName": null,
      "mappingCompleted": false,
      "totalMandatoryFields": null,
      "mappedMandatoryFields": null,
      "aiMappingApplied": null
    },
    "logicalDocumentType": null,
    "conversion": null,
    "document": {
      "documentId": "01KMMV7392T76HRE7X0NFCJZBX",
      "documentType": null,
      "createdAt": null,
      "metadata": null,
      "status": null
    },
    "validation": {
      "overallSuccess": false,
      "methods": null,
      "errors": [
        {
          "method": "gets",
          "message": "Line item price is required",
          "code": "GETS-LINE-005",
          "path": ["lineItems", 0, "price", "amount"]
        },
        {
          "method": "gets",
          "message": "Line item price is required",
          "code": "GETS-LINE-005",
          "path": ["lineItems", 1, "price", "amount"]
        },
        {
          "method": "gets",
          "message": "Document type must be a valid DOCUMENT_TYPES",
          "code": "GETS-GEN-005",
          "path": ["documentType"]
        }
      ],
      "validatedAt": "2026-03-26T10:32:06.517Z",
      "success": false
    },
    "submission": null,
    "processing": {
      "purpose": null,
      "completedSteps": null,
      "totalProcessingTime": null,
      "completedAt": null,
      "processedAt": "2026-03-26T10:32:06.747Z",
      "requestId": "req_1774521123558_c18c92ef6c5d47ed8bafb913ca08d771",
      "status": "completed"
    },
    "destinations": {
      "count": 1,
      "stored": true,
      "types": ["tax_authority"],
      "valid": 1
    }
  },
  "metadata": {
    "processingTime": 732,
    "requestId": "req_1774521123558_c18c92ef6c5d47ed8bafb913ca08d771",
    "timestamp": "2026-03-26T10:32:06.747Z",
    "version": "1.0"
  },
  "error": null
}

Why this structure is important:

MAPPING is the "Discovery" phase where you build the data blueprint.
The Portal is where you finalize the compliance logic and connect it to your application source.
INVOICING is the "Execution" phase where the SDK performs the actual regulatory submission using that blueprint.

4) Field Mapping

For a comprehensive understanding of all available fields, validation rules, and country-specific requirements, refer to our detailed Field Mapping Payload Reference.

This reference provides:

Complete field documentation for all supported countries (SA, MY, BE, DE, AE)
Country-specific requirements and compliance rules
Field descriptions with examples and validation rules
Required vs Optional field indicators

Review this reference to ensure your payload structure meets all regulatory requirements for your target country.

5) Test Bed

Use Test Bed to validate your mapping flow before live submission.

How it works:

Keep the SDK in Environment.SANDBOX.
Push your sample payload with Purpose.MAPPING.
The mapping flow passes that payload to the platform for validation and template checks.
Fix any mapping errors shown in portal.
After successful validation, switch to Purpose.INVOICING for submission.

Expected result:

Your sample payload gets processed through mapping without validation errors.
You are ready for controlled invoicing tests and then production rollout.

Reference (download)

Download the full class file: UAETaxInvoiceTest.java

Retrieval Status (Document Status API)

For retrieval, use the documentId from submission and call document status API through SDK.

import io.complyance.sdk.DocumentStatusResponse;

DocumentStatusResponse status = GETSUnifySDK.getDocumentStatus("PASTE_DOCUMENT_ID_HERE");
System.out.println("State: " + status.getData().getState());
System.out.println("Is Terminal: " + status.getData().isTerminal());

Run retrieval sample

mvn -q -f test-project/pom.xml compile exec:java \
  -Dexec.mainClass=io.complyance.test.RetrievalStatusSample

Reference (download)

Download the full retrieval sample: RetrievalStatusSample.java

Support

Contact: Contact Complyance for E-Invoicing - Complyance has helped over 1000+ organizations simplify global e-invoicing. Let us help you understand how Complyance can work for you.