Basics

To use various examples, we call the ../examples/autoload.php file found in the package, which automatically loads the classes we will need for sending Agent requests. We only need to do this once, specifying an absolute or relative path as needed.

require_once(__DIR__ . '/../examples/autoload.php');

The API is accessible through the SzamlaAgent namespace. You can see the correct usage in the examples. Integrated development environments (IDEs) automatically complete the namespaces of the classes to be imported; otherwise, you must provide them as follows:

use \SzamlaAgent\SzamlaAgentAPI,
    \SzamlaAgent\Buyer,
    \SzamlaAgent\Item\InvoiceItem,
    \SzamlaAgent\Document\Invoice\Invoice;

The above example imports classes used for issuing paper or e-invoices.

You can find the example in the API package at the following location: ./examples/document/invoice/create_invoice_with_default_data.php

warning

The minimum PHP version required for using the Számla Agent PHP API: 5.6.0.

Character Encodings

Agent requests and responses default to utf-8 character encoding.

Initialization

To prepare for Agent communication, create an Agent instance:

$agent = SzamlaAgentAPI::create('agentApiKey’);

You need to create the Számla Agent key ('apiKey') in the Számlázz.hu account you want to use the Agent with (make sure it's a user who only has access to a single invoicing account). Using the above method, the PHP class responsible for Agent communication will be created with the default settings.

Read more about this here in Hungarian.

• In case of a successful response, the data will contain the generated document in PDF format (in one instance).
• The logging level is default to DEBUG, which you can change, for example, to only error logging as follows:

$agent = SzamlaAgentAPI::create('apiKey', true, Log::LOG_LEVEL_ERROR);

or individually parameterized:

$agent->setLogLevel(Log::LOG_LEVEL_ERROR);

If you want to be notified by email if something goes wrong during the Agent operation, you can set it up as follows:

$agent->setLogEmail(‘example@example.com’);

Default Settings

Below are the settings you can access. It is important that PHP is able to write to the logs, xmls, and pdf directories.

Logging Levels (logLevel)

The logging "level" determines the level of logging.

0. no logging: Sets the logging to inactive.
1. errors: Only records 'error' type events and optionally sends an email about them.
2. warnings: Besides logging errors, it also logs warnings, which may not necessarily affect the normal operation.
3. debug mode: In addition to the above, provides continuous information about the functioning of the features.

0: LOG_LEVEL_OFF   - no logging
1: LOG_LEVEL_ERROR - logging errors only
2: LOG_LEVEL_WARN  - logging errors and warnings
3: LOG_LEVEL_DEBUG - logging all types (developer mode)

Logging Files

By default, each log file is generated in the ./logs directory and contains logged events and errors on a daily basis. Logging can be disabled as follows:

$agent = SzamlaAgentAPI::create('agentApiKey', true, Log::LOG_LEVEL_OFF);

Logging Email

If filled out, the website administrator will receive an email about error-level events at the email address provided here. If not filled out, the function will remain inactive.

$agent->setLogEmail(‘example@example.com’);

PDF Document in Response

You can set whether to receive the document in PDF format in the response of individual procedure calls (where applicable). By default, every response will contain the PDF, so you only need to set this if you don't want to receive it. You can do this as follows:

$agent = SzamlaAgentAPI::create('apiKey', false);

or individually parameterized:

$agent->setDownloadPdf(false);

The saved PDF file will be named according to the generated invoice number.

Cookie and Session Management

From both security and resource efficiency perspectives, it is important that during individual procedure calls, the client appears as one user from the Agent's remote system. When instantiating the Számla Agent API, the API automatically sets the session cookie required for Agent requests, ensuring that the Számlázz.hu system handles incoming requests in one session for subsequent requests. In practice, this means that by default, each Számla Agent API instance will have its own cookie file, ensuring that requests sent to invoicing accounts associated with instances use separate sessions.

If you want to change the path to this, you can do so as follows:

$agent->setCookieFileName('new-cookie-filename.txt');

When invoicing to multiple invoicing accounts at the same time, it is strongly recommended to use the database mode, where after sending a document, the session ID set in the Számlázz.hu server response can be extracted and stored in a database, and then provided with a setter method for the next request.

Setting the cookie database handling mode:

$agent->setCookieHandleMode(CookieHandler::COOKIE_HANDLE_MODE_DATABASE)

Querying the cookie after a document is created:

$result->getCookieSessionId();

Setting the session ID (based on the session ID stored in the database):

$agent->setCookieSessionId($sessionId);

Agent Call

The Agent API communicates using the latest CURL method. However, on certain server configurations, the CURL installation may be incomplete or the necessary certificate packages may not have been installed, so in these cases, any feedback from the procedure call may encounter errors. To overcome this, we integrated automatic certificate importing. In some cases, this solution may also encounter problems, such as system-level prohibitions.

Handling Errors and Exceptions

If any errors or exceptions occur during the use of the Számla Agent, the Agent throws a custom exception (SzamlaAgentException), which we can catch with a try-catch exception handling as follows:

try {
        $agent = SzamlaAgentAPI::create('agentApiKey');
        …
        …
        if ($result->isSuccess()) {
            ...
        }
    } catch (SzamlaAgentException $e) {
        $agent->logError($e->getMessage());
    } catch (\Exception $e) {
        $agent->logError($e->getMessage());
    }

A log entry is created for each error in the ./logs/{current-date} file. To log all errors, it's recommended to set the logging level to developer mode:

$agent = SzamlaAgentAPI::create('apiKey', true, Log::LOG_LEVEL_DEBUG); 

or individually parameterized:

$agent->setLogLevel(Log::LOG_LEVEL_DEBUG);