Developer Hub | FRAME Virtual Fiscalisation

Overview

This guide provides a comprehensive overview of how to integrate and utilize the Virtual Fiscalisation Library. It assists developers in registering fiscal devices, managing fiscal-related operations such as processing invoices and credit/debit notes, and ensuring compliance with ZIMRA requirements.

Key Benefits:

Simplified communication with ZIMRA
Abstracted complex fiscal processes
User-friendly high-level APIs
Full adherence to ZIMRA guidelines

Setting up the Library

1. Register a Device on ZIMRA Portal

Before using the API, you must register a fiscal device with ZIMRA to obtain your unique identifiers.

Device ID

Unique identifier for your device.

Serial Number

Physical serial of the device.

Activation Key

Key required for activation.

2. Acquire API Keys

Contact the FRAME sales team to acquire your development API key and library credentials. You will be provided with a username and a key, which you will use as your password for repository access.

sales@frame.co.zw

Maven Configuration

pom.xml Dependency

<dependency>
    <groupId>inc.frame</groupId>
    <artifactId>Frame-Virtual-Fiscalisation-Library</artifactId>
    <version>1.1.4</version>
</dependency>

settings.xml Configuration

Place this in your maven .m2 directory, replacing the library credentials with those provided by FRAME.

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0">
    <servers>
        <server>
            <id>frame-library-releases</id>
            <username>your_library_username</username>
            <password>your_api_key</password>
        </server>
    </servers>
    <profiles>
        <profile>
            <id>frame-repo</id>
            <repositories>
                <repository>
                    <id>frame-library-releases</id>
                    <url>https://framernd.tech/repository/frame-library-releases/</url>
                </repository>
            </repositories>
        </profile>
    </profiles>
</settings>

Installation

To pull the library from the Nexus repository, run the following command:

mvn clean install

Note: While we are committed to assisting with library integration, our base support package includes assistance in setting up the library. Custom solution development is the client's discretion unless a higher-tier agreement is in place.

Device Registration

1. Build Registration Request

public void registerDevice() {
    RegisterDeviceRequest request = RegisterDeviceRequest.builder()
        .deviceId(DEVICE_ID)
        .serialNumber(SERIAL_NUMBER)
        .activationKey(ACTIVATION_KEY)
        .build();

    RegisterDeviceResponse response = registerDevice(request);
}

2. Call Registration Service

public RegisterDeviceResponse registerDevice(RegisterDeviceRequest request) {
    FdmsDeviceRegistration service = new FdmsDeviceRegistration(SERVER_URL);
    try {
        return service.registerDevice(request);
    } catch (DeviceRegistrationException e) {
        throw new RuntimeException("Registration failed", e);
    }
}

Device Configurations

1. Build Configuration Request

public void getDeviceConfigurations() {
    DeviceConfigurationRequest request = DeviceConfigurationRequest.builder()
        .deviceId(DEVICE_ID)
        .build();

    DeviceConfigurationResponse configResponse = getDeviceConfigurations(request);
}

2. Call Configuration Service

public DeviceConfigurationResponse getDeviceConfigurations(DeviceConfigurationRequest request) {
    FdmsDeviceConfigurations configService = new FdmsDeviceConfigurations(SERVER_URL);
    try {
        return configService.getDeviceConfigurations(request);
    } catch (DeviceConfigurationException e) {
        throw new RuntimeException("Failed to get configurations", e);
    }
}

Fiscal Day Status

1. Build Status Request

public void getFiscalDayStatus() {
    FiscalDayStatusRequest request = FiscalDayStatusRequest.builder()
        .deviceId(DEVICE_ID)
        .build();

    FiscalDayStatusResponse statusResponse = getFiscalDayStatus(request);
}

2. Call Status Service

public FiscalDayStatusResponse getFiscalDayStatus(FiscalDayStatusRequest request) {
    FdmsFiscalDayStatus statusService = new FdmsFiscalDayStatus(SERVER_URL);
    try {
        return statusService.getFiscalDayStatus(request);
    } catch (FiscalDayStatusException e) {
        throw new RuntimeException("Failed to get fiscal day status", e);
    }
}

Opening a Fiscal Day

1. Build Open Day Request

public void openFiscalDay() {
    OpenFiscalDayRequest request = OpenFiscalDayRequest.builder()
        .deviceId(DEVICE_ID)
        .fiscalDay(LocalDate.now().format(DateTimeFormatter.ISO_LOCAL_DATE))
        .build();

    OpenFiscalDayResponse response = openFiscalDay(request);
}

2. Call Open Day Service

public OpenFiscalDayResponse openFiscalDay(OpenFiscalDayRequest request) {
    FdmsOpenFiscalDay openService = new FdmsOpenFiscalDay(SERVER_URL);
    try {
        return openService.openFiscalDay(request);
    } catch (OpenFiscalDayException e) {
        throw new RuntimeException("Failed to open fiscal day", e);
    }
}

Processing Invoices

Once you have an open fiscal day, you can start processing invoices. Each invoice must include the necessary details such as the invoice number, date, customer information, and line items.

public void processInvoice() {
    // Prepare Item List
    List<InvoiceLine> lines = Arrays.asList(
        InvoiceLine.builder()
            .itemCode("ITM001")
            .description("Consultation")
            .quantity(1)
            .unitPrice(BigDecimal.valueOf(100.00))
            .taxRate(BigDecimal.valueOf(15.00))
            .build()
    );

    // Build Request
    ProcessInvoiceRequest request = ProcessInvoiceRequest.builder()
        .deviceId(DEVICE_ID)
        .invoiceNumber("INV-2024-001")
        .customerName("Acme Corp")
        .lines(lines)
        .build();

    // Send to ZIMRA via FRAME
    ProcessInvoiceResponse response = sendInvoice(request);
}

Closing a Fiscal Day

1. Build Close Day Request

public void closeFiscalDay() {
    CloseFiscalDayRequest request = CloseFiscalDayRequest.builder()
        .deviceId(DEVICE_ID)
        .fiscalDay(LocalDate.now().format(DateTimeFormatter.ISO_LOCAL_DATE))
        .build();

    CloseFiscalDayResponse response = closeFiscalDay(request);
}

2. Call Close Day Service

public CloseFiscalDayResponse closeFiscalDay(CloseFiscalDayRequest request) {
    FdmsCloseFiscalDay closeService = new FdmsCloseFiscalDay(SERVER_URL);
    try {
        return closeService.closeFiscalDay(request);
    } catch (CloseFiscalDayException e) {
        throw new RuntimeException("Failed to close fiscal day", e);
    }
}

Important: Before closing the fiscal day, ensure that all transactions for the day have been processed, all invoices have been transmitted to ZIMRA, and you have a backup of all transaction data.

Contact & Support

Technical Support

For integration queries and library assistance.

support@frame.co.zw

Response within 24 hours

Emergency Support

Critical production issues only (24/7).

+263 77 123 4567

Support Hours (Harare Time)

Monday - Friday 8:00 AM - 5:00 PM Saturday 9:00 AM - 1:00 PM Sunday Closed

Troubleshooting Checklist

For faster resolution, please include the following in your request:

Library & Java version
Detailed issue description
Steps to reproduce
Error messages & logs

Office Location

1 Napier Ave., Hillside,
Bulawayo, Zimbabwe

General Inquiries

+263 86 7718 6045

frame.co.zw

Direct Client Integration

// Initialize FRAME Client
FrameClient client = new FrameClient.Builder()
    .setApiKey("your_api_key")
    .setEnvironment(Environment.PRODUCTION)
    .build();

// Execute device registration
DeviceResponse response = client.registerDevice(new DeviceRegistration(
    "YOUR_DEVICE_ID", 
    "YOUR_SERIAL_NUMBER", 
    "YOUR_ACTIVATION_KEY"
));