fiskaly/fiskaly-sdk-swift

fiskaly Cloud-TSE SDK for Swift/iOS


Keywords
ios, kassensichv, swift, tse
License
MIT

Documentation

fiskaly SDK for Swift/iOS

The fiskaly SDK includes an HTTP client that is needed1 for accessing the kassensichv.io API that implements a cloud-based, virtual CTSS (Certified Technical Security System) / TSE (Technische Sicherheitseinrichtung) as defined by the German KassenSichV (Kassen­sich­er­ungsver­ord­nung).

Features

  • Automatic authentication handling (fetch/refresh JWT and re-authenticate upon 401 errors).
  • Automatic retries on failures (server errors or network timeouts/issues).
  • Automatic JSON parsing and serialization of request and response bodies.
  • Future: [1] compliance regarding BSI CC-PP-0105-2019 which mandates a locally executed SMA component for creating signed log messages.
  • Future: Automatic offline-handling (collection and documentation according to Anwendungserlass zu § 146a AO)

Integration

Carthage

Carthage is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks. To integrate the fiskaly SDK into your Xcode project using Carthage, specify it in your Cartfile:

github "fiskaly/fiskaly-sdk-swift" ~> 1.1.600

Run the following command to fetch the SDKs source code and build the FiskalySDK.framework:

$ carthage update

Afterwards you will find following files in your project folder:

.
├── Cartfile
├── Cartfile.resolved
└── Carthage
    └── Build
        └── iOS
            └── FiskalySDK.framework

In order to use the fiskaly SDK you must include FiskalySDK.framework in your Xcode project as can be seen in the following screenshot:

screenshot-xcode-frameworks-integration

Finally, the SDK can be imported using:

import FiskalySDK

Usage

Creating a Client Instance

let client = try FiskalyHttpClient (
    apiKey:     ProcessInfo.processInfo.environment["API_KEY"]!,
    apiSecret:  ProcessInfo.processInfo.environment["API_SECRET"]!,
    baseUrl:    "https://kassensichv.io/api/v1/"
)

Retrieving the Version of the Client and the SMAERS

do {
    let response = try client.version()
    print(response)
} catch {
    print("Error while retrieving version: \(error)")
}

Client Configuration

The SDK is built on the fiskaly Client which can be configured through the SDK.

do {
    let response = 
        try client.config(
                    debugLevel: -1,
                    debugFile: "tmp/tmp.log",
                    clientTimeout: 1500,
                    smaersTimeout: 1500)
    print(response)
} catch {
    print("Error while setting config: \(error)")
}

Sending HTTP Requests

Please note:

  • the body sent in requests needs to be base64 encoded
let transactionUUID = UUID().uuidString

do {

    // start Transaction

    let transactionBody = [
        "state": "ACTIVE",
        "client_id": clientUUID
    ]

    let transactionBodyData = try? JSONSerialization.data(withJSONObject: transactionBody)
    let transactionBodyEncoded = transactionBodyData?.base64EncodedString()

    let responseCreateTransaction = try client.request(
        method: "PUT",
        path: "tss/\(tssUUID)/tx/\(transactionUUID)",
        body: transactionBodyEncoded!)

    print(responseCreateTransaction)

} catch {
    print("Error while starting transaction: \(error)")
}



// finish Transaction

let transactionFinishBody: [String: Any] = [
    "state": "ACTIVE",
    "client_id": clientUUID,
    "schema": [
        "standard_v1": [
            
            "receipt": [
                "receipt_type": "RECEIPT",
                "amounts_per_vat_rate": [
                    ["vat_rate": "19", "amount": "14.28"]
                ],
                "amounts_per_payment_type": [
                    ["payment_type": "NON_CASH", "amount": "14.28"]
                ]
            ]
            
        ]
    ]
]

do {

    let transactionFinishBodyData = try? JSONSerialization.data(withJSONObject: transactionFinishBody)
    let transactionFinishBodyEncoded = transactionFinishBodyData?.base64EncodedString()

    let responseFinishTransaction = try client.request(
        method: "PUT",
        path: "tss/\(tssUUID)/tx/\(transactionUUID)",
        query: ["last_revision": "1"],
        body: transactionFinishBodyEncoded!)

    print(responseFinishTransaction)

} catch {
    print("Error while finishing transaction: \(error)")
}


Related