SDK Guide for E-Invoicing Integration with Fatoora

If you are a developer building an integration with the Fatoora platform, you have two paths ahead: call the raw API interfaces yourself, or rely on a software development kit (SDK) that spares you a large share of the repetitive work. This page explains what an SDK offers in the context of e-invoicing, how to choose and install one, what a simplified example of setup and issuing a first invoice looks like, when using an SDK is better than the raw API, and how to build your own wrapper if you cannot find a ready-made package that suits you.

We speak here in general terms about the concept of the SDK, not about a specific package by name. Qoyod provides an integration API, but the focus of this page is on the principle: how to wrap the complex API layer (authentication, XML building, signing, and calling the interfaces) behind simple functions you call from your code. The goal is that you finish knowing when a package genuinely saves you time, and when building it or doing without it is wiser.

Read this page after you have reviewed An overview of the e-invoicing API, as it explains the interface layer that the package wraps. And when you reach the stage of actually sending invoices, you will find its details on the Sending the invoice via APIpage. This page links the two concepts: what the package shortens from that work, and what remains on your shoulders.

What is a software development kit (SDK) and why do you need it?

A software development kit (SDK) is a set of ready-made libraries and tools in a specific programming language that wraps the handling of an API behind clear functions. Instead of writing an HTTP request manually, building its headers, signing its payload, and parsing its raw response, you call a single function with a meaningful name such as «issue invoice» and the package takes care of the rest behind the scenes.

The essential benefit is that the package moves the complexity out of your code and into itself. Handling e-invoicing requires precise technical steps: generating the cryptographic stamp (Cryptographic Stamp), computing the hash (Hash) of the previous invoice to guarantee chain integrity, building an XML file in the approved UBL format, and managing the CSID certificate. A well-designed package hides these steps behind a simple interface, so you write your business logic, not cryptography logic.

The value of the package boils down to four things it shortens on your behalf. It handles authentication, manages tokens (Tokens) and their renewal. It builds the XML file from the invoice data without you writing its tags manually. It signs the invoice and appends the hash and the QR code to it. And finally it calls the correct interface (clearance or reporting) and returns the result to you in a readable format. These four layers are what consume most of the time of building an integration from scratch.

There is a less obvious benefit that is no less important: reducing the surface of error. Every line of code you write yourself to handle cryptography or build the XML is an additional chance of error. A package tested on thousands of invoices has already tried the edge cases that have not yet occurred to you, such as invoices with many line items, or line-level discounts, or currencies and fractions. Relying on proven code is safer than reinventing the same logic.

The package also gives you a unified error format. The raw API may return error messages in different formats depending on the interface, while a good package gathers them into one consistent format that your code handles easily. This unification simplifies error logging (Logging) and monitoring later in production, an aspect that is neglected at the start and then becomes decisive at the first real problem.

What exactly does the package wrap?

To understand the value of the package in practice, look at what you would have to write manually if you dealt with the API directly. Every invoice passes through a chain of steps, and the package reduces this chain to a single call. Below are the layers the package handles, and what you would have written yourself in their absence.

1. Authentication and token management

Integrating with the Fatoora platform requires authentication based on a CSID certificate and temporary access tokens. In the raw API you request the token, store it, watch for its expiry, and renew it before each call. The package hides this entire cycle: you pass the credentials once at setup, and the package manages the tokens and renews them automatically before each request.

2. Building the XML file

The electronic invoice is not free-form data, but an XML file in UBL format that follows strict validation rules. Building this file manually is prone to errors in the order of tags and in the formatting of fields. The package takes a simple invoice object (line items, prices, tax, customer data) and builds from it a structurally correct XML file, so you avoid the validation errors that cause the invoice to be rejected.

3. Signing, hashing, and the QR code

Every invoice must carry a cryptographic stamp, a unique identifier (UUID), a hash of the previous invoice, and a QR code built according to the approved TLV format. These are the most sensitive steps and the hardest for someone building them for the first time. The package handles them fully right after building the XML, so you do not deal with the low-level cryptography details yourself.

4. Calling the correct interface

After signing, the invoice is sent to the clearance interface (Clearance) if it is a business invoice (B2B), or to the reporting interface (Reporting) if it is a consumer invoice (B2C). The package chooses the correct path based on the invoice type, and returns to you the approval or rejection result in a unified format, so you do not memorize the interface addresses nor the differences between their two paths.

The takeaway is that the package does not add a new capability that does not exist in the API; rather it re-wraps the same capabilities in a safer and faster-to-use form. The ultimate responsibility for the correctness of the invoice data remains on your shoulders, but the distance between your data and an approved invoice becomes much shorter.

How do you choose a suitable software development kit?

Choosing the package is a decision that affects your project for years, so do not rush it. Before you choose, verify several practical criteria that distinguish the reliable package from the one that will leave you stuck later. It is not enough that it «works today»; it must also stay supported tomorrow.

The first criterion is language and compatibility. Make sure the package is written for the language your project runs on (PHP, or Python, or Node.js, or others), and that it supports the language version you use. A package written for an old version may block your project upgrade later, so this criterion balances immediate convenience against future flexibility.

The second criterion is maintenance recency. The Fatoora platform updates its specifications periodically, and a package that has not been updated for a long time may stop keeping up with the latest validation rules. Review the date of the last update, the number of open issues (Issues), and the speed of responding to them. A live package with regular maintenance is more important than a feature-complete but abandoned one.

The third criterion is coverage and documentation. Verify that the package covers both environments (sandbox and production), supports the invoice types you need (B2B, B2C, and credit and debit notes), and that its documentation is clear with ready examples. Good documentation saves days of experimentation, and its absence is a sign of a difficulty coming at the first problem.

The fourth criterion is licensing and source. Examine the package’s license to make sure it permits commercial use, and know who stands behind it: an official provider, an open-source community, or an individual. This determines how far you can depend on it in the long term, and how far you can fix it yourself if needed.

Installing and configuring the package

After choosing the package, installation comes next. Most packages are installed via the language’s package manager, so you do not need to copy files manually. Below are examples of installation in three common environments, with a note that the actual package name depends on the provider you chose.

# PHP (Composer)
composer require vendor/einvoice-sdk

# Node.js (npm)
npm install einvoice-sdk

# Python (pip)
pip install einvoice-sdk

After installation, you configure the package with your own credentials: the base URL (Base URL) of the environment you work on, the CSID certificate, and the secret key. The golden rule is to always start from the sandbox environment (Sandbox), and to never put production data directly in your code, but rather in isolated environment variables (Environment Variables). Below is a simplified configuration example in PHP.

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

use Vendor\EInvoice\Client;

// Configuration on the sandbox environment
$client = new Client([
    'environment' => 'sandbox',          // sandbox | production
    'csid'        => getenv('FATOORA_CSID'),
    'secret'      => getenv('FATOORA_SECRET'),
]);

Notice how the package shortened everything related to the base URL and token management into a single object. You did not write an HTTP request, did not build an authentication header, and did not deal with token renewal. This is the practical value of the package: one setup, then you focus on issuing invoices.

A practical example: issuing your first invoice

After setup, issuing the invoice becomes a single step. You build the invoice object with simple data (customer, line items, tax), then call the issue function, and the package takes care of building the XML, signing, appending the hash and the QR code, and calling the correct interface. Below is a simplified example that illustrates the idea.

// Build the invoice data
$invoice = [
    'type'     => 'standard',          // standard (B2B) | simplified (B2C)
    'customer' => [
        'name' => 'Example Trading Company',
        'vat'  => '300000000000003',
    ],
    'items' => [
        [
            'description' => 'Consulting service',
            'quantity'    => 1,
            'price'       => 1000.00,
            'vat_rate'    => 15,        // 15%
        ],
    ],
];

// A single call handles all the layers
$result = $client->issueInvoice($invoice);

if ($result->isCleared()) {
    echo 'Invoice approved: ' . $result->getUuid();
} else {
    echo 'Invoice rejected: ' . $result->getErrorMessage();
}

The idea you must grasp from this example is that the package does not eliminate the two-step dialogue with the Fatoora platform, but rather hides it. The invoice is still sent, then reviewed, then approved or rejected, but you deal with a ready-made result through the two functions isCleared() and getErrorMessage() instead of parsing the raw response yourself.

Notice too that the example covers both paths: acceptance and rejection. This is not a cosmetic detail, but the essence of a sound integration. The package shortens the work, but it does not exempt you from handling rejection. The invoice may be rejected for an error in a tax number or in a mandatory field, and you must read the reason for rejection and correct it. A professional’s integration covers both paths from day one.

When do you use a ready-made package and when do you deal with the raw API?

The package is not always the optimal choice. There are cases where a tool saves you precious time, and other cases where dealing directly with the API is wiser. The decision depends on the nature of your project and how much you need fine-grained control.

Use a ready-made package when your goal is fast issuance, when your use cases are standard (ordinary business and consumer invoices), and when you do not want to maintain cryptography and signing logic yourself. The package here shortens weeks of work, reduces the surface of error, and gives you specification updates for free with each new release of it.

Deal with the raw API when you need fine-grained control the package does not provide, or when you build non-standard use cases (such as complex invoicing scenarios or integration with a private internal system), or when you cannot find a reliable, well-maintained package in your language. Direct handling gives you full flexibility, but it burdens you with the responsibility for every layer the package would have handled.

The real trade-off is between speed and control. The package buys you speed at the cost of some control, and the raw API buys you control at the cost of some time. There is no absolutely right choice, but rather a choice suited to your project. And in many cases, a ready-made accounting system such as Qoyod is wiser than both when the technical integration itself is not the goal of your project.

There is another dimension many overlook in this trade-off: the cost of maintenance over the long term. A good package carries for you the burden of keeping up with the Fatoora platform’s updates, so whenever a validation rule changes or a new field is added, the package provider issues an updated release that you install with a single command. But with the raw API, you are the one who tracks these changes and applies them manually. Factor in this recurring cost, not just the initial build cost, for it is the real difference between the two options over the years.

A third dimension worth thinking about is the size of your team and its experience. The small team that lacks low-level cryptography and signing experience benefits more from the package, because it spares them a field that is hard to master quickly. The large team with deep experience in security and integration may prefer full control. Choose based on your team’s actual capabilities, not based on what you wish it were.

Building your own wrapper around the API

If you do not find a ready-made package that suits your language or case, the middle option is to build your own wrapper. The wrapper is a thin layer you write once on top of the raw API, in which you gather the logic of authentication, XML building, and signing into internal functions, then the rest of your code calls them as if it were a ready-made package. This way you get the convenience of the package with full control over its details.

Start by building a single class (Class) that handles authentication and token renewal internally, so you do not repeat authentication logic in every call. Make the class read credentials from environment variables, store the token, and renew it automatically before its expiry. This layer alone saves you a great deal of repetition in the rest of the project.

After that, add high-level functions that reflect your business language, not the API’s language: a issueInvoice() function that builds the XML, signs it, and sends it, and a cancelInvoice() function for credit notes, and so on. The idea is that the rest of your project never sees the raw API details, but rather sees a clean interface in invoicing terms. This keeps integration maintenance focused in one place.

The major advantage of your own wrapper is that you isolate the changes. When the Fatoora platform updates its specifications, you modify your wrapper in one place without touching the rest of the code. And when you test, you test the wrapper alone. This pattern (isolating the integration behind a single layer) is a sound engineering practice whether you used a ready-made package or built your own wrapper.

Note, however, that your own wrapper burdens you with a responsibility that does not end at the first writing. You are the one who tracks the Fatoora platform’s updates and applies them to your wrapper, you are the one who writes tests covering its cases, and you are the one who fixes its failures. So do not build a wrapper unless you are ready to maintain it over the long term. A neglected wrapper is worse than the raw API, because it hides a complexity that has stopped working without your knowing.

A final practical piece of advice: whatever your path (package, wrapper, or raw API), isolate the credentials from the code, log every request and response in production, and test both the acceptance and rejection paths before the first real invoice. These three practices benefit you on every path, and save you hours of diagnosis when a problem appears in production. A sound integration is not measured by the success of the first invoice, but by its ability to handle everything that follows it.

Testing in the sandbox environment before production

Whatever path you chose, do not move to production before you test your integration in the sandbox environment (Sandbox) thoroughly. The sandbox environment is a full copy of the Fatoora platform but without a real tax effect, so it is your safe playground to try every case before you touch an invoice that has legal value. Always start from it, and make the move to production the last step after your complete confidence.

Test the happy path in the sandbox first: a standard business invoice that passes clearance and is approved. Then move to the harder cases: an invoice with a wrong tax number to make sure your system reads the rejection and logs it, an invoice with a missing field to see the error message, and a consumer invoice (B2C) to verify the reporting path. Every case you test in the sandbox is a case that will not surprise you in production.

Also verify the token renewal behavior by keeping your session open until the token expires, then send a new invoice to see whether the package (or your wrapper) renews the token automatically or not. This simple experiment reveals a common gap that appears only after hours of continuous operation in production. Discovering it in the sandbox saves you an embarrassing outage in front of your customers.

Finally, keep a fixed set of test requests that you run before every new release of your integration. With every update of the package or your wrapper, re-run this set in the sandbox to make sure nothing broke. This simple discipline turns the integration from fragile code into a reliable system you trust with every change.

Common mistakes when using packages

Even with a ready-made package, developers fall into recurring mistakes worth flagging. The most common is mixing the sandbox environment with production. Remember that each environment has an independent certificate and keys, and that mixing them may generate unintended real invoices. Isolate the two environments’ settings completely, and always start from the sandbox.

The second mistake is ignoring token renewal. Some developers assume the package renews the token automatically without verifying that in its documentation. Make sure of the package’s behavior in managing tokens, otherwise random authentication errors will surprise you in production after the token expires.

The third mistake is settling for the happy path. The package makes acceptance easy, but it does not exempt you from handling rejection and warnings. Write your logic so that it reads the reason for rejection, logs it, and acts accordingly. A rejected invoice that your system does not handle turns into a gap in your tax record. For more on managing these cases, see the Authentication in the invoicing API page, which explains the token cycle in detail.

Where does Qoyod fit in this picture?

Everything we explained here (the package, the private wrapper, and the raw API) assumes you are building the integration yourself. But if you are a business owner who does not want to write code at all, then an accounting system such as Qoyod handles the entire layer on your behalf. Qoyod signs every invoice with the cryptographic stamp, appends the hash and the QR code to it, chooses between clearance and reporting automatically, and manages the CSID certificate without any intervention from you.

This way you get full compliance with Phase Two of e-invoicing without installing a package or writing a single API request. You create the invoice from the Qoyod interface as usual, and all the technical dialogue happens behind the scenes. And technical support remains available 24 hours, seven days a week if you need help.

The practical difference between building the integration yourself and using Qoyod goes beyond writing the code. When you build the integration, you bear the responsibility of tracking every update in the Fatoora platform’s specifications, testing every change, monitoring production, and handling every rejected invoice. When you use Qoyod, this burden moves entirely to a specialized team that keeps up with the Authority’s updates on behalf of thousands of businesses. This is a trade-off between the technical integration being your project, and it being merely a means to issue your invoices.

Your responsibility remains within your own scope, not the system’s: registering the business on the Fatoora platform, and filing the tax return through the Authority’s portal. As for the technical side of signing, clearance, and reporting, Qoyod takes care of it. For the broader picture of e-invoicing and its requirements, see the E-invoicing from Qoyodpage, and for the technical details of the interface layer, see An overview of the API.