Ugrás a fő tartalomhoz

A kérés és az XML felépítése

Ez az oldal az action-agent_ceg_mb kérés technikai referenciája: a kérés paraméterei, az XML blokkjai és mezői, valamint a minta XML és az XSD. A folyamat áttekintése és az előfeltételek: Kapcsolat kialakítása API-val.

A kérés felépítése​

A kérés technikai paraméterei megegyeznek a többi Számla Agent hívással:

  • URL: https://www.szamlazz.hu/szamla/
  • Metódus: POST
  • Tartalomtípus: multipart/form-data
  • Form mező neve: action-agent_ceg_mb
  • Fájl tartalma: a megbízó cég és a dedikált felhasználó adatai XML formátumban (lásd lentebb)

A kérés például ilyen HTML űrlappal küldhető be:

<html>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" >
<body>
<form action="https://www.szamlazz.hu/szamla/" method="post" enctype="multipart/form-data">
  <input type="file" name="action-agent_ceg_mb"><br><br>
  <input type="submit" name="generate" value="Megbízói fiók létrehozása">
</form>
</body>

Itt is kipróbálhatod:

Töltsd fel a megszerkesztett XML fájlt

Az XML felépítése​

Az XML gyökéreleme az <XmlCegMb>, benne három blokk, ebben a sorrendben:

BlokkMire való
<login>A hívó (megbízott) fiók azonosítása
<cegMb>A megbízó cég adatai - ezekből jön létre a megbízói fiók
<usrMb>A dedikált felhasználó adatai - ezzel számlázik majd a megbízott a megbízó fiókjában

Az XML-ben a mezők sorrendje kötelezően fix - nem cserélhető fel; a rendszer a kérést az XSD alapján validálja. Küldés előtt érdemes az XML-t az XSD-vel validálni.

<login> - a megbízott azonosítása​

A hívó (megbízotti) fiókot kétféleképpen azonosíthatod: Agent kulccsal vagy felhasználónév + jelszó párossal. Ha a <szamlaagentkulcs> ki van töltve, a rendszer azt használja az azonosításhoz - a <loginname> és <password> ilyenkor el is hagyható (ha mégis kitöltöd, az értéküket a rendszer figyelmen kívül hagyja).

MezőKötelezőLeírás
<loginname>igen*A megbízotti fiók felhasználójának bejelentkezési neve. A felhasználó pontosan egy fiókhoz tartozhat; többfiókos felhasználónál a hívás 164-es, hibás belépési adatnál 3-as hibakóddal áll le.
<password>igen*A fenti felhasználó jelszava.
<szamlaagentkulcs>nemA megbízotti fiók Agent kulcsa. A kulcsot a fiók tulajdonosa vagy adminisztrátora a vezérlőpult alján, a Számla Agent kulcsok szekcióban tudja létrehozni; részletes leírás: Mi a Számla Agent kulcs (API kulcs)? és a Hitelesítés oldal.

* Csak felhasználónév + jelszavas azonosításnál kötelező; ha a <szamlaagentkulcs> ki van töltve, elhagyható.

<cegMb> - a megbízó cég adatai​

MezőKötelezőLeírás
<cegcompanyname>igenA megbízó (szállító) cég neve. Új fiók létrehozásakor ez lesz a számlákon az eladó neve; meglévő fióknál a rendszer a fiókban tárolt cégnevet használja, ezt a mezőt nem veszi át.
<cegtaxnumber>igenA megbízó adószáma. A rendszer ezzel az adószámmal keres élő fiókot (karakterre pontos egyezéssel, a teljes, 13 karakteres adószámot nézve): ha nincs ilyen fiók, újat hoz létre; ha van, ahhoz küld csatlakozási kérelmet. Hibás formátumú adószámnál a hívás 309-es hibával áll le.
<cegszamlaszamelotag>igenA megbízotti számlaszám előtag: a megbízottként kiállított számlák sorszáma ezzel kezdődik majd (pl. MBSZ-2026-1), és külön számlatömbbe kerülnek a megbízó saját számláitól. A tömböt a rendszer akkor hozza létre, amikor a megbízó elfogadja a kérelmet. Formátum: max. 5 karakter, csak nagybetűk és számok (hibás formátumnál 337-es, hiányzó előtagnál 7-es hiba); részletek: Előtagkezelés.
<cegirsz>, <cegcity>, <cegaddr>igenA megbízó székhelye: irányítószám, település, cím.
<cegpostirsz>, <cegpostcity>, <cegpostaddr>nemPostázási cím, ha eltér a székhelytől.
<cegbank>, <cegbankaccount>igen**A megbízó bankjának neve és bankszámlaszáma; ezek a számlákon jelennek meg. Ha üresen küldöd, a fiókban nem jön létre bankszámla-adat.
<cegemail>igenA megbízó cég valós, élő e-mail címe: új fiók létrehozásakor erre a címre megy az aktiváló (fiókgazdai meghívó) levél. Már létező fióknál ez a mező nem kerül felhasználásra: az értesítés a meglévő fiókban tárolt e-mail cím(ek)re megy.
<cegemailreplyto>igen**A kiküldött számlaértesítő e-mailekben ez lesz a válaszcím (reply-to). Ha üresen küldöd, a rendszer a fiók szamlazz.hu-s e-mail címét, ennek hiányában a fiókgazda e-mail címét használja válaszcímként.
<cegpenzforgdattol>, <cegpenzforgdatig>nemA pénzforgalmi elszámolás időszaka (ÉÉÉÉ-HH-NN). Akkor add meg, ha a megbízó pénzforgalmi áfaelszámolást választott: ekkor a számláin kötelező a „Pénzforgalmi elszámolás." jelölés, amelyet a rendszer ezen időszak alapján tesz a számlára. A záródátum elhagyható. Részletek: Pénzforgalmi elszámolás időszakának beállítása.
<cegkatadattol>, <cegkatadatig>nemA kisadózás (KATA) időszaka (ÉÉÉÉ-HH-NN). Ez alapján kerül a számlára a „Kisadózó." szöveg; a felirat a régi (2022. augusztus 31-ig érvényes) kata időszakra vonatkozik, az új katás számláknak már nem kötelező eleme. A záródátum elhagyható. Részletek: Kisadózó felirat törlése a számláról.

** A tagnek szerepelnie kell az XML-ben (az XSD megköveteli), de az értéke üresen hagyható.

<usrMb> - a dedikált felhasználó​

MezőKötelezőLeírás
<usremail>igenA dedikált felhasználó e-mail címe, egyben bejelentkezési neve. Nem lehet a rendszerben már létező bejelentkezési név; foglalt névnél a hívás 101-es hibával áll le.
<usrpassword>igenA dedikált felhasználó jelszava. Legalább 8, legfeljebb 128 karakter; rövidebb jelszónál a hívás 506-os, hosszabbnál 507-es hibával áll le.
<usrvezeteknev>nemA felhasználó vezetékneve.
<usrkeresztnev>igenA felhasználó keresztneve.
Megbízónként külön dedikált felhasználót adj meg

Ha több megbízóhoz csatlakozol, minden megbízóhoz külön <usremail>-t (külön dedikált felhasználót) használj. Ha egy újabb megbízónál egy már létező felhasználó e-mail címét adod meg, a csatlakozási kérelem ehhez a meglévő felhasználóhoz jön létre, és elfogadás után a felhasználó több fiókhoz fér hozzá - onnantól minden Agent hívása 164-es hibával áll le.

Minta XML és XSD​

<?xml version="1.0" encoding="UTF-8"?>
<XmlCegMb xmlns="http://www.szamlazz.hu/xmlcegmb" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.szamlazz.hu/xmlcegmb http://www.szamlazz.hu/docs/xsds/agentmb/xmlcegmb.xsd">
  
  <login>
      <!-- A megbízott által létrehozott felhasználó. Ez a felhasználó csak 1 céghez tartozhat,
           különben a bejelentkezés sikertelen lesz, mert a rendszer nem tudja eldönteni,
           melyik cégbe szeretne belépni.
           A többfiókos felhasználó 164-es, a hibás belépési adat 3-as hibakódot eredményez.
      -->
      <loginname>user</loginname>
      <password>passwd</password>
      <szamlaagentkulcs>agentkey</szamlaagentkulcs>
  </login>
  
  <cegMb>
      <!--
          A megbízó cég adatai
      -->

      <cegcompanyname>Company name Co.</cegcompanyname>
      <cegtaxnumber>12345678-1-12</cegtaxnumber>
      <cegszamlaszamelotag>MBSZ</cegszamlaszamelotag>
      <cegirsz>1117</cegirsz>
      <cegcity>Budapest</cegcity>
      <cegaddr>Budafoki út 17.</cegaddr>
      <cegpostirsz>1121</cegpostirsz>
      <cegpostcity>Budapest</cegpostcity>
      <cegpostaddr>Pf. 17.</cegpostaddr>
      <cegbank>AXA</cegbank>
      <cegbankaccount>12345678-12345678</cegbankaccount>
      <cegemail>[email protected]</cegemail>
      <cegemailreplyto>[email protected]</cegemailreplyto>
      <cegpenzforgdattol>2014-01-01</cegpenzforgdattol>
      <cegpenzforgdatig>2014-12-31</cegpenzforgdatig>
      <cegkatadattol>2014-01-01</cegkatadattol>
      <cegkatadatig>2014-12-31</cegkatadatig>
  </cegMb>
  
  <usrMb>
      <!-- A dedikált felhasználó: ezzel a felhasználóval számláz majd
           a megbízott a megbízó fiókjában a jóváhagyás után. -->
      <usremail>[email protected]</usremail>
      <usrpassword>As6dezh7*K#</usrpassword>
      <usrvezeteknev>John</usrvezeteknev>
      <usrkeresztnev>Doe</usrkeresztnev>
  </usrMb>

</XmlCegMb>

Következő lépés​

Ha beküldted a kérést, itt olvashatod el, mi történik utána: A kérés beküldése után: különböző esetek és a megbízó teendői.