Kapcsolódó információk:
› Paraméterezési útmutatók

Összehasonlított verziók

Régi verzió 3

changes.mady.by.user QSoft

Mentés ekkor:

összehasonlítva

Új verzió Aktuális

changes.mady.by.user QSoft

Mentés ekkor:

Kulcs

  • Beillesztett sor.
  • Törölt sor.
  • Formázás megváltoztatva.

A DbConnector alkalmazáshoz kapcsolódó API felület az alkalmazás néhány funkcióját delegálja intranetes Az API felület a DbConnector alkalmazás Kimenő számlák automatizált készítése funkciót teszi elérhetővé webszolgáltatásként.
A webszolgáltatás XML webszolgáltatás XML alapú REST API kezelési móddal érhető el.

...

width50%

hívásokkal működtethető.

Az API a következő belépési ponton érhető el. A szerver név a helyi intranetes környezettől függ.

A REST API hívások általános használata a DbConnector REST API oldalon található. A dokumentum angol nyelven is elérhető DbConnector REST API - invoice címen.

helyi intranet saját ... szerver név stb...
Az API a következő belépési ponton érhető el.

A várólistát egy időzítetten futó feldolgozó üríti ki. A feldolgozás közben várólistába kerülő új elemek a következő feldolgozási periódusba kerülnek.

Panel
bgColorAliceBlue
titleBGColorLightSteelBlue
title
POST | GET
    

http://server/dbconnector/api/v1

/

Header paraméterek: az API használathoz szükséges pkod, lickod paraméterek.

Az API hívás aszinkron működésű. A beküldött kérések várólistába kerülnek. A feldolgozottsági állapot lekérdezésére külön API hívás van. A válaszok XML-ben érkeznek.

Oszlop
width50 %
Panel
bgColorBeige


Tartalom

Tartalomjegyzék
maxLevel1

Minden API híváskor az autentikációs adatokat a HTTP header-ben kell beküldeni.

Header paraméterek
   pkod:SajatSupPartnerKod
   lickod:SajatSupLicKod 

Az adatok a SUP rendszert felhasználó cég számára átadott licence adatlapon találhatók.

  • pkod - SUP partnerkód
  • lickod - SUP licence kód

...

Rögzítés
xmlSzamla
xmlSzamla
Számla beküldése

Panel
bgColorAliceBlue
titleBGColorDarkSalmon
titlePOST

http://server/dbconnector/api/v1/

...

postxml

A hívás célja

...

, hogy a Kimenő számla importálás XML sémával leírt, külső rendszerben előállított számlázási utasítás alapján a SUP rendszer DbConnector modulja, a Kimenő számlák automatizált készítése funkciója API felületen keresztül is elérhető legyen.

Qsboxmegjegyz

A beküldés egy aszinkron feldolgozás, a beküldött XML-ek várólistába kerülnek, a feldolgozottsági állapotot a későbbiekben le kell kérdezni. Megfelelő szerver oldali beállítások esetén a sikeres feldolgozottsági státussal együtt a számla PDF képe is visszaadásra kerül a hívóhoz.

Paraméter (kötelező)
   XML : A számázási utasítás XML (az esetleges számla csatolmányokat előzetesen kell feltölteni)

...

Result
   XML -

...

 

...

bash - API elérhetősége

<Token> : Sikeres beküldés esetén a kapott adatot meg kell őrizni. A feldolgozás eredménye ezzel az azonosítóval kérhető le.

Kódblokk
language
java
titleHívás minta
CURL.EXE    ^
  -X
GET
POST   
^
     http://server:8080/dbconnector/api/v1/
test
postxml ^
  -
F dummy=true

...

Kódblokk
languagebash
titleHívás minta - Authentikációs adatok tesztelése
CURL.EXE 
H pkod:SajatSupPartnerKod  ^
  -
X
H lickod:SajatSupLicKod
POST
   ^
  -H "Content-Type:
http://server:8080/dbconnector/api/v1/test ^ -H pkod:SajatSupPartnerKod ^ -H lickod:SajatSupLicKod
text/html; charset=UTF-8" ^
  --data-ascii @testUpload.xml
Kódblokk
languagexml
titleVálasz minta
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<DbConnectorResponse>
    <Success>true</Success>
    <StatusCode>200</StatusCode>
<Message>DbConnector DLL: 15.1 (2018.04.01. 8:16:32)</Message>
<Token>7085BEEC-93B0-4FE1-88BB-F531EDAC38D6</Token>
</DbConnectorResponse>
Qsboxmegjegyz

File-ként létrehozott XML esetén figyelni kell arra, hogy BOM nélküli XML-t kell feltölteni.

Rögzítés

...

upload

...

upload
Számla

...

csatolmány feltöltése

Panel
bgColorAliceBlue
titleBGColorDarkSalmon
titlePOST

...

http://server/dbconnector/api/v1/

...

upload

A

...

Qsboxmegjegyz

A beküldés egy aszinkron feldolgozás, a beküldött XML-ek várólistába kerülnek, a feldolgozottsági állapotot a későbbiekben le kell kérdezni. Megfelelő szerver oldali beállítások esetén a sikeres feldolgozottsági státussal együtt a számla PDF képe is visszaadásra kerül a hivóhoz.

Paraméter (kötelező)
   XML : A számázási utasítás XML

...

bash

számlához opcionálisan csatolmányként tárolt melléklet tölthető fel. Feltölthető file formátum: JPG, PDF. Amennyiben az elkészült számla is PDF formátumú, a mellékletek beágyazódnak a számla PDF-be.
A csatolmányokat a számlázási utasítás XML beküldést megelőzően kell feltölteni a szerverre. A válaszként kapott azonosítókat (tokenek) egy vesszővel felsorolt listában el kell helyezni a számlázási XML-ben, a <Elojegyzett_Szamlak><Szamlak><Szamla><Csatolmanyok> adattagban.

Kódblokk
language
java
titleHívás minta
CURL.EXE    ^
  -X POST   ^
     http://server:8080/dbconnector/api/v1/
postxml
upload ^
  -H pkod:SajatSupPartnerKod  ^
  -H lickod:SajatSupLicKod    ^
  -
H "Content-Type: text/html; charset=UTF-8" ^ --data-ascii @test.xml
F file=@testupload.jpg
Kódblokk
languagexml
titleVálasz minta
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<DbConnectorResponse>
    <Success>true</Success>
    <StatusCode>200</StatusCode>
    <Message>File feltöltés sikeres</Message>
<SzamlaToken>7085BEEC
<Token>74cc7200-
93B0
b9fc-
4FE1
4fd8-
88BB
a1cf-
F531EDAC38D6<
8942c09afc35</
SzamlaToken>
Token>
</DbConnectorResponse>



Rögzítés
getStatus
getStatus
Feldolgozottsági állapot lekérdezése

Panel
bgColorAliceBlue
titleBGColorLightSteelBlue
titleGET

...

http://server/dbconnector/api/v1/getstatus

A hívás célja a korábban a feldolgozási várólistába beküldött XML dokumentum feldolgozottsági státusának lekérdezése. A kérés azonosításához az XML beküldéskor válaszként kapott

...

tokent kell használni.

Sikeres feldolgozás esetén válaszként visszaadja a számát a SUP rendszerben azonosító adatot (napló | számlaszám)

...

. Megfelelő beállítások esetén a számla PDF

...

kép is lekérdezhető -

...

base64 enkódolt formában.

...

Paraméter (kötelező)
   token : Az XML beküldéskor kapott token.

Result
   XML -

...

<BizonylatAzon> :

...

Az elkészült

...

bizonylat azonosítója a SUP rendszerben (napló |

...

számlaszám).
   XML -

...

bashHívás

 <DocumentType>, <DocumentData> : Az elkészült számla PDF számlaképe (megfelelő SUP beállítás esetén).

Kódblokk
language
java
title
Kérés minta
CURL.EXE    ^
  -X GET    ^
     http://server:8080/dbconnector/api/v1/getstatus?token=
B03D8188
7085BEEC-
2159
93B0-
4174
4FE1-
A866
88BB-
E214988DFB2A
F531EDAC38D6
^
 ^
  -H pkod:SajatSupPartnerKod   ^
  -H lickod:SajatSupLicKod
 Kódblokk
languagexml
titleVálasz minta #1
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<DbConnectorResponse>
    <Success>false</Success>
    <StatusCode>290</StatusCode>
    <Message>A tetel feldolgozasra var</Message>
</DbConnectorResponse>
 Kódblokk
languagexml
titleVálasz minta #2
 <
 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<DbConnectorResponse>
    <Success>true</Success>
    <StatusCode>200</StatusCode>
    
<SzamlaAzon>499
<BizonylatAzon>411|
DBC0001
KI-0001/
18<
22</
SzamlaAzon>
BizonylatAzon>
</DbConnectorResponse>
Válasz XML
Az API hívásra adott válasz XML egy <DbConnectorResponse> séma alapján jön létre.
Adattagok
SuccessSikeres feldolgozás esetén true, egyéb esetben false
StatusCodeSikertelen feldolgozás esetén további, részletesebb információkat közöl. Megegyezik a http statuskóddal, de a hívás sikerességének ellenőzéséhez a nem ezt, hanem a http statuskódot kell használni.
MessageSikertelen feldolgozás esetén szöveges információk a problémáról, összhangban a StatusCode válasszal
TokenKérés beküldés esetén a várólistából ezzel az azonosítóval lehet majd a status információkat lekérni
SzamlaAzon
BizonylatAzon
Számlázási utasítás beküldés és sikeres feldolgozás esetén, a SUP rendszerben a megadott azonosítón található meg a számla
pdfDocument
.
 Qsboxmegjegyz
A feldolgozás során a BizonylatAzon információ akkor is visszajön, ha a teljes folyamat nem volt sikeres (pl. nem sikerült hitelesíteni az e-számlát), de a számla bizonylat létrehozása sikeres volt.
DocumentType
DocumentData
Számlázási utasítás beküldés és sikeres feldolgozás esetén, az elkészült számla PDF képe base64 enkódolt formában. A számla PDF kép visszaadáshoz a szerver oldalon további beállítások szükségesek. Ha ez nincs, akkor csak a 
 SzamlaAzon 
 BizonylatAzon információ jön vissza
...
  • 200 OK
  • 290 Not yet processed
  • 401 Unauthorized
  • 404 Not Found
  • 491 Auth param missing
  • 492 XML ERROR
  • 493 Already exist
  • 494 Too long time not processed
  • 495 Error on processing
  • 499 Other error
  • 590 INI error
  • 591 Database connect error
  • 592 Other Exception
Kliens implementáció
A kliens implementáció első lépése az API működésének tesztelése. A tesztelés két üzemmódban lehetséges.
  • API alapvető elérhetőségének ellenőrzése
  • API teljeskörű tesztelése
A működés teszteléséhez a a széles körben elterjedt CURL használható. Szintén használhatók a különböző böngészőkhöz készített bővítmények.
Intraneten kívüli használat
Bár az API alapvetően intranetes felhasználásra készült, nincs akadály annak, hogy megfelelő biztonsági feltételek megteremtésével az internet irányából is használható legyen.
A QSoft Kft. az API kipróbálásához webes teszt-felületet hozott létre, mely elérhető: http://dbconnector-apitest.sup.hu helyen.
A teszt API szintén elérhető az internetről is: http://dbconnector-apitest.sup.hu/api címen. 
A használathoz, teszteléshez szűkséges azonosító kódok előzetes egyeztetés után lesznek létrehozva.
Hibakezelés
API elérhetőség hiba
Authentikációs hiba
 Qsboxmegjegyz
A PDF számlakép lekérdezés csak az XML-ben levő AutoNyomtatas=True bekapcsolása esetén lehetséges. A számla késleltetett, kézi véglegesítése esetén, a REST API - iktatási tétel lekérdezés híváson keresztül lehet a számlaképet lekérni.
 Rögzítés
statusKodok
statusKodok
Hibakezelés - hibakódok
Az XML result-ban visszaadott státuszkódok megegyeznek a HTTP hívás státuszkódjaival. A fejlesztés során inkább a HTTP státuszkódokkal érdemes dolgozni,, mert előfordulhat olyan eset (pl.: time out), hogy a HTTP kérés válaszban nem az elvárt XML üzenet jön, hanem csak egy hibakód.
A témában további információk a DbConnector REST API általános dokumentációban.