README

The fiskaly SDK is a HTTP Laravel client that is needed for accessing the fiskaly API v2 that implements a cloud-based, virtual CTSS (Certified Technical Security System) / TSE (Technische Sicherheitseinrichtung) as defined by the German KassenSichV (Kassensicherungsverordnung).

Requirements

PHP 8.0+ Laravel or Lumen 8+

Integration

Composer

The PHP SDK is available for a download via Composer.

Packagist - Package Repository.

Simply execute this command from the shell in your project directory:

$ composer require elkadrey/fiskaly-laravel

Or you can manually add the package to your composer.json file:

"require": {
    "elkadrey/fiskaly-laravel": "*"
}

then run

$ composer update

Service

Additionally, to the SDK, you'll also need the fiskaly service. Follow these steps to integrate it into your project:

Go to https://developer.fiskaly.com/downloads#service
Download the appropriate service build for your platform
Start the service

Get started

example 1: Make connection and create a INITIALIZED TSS

<?php namespace App\Http\Controllers;

use Illuminate\Routing\Controller as BaseController;

//include the client library
use elkadrey\FiskalyLaravel\FiskalyLaravelClient;
use Exception;
use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;
use Illuminate\Support\Facades\Cache;

class Controller extends BaseController
{
    private ?FiskalyLaravelClient $client = null;

    public function __construct()
    {
        //Make the connection
        $this->client = FiskalyLaravelClient::create([
            "api_key" => env("TSE_API_KEY"), 
            "api_secret" => env("TSE_API_SECRET"), 
            "baseUrl" => env("TSE_API_URL", null),
            "token" => Cache::get("tse_token"),
            "token_expire_at" => Cache::get("tse_token_expire_at"),
        ]);
        //Set debug level (2 is default)
        /** Debug levels list
        * 0 = errors only
        * 1 = errors and warning
        * 2 = all with info for each API response
        */
        $this->client->setLog(2);

        //make Auth with token in case empty token or expired
        $token = $this->client->MakeAuth();
        
        //Also you can use getToken
        //$token = $this->client->getToken();
        
        Cache::put("tse_token", $token->access_token);
        Cache::put("tse_token_expire_at", $token->access_token_expires_at);
    }

    public function createTSS(Request $request)
    {
        $this->validate($request, [
            "metadata" => "nullable|array"
        ]);

        try
        {
            //create a ready INITIALIZED TSS (5 steps in one)
            set_time_limit(0);
            $results = $this->client->createTSS($request->metadata);
            return JsonResource::make($results);
        }
        catch(Exception $e)
        {
            //Your exception code here
        }
    }
}

Custom API usage

To call api like for example: "/tss/{{tssId}}/client/{{$guid}} with method: put" just call the method in the first function then use "_" to spirite the api slashs "/" and provide the params data as array, request or collection and the arrangement is boolean in case you want to add GUID automatically for example:

$this->client->put_tss_95a03ad9-61ad-4757-8a1d-57daf47db25c_client($params, true);

example 2: Make connection and create a Manually TSS

    public function createManuallyTSS(Request $request)
    {
        $this->validate($request, [
            "metadata" => "nullable|array"
        ]);

        try
        {
            //create a ready INITIALIZED TSS (5 steps in one)
            set_time_limit(0);

            //API => method:put /tss/{$guid}
            $tss = $this->client->put_tss($request->metaData, true); //return laravel collection 
            if($tss->state == "CREATED")
            {
                //1- Change state to UNINITIALIZED
                //API => method:patch /tss/{tssid}
                $this->client->{"patch_tss_$tss->_id"}(["state" => "UNINITIALIZED"]);
                $tss->put("state", "UNINITIALIZED");

                //2 - Set admin pin
                $adminPin = uniqid();
                //change admin pin api
                $this->client->changeAdminPin($tss->_id, $tss->admin_puk, $adminPin);                
                $tss->put("adminpin", $adminPin);

                //3- Make admin auth
                //make admin auth
                $this->client->adminAuth($tss->_id, $adminPin);

                //4- Change state to INITIALIZED
                //API => method:patch /tss/{tssid}
                $this->client->{"patch_tss_$tss->_id"}(["state" => "INITIALIZED"]);                
                $tss->put("state", "INITIALIZED");
                return JsonResource::make($tss);
            }
        }
        catch(Exception $e)
        {
            //Your exception code here
        }
    }

example 3: add client to TSS

public function addClient(string $tssid, Request $request)
{
    $this->validate($request, [
        "metadata" => "nullable|array"
    ]);

    try
    {
        $guid = $this->client->getUUID();
        
        $serial_number = "ERS $guid";
        $info = compact('serial_number', 'metadata');

        //API => method:PUT /tss/{tssid}/client/{guid}
        $results = $this->client->{"put_tss_$tssid"."_client_$guid"}($info);
        return JsonResource::make($results);
    }
    catch(Exception $e)
    {
        //Your exception code here
    }
}

example 4: Start Transaction

public function startTransaction(string $tssid, string $clientid)
{
    try
    {
        //API => method:PUT /tss/{{tssId}}/tx/{{$guid}}?tx_revision=1
        $results = $this->client->{"put_tss_$tssid"."_tx?tx_revision=1"}(["state" => "ACTIVE", "client_id" => $clientid], true);
        return JsonResource::make($results);
    }
    catch(Exception $e)
    {
        //Your exception code here
    }
}

New Feature: DSFinV-K API Mode

To interact with DSFinV-K which requires a different API URL, you can enable the DSFinV-K mode on the client:

$this->client->setDsfinkMode(true);

After enabling DSFinV-K mode, you can make API calls to the DSFinV-K endpoint as usual, for example:

$this->client->make("cash_registers/$client->uuid", $data, false, "put");

This will route the request to the correct DSFinV-K API URL automatically.

elkadrey / fiskaly-laravel

Maintainers

Package info

Statistics

Security