Munkamenet (session cookie)

A Számla Agent minden kérésnél hitelesít, ami időbe kerül. Ha viszont a kliens visszaküldi az előző válaszban kapott munkameneti sütit (JSESSIONID), a Számlázz.hu a meglévő munkamenetet használja, és gyorsabban válaszol. A süti tárolása a hívó fél dolga. A kasszában ez automatikus.

Mit csinál a kassza?#

Az első kérésnél nincs tárolt süti, a Számlázz.hu új munkamenetet nyit, és a válasz Set-Cookie fejlécében visszaadja a sütit.
A kassza elmenti a sütit a cookieStore-ba.
A következő kéréseknél a kassza a Cookie fejlécben visszaküldi, és ha a Számlázz.hu frissíti, felülírja a tároltat.
Hitelesítési hibánál (auth kategória) a kassza törli a tárolt sütit, így a következő kérés tiszta lappal indul.

A Számlázz.hu 90 perc tétlenség után törli a munkamenetet. A kassza a sütit 85 percig tartja meg, így nem küld vissza lejárt munkamenetet.

Hosszan futó szerveren#

Node.js szerveren, Bunon vagy Denón nincs teendőd. Az alapértelmezett tároló a memóriában van, és addig él, amíg a folyamat. Ehhez a klienst egyszer hozd létre, és mindenhol ugyanazt használd:

lib/kassza.ts

import { createKassza } from 'kassza'

export const kassza = createKassza()

Serverless és edge#

Vercel Functions, AWS Lambda vagy Cloudflare Workers alatt a példányok jönnek-mennek, a memória nem közös. Ilyenkor adj meg közös tárolót a kassza/cookie-stores modulból:

import { Redis } from '@upstash/redis'
import { createKassza } from 'kassza'
import { upstashRedisCookieStore } from 'kassza/cookie-stores'

export const kassza = createKassza({
  cookieStore: upstashRedisCookieStore(Redis.fromEnv()),
})

import { createKassza } from 'kassza'
import { cloudflareKvCookieStore } from 'kassza/cookie-stores'

export default {
  async fetch(request: Request, env: Env) {
    const kassza = createKassza({
      agentKey: env.SZAMLAZZ_AGENT_KEY,
      cookieStore: cloudflareKvCookieStore(env.KASSZA_KV),
    })
    return Response.json(await kassza.invoices.find({ orderNumber: 'REND-1001' }))
  },
}

import Redis from 'ioredis'
import { createKassza } from 'kassza'
import { ioredisCookieStore } from 'kassza/cookie-stores'

export const kassza = createKassza({
  cookieStore: ioredisCookieStore(new Redis(process.env.REDIS_URL)),
})

import { createClient } from 'redis'
import { createKassza } from 'kassza'
import { nodeRedisCookieStore } from 'kassza/cookie-stores'

const redis = await createClient({ url: process.env.REDIS_URL }).connect()

export const kassza = createKassza({ cookieStore: nodeRedisCookieStore(redis) })

A Cloudflare KV legalább 60 másodperces lejáratot fogad el, ezt az adapter magától betartja.

Saját tároló#

Bármilyen kulcs-érték tárolót bekötheted, ha megírod a get, set és delete függvényt. A set harmadik paramétere a lejárat másodpercben.

import { customCookieStore } from 'kassza/cookie-stores'

const cookieStore = customCookieStore(
  {
    get: (key) => db.session.findValue(key),
    set: (key, value, ttlSeconds) => db.session.upsert(key, value, ttlSeconds),
    delete: (key) => db.session.remove(key),
  },
  { prefix: 'webshop:', timeoutMs: 300 },
)

Közös session több kliens között

Egyedi cookie store: a második kliens is újrahasznosítja a session cookie-t.

Futtatás a sandboxban

munkamenet.ts

import {  } from 'kassza'
import {  } from 'kassza/cookie-stores'
import {  } from 'kassza-sandbox'

const  = new <string, string>()

const  = ({
  : () => .(),
  : (, ) => {
    .(, )
  },
  : () => {
    .()
  },
})

const  = ({  })
const  = ({  })

await ..({ : 'REND-1' })
await ..({ : 'REND-2' })

.(
  .calls.map(() => ({
    : .action,
    : .sessionReused,
  })),
)
.('A tárolt kulcs:', [....()])

1. Számla adatai · action-szamla_agent_xml

<?xml version="1.0" encoding="UTF-8"?>
<xmlszamlaxml xmlns="http://www.szamlazz.hu/xmlszamlaxml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.szamlazz.hu/xmlszamlaxml https://www.szamlazz.hu/szamla/docs/xsds/agentxml/xmlszamlaxml.xsd">
  <szamlaagentkulcs>••••••••</szamlaagentkulcs>
  <rendelesSzam>REND-1</rendelesSzam>
</xmlszamlaxml>

2. Számla adatai · action-szamla_agent_xml

<?xml version="1.0" encoding="UTF-8"?>
<xmlszamlaxml xmlns="http://www.szamlazz.hu/xmlszamlaxml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.szamlazz.hu/xmlszamlaxml https://www.szamlazz.hu/szamla/docs/xsds/agentxml/xmlszamlaxml.xsd">
  <szamlaagentkulcs>••••••••</szamlaagentkulcs>
  <rendelesSzam>REND-2</rendelesSzam>
</xmlszamlaxml>

1. Számla adatai · válasz, HTTP 200

content-type: text/plain; charset=UTF-8
szlahu_error: Hi%C3%A1nyz%C3%B3%20adat%3A%20ismeretlen%20sz%C3%A1mlasz%C3%A1m%2C%20rendel%C3%A9ssz%C3%A1m%20vagy%20k%C3%BCls%C5%91%20azonos%C3%ADt%C3%B3.
szlahu_error_code: 7
set-cookie: JSESSIONID=EAE3690A13F0359C1D7A2E50; Path=/szamla; Secure; HttpOnly

[ERR] [7] Hiányzó adat: ismeretlen számlaszám, rendelésszám vagy külső azonosító.

2. Számla adatai · válasz, HTTP 200

content-type: text/plain; charset=UTF-8
szlahu_error: Hi%C3%A1nyz%C3%B3%20adat%3A%20ismeretlen%20sz%C3%A1mlasz%C3%A1m%2C%20rendel%C3%A9ssz%C3%A1m%20vagy%20k%C3%BCls%C5%91%20azonos%C3%ADt%C3%B3.
szlahu_error_code: 7

[ERR] [7] Hiányzó adat: ismeretlen számlaszám, rendelésszám vagy külső azonosító.

Konzol

[
  { muvelet: 'getInvoiceXml', sessionUjrahasznositva: false },
  { muvelet: 'getInvoiceXml', sessionUjrahasznositva: true }
]
A tárolt kulcs: [
  'szamlazz:session:784338831688dc9a95ad9dd7933c9865f09eaa21d8d1eb9258271de9595d5dde'
]

Ha a tároló nem elérhető#

A munkamenet csak gyorsítás, ezért a tároló hibája nem akaszthatja meg a számlázást. Ha a Redis vagy a KV nem válaszol, a kassza munkamenet nélkül küldi el a kérést. Az adapterek alapból figyelmeztetést írnak a konzolra, ezt az onError opcióval a saját naplódba irányíthatod:

Opció	Alapérték	Leírás
`prefix`	–	Előtag minden tárolókulcs elé.
`timeoutMs`	nincs	Ennyi idő után a tároló műveletét sikertelennek veszi.
`onError`	`console.warn`	Hívódik, ha a tároló hibát dob vagy túllépi az időkorlátot.
`resilient`	`true`	`false` esetén a tároló hibája a hívóhoz is eljut.

Munkamenet törlése#

Ha a Számlázz.hu felületén módosítod a fiók adatait, például a cégnevet vagy az e-mail címet, a változás csak új munkamenetben érvényesül. Ilyenkor hívd meg a resetSession() metódust:

await kassza.resetSession()

Ha egyáltalán nem szeretnél munkamenetet, add meg a cookieStore: false opciót. Ekkor minden kérés teljes hitelesítéssel fut, ami nagy forgalomnál érezhetően lassabb.