Session cookies
The operation of the Számla Agent is optimized such that the management of session cookies, i.e., storing and using session cookies during calls, is the responsibility of the calling party (e.g., a web store).
Typically, web stores use a client-server architecture, where only the browser runs on the client side as a "thin client." All other processing occurs on the server. When the web store wishes to issue an invoice, it initiates a call to the Számla Agent. It is essential for the Agent to perceive the web store as a single "user," and consequently, the same user authentication is applied for every call.
Step-by-step explanation
1. Initial Call to Számla Agent: If the requester (e.g., a web store) does not have a session cookie, Számla Agent will detect this when the first XML file is sent. The Agent then creates a new session (generating a session cookie) and begins processing the XML file.
2. First Response: Depending on the response version specified in the request, the response arrives. This typically includes a PDF in the response body and additional information in the response header, such as the session cookie (noted as JSESSIONID). It is crucial to save both the PDF file and the session cookie.
3. Second Call to the Agent: The XML is sent again, but this time the previously obtained session cookie is included in the request header.
4. Second Response: Another PDF is returned in the response body, and the same session cookie is returned. This indicates that no further action is required.
After this, steps 3 and 4 repeat. If the session is inactive for 90 minutes, Számlázz.hu will delete it. In this case, a new session cookie will be generated upon the next call.
Recommended procedures
1. XML File and session cookie required for calling Számla Agent: If there is no cookie file received in the request, the Agent will create one and return it in the response. If a cookie file exists, it should be used in the call.
2. Handling responses: Save the PDF/XML file contained in the incoming response. It is also advisable to save the received cookie to a file. The existing cookie file can be overwritten, as the web store is treated as a single user from the perspective of Számlázz.hu, authenticated via the API key.
If session cookies are not stored on the server, the Agent will create a new session cookie for every request and go through the authentication process each time. This requires additional time. While the impact may be negligible for handling a few invoices, the time loss becomes significant if the invoicing requests scale to thousands or tens of thousands. Thus, it is highly recommended to store and reuse session cookies in systems that send a large number of invoice generation requests to Számla Agent.
In the event of changes to Számlázz.hu account details, such as company data or email address modifications, generating a new session cookie is advised. This ensures that the changes take effect.