A DbConnector alkalmazáshoz kapcsolódó API felület az alkalmazás néhány funkcióját delegálja intranetes webszolgáltatásként.
A webszolgáltatás XML alapú REST API kezelési móddal érhető el.
Az API a helyi intranet saját ... szerver név stb...
Az API a következő belépési ponton érhető el.
POST | GET http://server/dbconnector/api/v1/
Az API 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.
Tartalom
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
API tesztelése
GET | POST http://server/dbconnector/api/v1/test
A hívás célja az API elérhetőségének tesztelése. Az elérhetőség egyszerű tesztelésére bármely böngésző alkalmas. A komplex teszteléséhez pl.: a széles körben elterjedt CURL használható.
Body paraméter (opcionális raw data) dummy
Result XML - <Success> : true | false XML - <StatusCode> : A HTML státuskódhoz hasonló részletesebb információ.
Alapesetben csak az API létezését teszteljük. Ez közel ekvivalens a böngésző címsorból meghívott móddal.
CURL.EXE ^
-X GET ^
http://server/dbconnector/api/v1/test ^
-F dummy=true
A teljes teszthez meg kell adni a hitelesítő adatokat is. Siker esetén egy verziószám a válasz.
CURL.EXE ^
-X POST ^
http://server:8080/dbconnector/api/v1/test ^
-H pkod:SajatSupPartnerKod ^
-H lickod:SajatSupLicKod
<?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>
</DbConnectorResponse>
Számla beküldése
POST http://server/dbconnector/api/v1/xmlszamla
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 webes felületen keresztül is elérhető legyen.
MegjegyzésParaméter (kötelező) XML : A számázási utasítás XML
Result XML - <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.
CURL.EXE ^
-X POST ^
http://server:8080/dbconnector/api/v1/postxml ^
-H pkod:SajatSupPartnerKod ^
-H lickod:SajatSupLicKod ^
-H "Content-Type: text/html; charset=UTF-8" ^
--data-ascii @test.xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<DbConnectorResponse>
<Success>true</Success>
<StatusCode>200</StatusCode>
<SzamlaToken>7085BEEC-93B0-4FE1-88BB-F531EDAC38D6</SzamlaToken>
</DbConnectorResponse>
Feldolgozottsági állapot lekérdezése
GET 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 token 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), valamint a számla PDF képet - base64 enkódolt formában.
Paraméter (kötelező) token : Az XML beküldéskor kapott token.
Result XML - <SzamlaAzon> : Az elkészült számla azonosítója a SUP rendszerben (napló | számla sorszám. XML - <PdfDocument> : Az elkészült számla PDF számlaképe (megfelelő SUP beállítás esetén).
CURL.EXE ^
-X GET ^
http://server:8080/dbconnector/api/v1/getstatus?token=B03D8188-2159-4174-A866-E214988DFB2A ^
-H pkod:SajatSupPartnerKod ^
-H lickod:SajatSupLicKod
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<DbConnectorResponse>
<Success>false</Success>
<StatusCode>290</StatusCode>
<Message>A tetel feldolgozasra var</Message>
</DbConnectorResponse>
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<DbConnectorResponse>
<Success>true</Success>
<StatusCode>200</StatusCode>
<SzamlaAzon>499|DBC0001/18</SzamlaAzon>
</DbConnectorResponse>
Válasz XML
Az API hívásra adott válasz XML egy <DbConnectorResponse> séma alapján jön létre.
Adattagok
Success | Sikeres feldolgozás esetén true, egyéb esetben false |
StatusCode | Sikertelen feldolgozás esetén további, részletesebb információkat közöl |
Message | Sikertelen feldolgozás esetén szöveges információk a problémáról, összhangban a StatusCode válasszal |
Token | Ké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 | 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 | 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 információ jön vissza |
Hibakódok
- 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