Complyance Logo

Quick Start Guide

Goal: Integrate the Complyance SDK and submit your first compliant e-invoice in under 10 minutes.

This guide provides a single, high-speed path to success for our production-ready SDKs: Java, PHP, and .NET.

1. Prerequisites

Before you write any code, ensure you have:

  • Complyance API Key: Log in to the Developer Portal to generate your key.
  • Target Environment:
    • Sandbox: For testing (Recommended for now).
    • Production: For live regulatory submissions.
  • Language Runtime: Java 11+, PHP 8.1+, or .NET 6+.

2. Installation

Install the library using your standard package manager.

Java (Maven)

Add to your pom.xml:

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

PHP (Composer)

composer require io.complyance/unify-sdk

.NET (NuGet)

dotnet add package Complyance.SDK.dotNet

3. Your First API Call

Use the following "Happy Path" examples to push a sample invoice to the Sandbox environment.

Important: The sourceName (e.g., "web-app") and sourceVersion (e.g., "1.0") serve as your unique application identity on our platform.

Java Implementation

import io.complyance.sdk.*;
import java.util.*;

public class ComplyanceQuickstart {
    public static void main(String[] args) {
        // 1. Setup Identity & Configuration
        Source source = new Source("web-app", "1.0", SourceType.FIRST_PARTY);
        SDKConfig config = new SDKConfig("YOUR_API_KEY", Environment.SANDBOX, Arrays.asList(source));
        GETSUnifySDK.configure(config);

        // 2. Prepare Sample Invoice Data
        Map<String, Object> payload = Map.of(
            "invoice_data", Map.of("document_number", "INV-001", "currency_code", "SAR"),
            "seller_info", Map.of("seller_name", "Test Vendor"),
            "buyer_info", Map.of("buyer_name", "Test Customer")
        );

        // 3. Submit for Processing
        UnifyResponse response = GETSUnifySDK.pushToUnify(
            "web-app", "1.0", LogicalDocType.TAX_INVOICE, Country.SA, 
            Operation.SINGLE, Mode.DOCUMENTS, Purpose.INVOICING, payload
        );
        
        System.out.println("Success! Submission ID: " + response.getData().getSubmission().getSubmissionId());
    }
}

PHP Implementation

<?php
require 'vendor/autoload.php';

use ComplyanceSDK\GETSUnifySDK;
use ComplyanceSDK\Models\{SDKConfig, Source};
use ComplyanceSDK\Enums\{SourceType, Environment, Purpose, LogicalDocType, Country};

// 1. Configure SDK Identity
$source = new Source("web-app", "1.0", SourceType::fromString(SourceType::FIRST_PARTY));
$config = new SDKConfig("YOUR_API_KEY", Environment::from(Environment::SANDBOX), [$source]);
GETSUnifySDK::configure($config);

// 2. Build Minimal Invoice
$payload = [
    'invoice_data' => ['document_number' => 'INV-' . time(), 'currency_code' => 'SAR'],
    'seller_info' => ['seller_name' => 'Test Vendor'],
    'buyer_info' => ['buyer_name' => 'Test Customer']
];

// 3. Official Submission
$response = GETSUnifySDK::pushToUnify(
    "web-app", "1.0", 
    LogicalDocType::from(LogicalDocType::TAX_INVOICE),
    Country::from(Country::SA),
    Purpose::from(Purpose::INVOICING),
    $payload
);

echo "Success! Submission ID: " . $response->getData()->getSubmission()->getSubmissionId();

.NET Implementation (C#)

using Complyance.SDK.dotNet;

// 1. Initialize Client
var client = new ComplyanceClient(new ComplyanceClientOptions {
    ApiKey = "YOUR_API_KEY",
    BaseUrl = "https://api.complyance.io" 
});

// 2. Build Invoice Model
var invoice = new Invoice {
    DocumentNumber = "INV-001",
    Currency = "SAR",
    Seller = new Party { Name = "Test Vendor" },
    Buyer = new Party { Name = "Test Customer" }
};

// 3. Submit
var result = await client.SubmitInvoiceAsync(invoice, "SA");
Console.WriteLine($"Success! Submission ID: {result.InvoiceId}");

4. Verify Success

A successful submission will return a status: SUCCESS. You can view the full details of the transformation and legal submission in two places:

  1. API Response: You will receive a unique submissionId (e.g., gets_sub_12345).
  2. Portal Activity: Log in to the Complyance Dashboard to see your document's status, QR code (for KSA), and transformation logs.

5. Troubleshooting Common Issues

Status CodeError MessageSolution
401UnauthorizedYour API key is invalid or for the wrong environment. Ensure you use Sandbox keys only for Environment.SANDBOX.
422Source Not BoundYour sourceName (e.g., "web-app") is not yet mapped inside the portal. See the Template Mapping guide.
400Required Field MissingCheck the message field for validation errors. This usually means a mandatory field (e.g., vat_number) is missing from your payload.
ENV_MISMATCHKey Environment ErrorSelf-Correction: Check that your code Environment enum matches your API Key's origin. A Sandbox key will fail if the SDK is set to PRODUCTION.
429Too Many RequestsYou have exceeded the rate limit for your tier. Implement exponential backoff and check your plan limits in the developer portal.

Next Steps