Kérések küldése

A Számla Agent minden művelete ugyanarra a címre érkezik: https://www.szamlazz.hu/szamla/. Hogy melyik műveletet kéred, azt nem az URL, hanem a multipart/form-data kérésben küldött XML fájl form mezőjének neve dönti el.

Műveletek és form mezők#

A kasszában nem kell form mezőkkel foglalkoznod, minden műveletnek saját metódusa van. A táblázat azt is mutatja, melyik hívást próbálja újra a kassza hálózati hiba esetén.

kassza metódus	Agent form mező	Automatikus újrapróbálás
`invoices.create(), invoices.preview()`	`action-xmlagentxmlfile`	soha
`invoices.reverse()`	`action-szamla_agent_st`	soha
`invoices.registerPayment(), invoices.clearPayments()`	`action-szamla_agent_kifiz`	csak felülíró (additive: false) hívásnál
`invoices.getPdf(), verifyCredentials()`	`action-szamla_agent_pdf`	igen
`invoices.get(), invoices.find()`	`action-szamla_agent_xml`	igen
`invoices.deleteProforma()`	`action-szamla_agent_dijbekero_torlese`	soha
`receipts.create()`	`action-szamla_agent_nyugta_create`	csak callId megadásával
`receipts.reverse()`	`action-szamla_agent_nyugta_storno`	csak callId megadásával
`receipts.get(), receipts.find()`	`action-szamla_agent_nyugta_get`	igen
`receipts.send()`	`action-szamla_agent_nyugta_send`	soha
`taxpayer.query()`	`action-szamla_agent_taxpayer`	igen

Mit küld el a kassza?#

Egy számlakészítés a hálózaton nagyjából így néz ki. Az XML fájlként megy, nem szöveges mezőként. Ha szöveges mezőként küldenéd, a Számlázz.hu 53-as hibával válaszolna.

POST /szamla/ HTTP/1.1
Host: www.szamlazz.hu
Accept: application/xml, application/pdf, text/plain, */*
Cookie: JSESSIONID=…
Content-Type: multipart/form-data; boundary=----kassza

------kassza
Content-Disposition: form-data; name="action-xmlagentxmlfile"; filename="request.xml"
Content-Type: text/xml; charset=UTF-8

<?xml version="1.0" encoding="UTF-8"?>
<xmlszamla xmlns="http://www.szamlazz.hu/xmlszamla" …>
  <beallitasok>…</beallitasok>
  <fejlec>…</fejlec>
  <elado>…</elado>
  <vevo>…</vevo>
  <tetelek>…</tetelek>
</xmlszamla>
------kassza--

Mellékletnél a fájlok attachfile1, attachfile2 és így tovább nevű mezőkben mennek, legfeljebb 5 darab, darabonként legfeljebb 2 MB.

Egy XML, egy bizonylat#

Egy kérés pontosan egy számlát vagy nyugtát hoz létre. Több bizonylatot egymás után, külön hívásokkal állíts ki. Tömeges számlázásnál ne indíts egyszerre sok párhuzamos kérést, mert a Számlázz.hu a túlzott terhelést kitiltással büntetheti.

for (const rendeles of kiszamlazando) {
  await szamlaz(rendeles)
}

Elgépelt mezőnevek#

Az Agent XML elemnevei kis- és nagybetűérzékenyek, és a sorrendjük is kötött. Egy elgépelt elemnév 57-es hibát okoz, vagy ami rosszabb, a számla elkészül, de a kért beállítás csendben elmarad. A kasszában ilyen hiba nem fordulhat elő: az XML-t típusos objektumból, az XSD szerinti sorrendben építi fel, az elgépelt mezőnevet pedig már a TypeScript jelzi.

import {  } from 'kassza'

const  = ({ : 'kulcs' })

await ..({
  : { : 'Vevő Kft.', : '1111', : 'Budapest', : 'Fő utca 1.' },
  : [{ : 'Tanácsadás', : 20_000, : 27 }],
  simpleitems: true,Object literal may only specify known properties, but 'simpleitems' does not exist in type 'CreateInvoiceInput'. Did you mean to write 'simpleItems'?
})

Válaszformátum#

A Számla Agent a kérés valaszVerzio értékétől függően szöveggel, PDF-fel vagy XML-lel válaszol. A kassza mindig az XML választ kéri, mert abban a számlaszám, az összegek és, ha kérted, a Base64 kódolású PDF is benne van. Te ebből típusos objektumot kapsz, a PDF pedig Uint8Array lesz.

Tesztelés#

Tesztfiókban 10 percenként legfeljebb 500 számlát készíthetsz. Fejlesztés közben ez bőven elég, automata tesztekhez viszont a kassza/testing mock kliensét használd.

Több webshop egy fiókban#

Ha ugyanabból a Számlázz.hu fiókból több webshop számláz, adj mindegyiknek saját számlaszám előtagot. Az előtagot előbb a Számlázz.hu felületén, a Beállítások / Előtagok menüpontban kell rögzíteni, különben 202-es hibát kapsz.

export const webshopKassza = createKassza({ defaults: { invoice: { prefix: 'WEB' } } })
export const piaciKassza = createKassza({ defaults: { invoice: { prefix: 'PIAC' } } })

Alacsony szintű konstansok#

Saját eszközökhöz a kassza a nyers értékeket is exportálja a kassza csomagból:

Konstans	Érték
`SZAMLAZZ_AGENT_URL`	`'https://www.szamlazz.hu/szamla/'`
`AGENT_ACTIONS`	A művelet és a form mező párjai, például `createInvoice: 'action-xmlagentxmlfile'`
`MAX_INVOICE_ATTACHMENTS`	`5`
`AGENT_ERROR_CODES`	Az ismert hibakódok üzenettel, kategóriával és tippel

Következő lépések#

Számla létrehozás

Az első számla minden mezővel és szabállyal.

Munkamenet (session cookie)

Gyorsabb kérések a munkamenet újrahasznosításával.