Ugrás a fő tartalomhoz

Kapcsolat kialakítása API-val

A megbízott számlakibocsátás lényege, hogy egy cég (a megbízott) egy másik cég (a megbízó, vagyis a szállító) nevében, a megbízó Számlázz.hu fiókjában állít ki számlákat. Ehhez először kapcsolatot kell kialakítani a két cég között. A kapcsolat kétféleképpen hozható létre: a webes felületen (Kapcsolat kialakítása a felületen) vagy programozottan, API-val (action-agent_ceg_mb) - ezt az utóbbit írja le ez a szekció, három oldalon:

  1. Áttekintés és előfeltételek (ez az oldal): mit csinál a hívás, mi kell hozzá, és hogyan épül fel a folyamat.
  2. A kérés és az XML felépítése: a kérés technikai paraméterei, az XML blokkjai és mezői, minta XML és XSD.
  3. A kérés beküldése után: különböző esetek és a megbízó teendői: mi történik a beküldött kéréssel, mit kell tennie a megbízónak, válasz és hibakezelés.

A szerepek (megbízó, megbízott) és az üzleti áttekintés: Megbízott számlakibocsátás.

Mit csinál az action-agent_ceg_mb hívás?​

Az API-s út ugyanazzal az XML kéréssel két helyzetet fed le:

  • ha a megbízónak még nincs Számlázz.hu fiókja, a hívás létrehozza a megbízói fiókot;
  • ha a megbízónak már van fiókja (a megadott adószám alapján azonosítva), a hívás csatlakozási kérelmet küld a fiók gazdájának - második fiók nem jön létre.
Az adószám pontossága kritikus

A rendszer kizárólag a kérésben küldött adószám pontos egyezése alapján ismeri fel a megbízó meglévő fiókját. Ha az adószám elgépelt vagy eltér a fiókban tárolttól, a hívás csatlakozási kérelem helyett új fiókot hoz létre. Beküldés előtt ezért mindig ellenőrizd a megbízó adatait, különösen az adószámot.

A hívás mindkét esetben létrehozza azt a dedikált felhasználót is (<usrMb>), amelyikkel a megbízott később a megbízó fiókjában számlázni fog. Több megbízó esetén megbízónként külön dedikált felhasználót (külön <usremail>-t) adj meg: az Agent hívásokhoz használt felhasználó csak pontosan egy fiókhoz férhet hozzá, különben a hívások 164-es hibával állnak le.

Előfeltételek​

Mielőtt a kérést összeállítanád, ezekre lesz szükséged:

  • Regisztrált megbízotti fiók a Számlázz.hu-n, Számla Agent hozzáféréssel; az azonosításhoz Agent kulcsot használsz, de felhasználónév + jelszó párost is használhatsz, lásd: Hitelesítés.
  • Engedély az interfészhez: az action-agent_ceg_mb hívás engedélyhez kötött. Hozzáférést az ügyfélszolgálaton tudsz kérni; engedély nélkül a hívás 137-es hibakóddal tér vissza.
  • A megbízó adatai. Kötelező: cégnév, adószám, székhely és egy valós e-mail cím - fontos: új fiók létrehozásakor a megbízó erre, a kérésben megadott e-mail címre kapja az aktiváló (fiókgazdai meghívó) levelet. A bank neve, a bankszámlaszám és a számlaértesítők válaszcíme (reply-to) tagjének szerepelnie kell az XML-ben, de az értékük üresen hagyható. Nem kötelező: az eltérő postázási cím, a pénzforgalmi elszámolás és a kisadózás (KATA) időszaka. Mezőnkénti részletek: A kérés és az XML felépítése.
  • Egyeztetett számlaszám előtag (max. 5 karakter, csak nagybetűk és számok szerepelhetnek benne): ebbe a számlatömbbe készülnek majd a megbízotti számlák; részletek: Előtagkezelés.
információ

Ha a hívó (megbízotti) fiók tesztüzemben van, a hívással létrehozott megbízói fiók automatikusan szintén tesztfiók lesz, és a cégneve „ (agentceg teszt)" utótagot kap. Így a teljes folyamat éles adatok nélkül, biztonságosan kipróbálható; lásd: A folyamat tesztelése. Az interfész engedélye a tesztfiókra is szükséges - a tesztüzem #profi funkciókészlete sem tartalmazza, ezért kérd meg a tesztfiókodra is az ügyfélszolgálattól.

A folyamat áttekintése​

Időrendben így épül fel a kapcsolat az API-n keresztül:

  1. Összeállítod az action-agent_ceg_mb kérés XML-jét a megbízó cég adataival; lásd: A kérés és az XML felépítése.
  2. Beküldöd a kérést HTTP POST-tal a Számla Agent végpontra.
  3. A rendszer az adószám alapján létrehozza a megbízói fiókot, vagy csatlakozási kérelmet küld a meglévő fiókhoz; lásd: Mi történik a csatlakozási kérelem beküldését követően?
  4. A megbízó e-mailt kap: új fióknál az aktiváló (fiókgazdai meghívó) levél a kérésben megadott <cegemail> címre megy; meglévő fióknál a jóváhagyási kérelemről szóló értesítés a fiókban tárolt cégemail címre és a fiókgazda e-mail címére érkezik, és a fiókgazda a kérelmet a vezérlőpultján fogadja el.
  5. Amikor a megbízó birtokba veszi a fiókot / jóváhagyja a kérelmet, a megbízott visszaigazoló e-mailt kap.
  6. Éles számlázás előtt a megbízói fiókban el kell végezni a NAV Online Számla összekötést.
  7. Ezután indulhat a számlázás a megbízó fiókjában; lásd: Számlakiállítás megbízottként.

Következő lépés​

Állítsd össze a kérést: A kérés és az XML felépítése.