...

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.

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

...

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

Rögzítés
teszt teszt

API tesztelése

GET | POST 
     http://server/dbconnector/api/v1/test

...

Result
   XML - <Success>    :  true | false
   XML - <StatusCode> :  A HTML státuskódhoz hasonló részletesebb információ.

...

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.

...

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<DbConnectorResponse>
    <Success>true</Success>
    <StatusCode>200</StatusCode>
    <Message>API build: 1.0.6536M (2018.08.09.  <Message>DbConnector16:07:30) DbConnector DLL: 15.1 (2018.0408.01. 8:16:32)</Message>
</DbConnectorResponse>

Rögzítés
xmlSzamla xmlSzamla

Számla beküldése

POST
     http://server/dbconnector/api/v1/xmlszamlapostxml

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.

...

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 - <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@testUpload.xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<DbConnectorResponse>
    <Success>true</Success>
    <StatusCode>200</StatusCode>
    <SzamlaToken>7085BEEC<Token>7085BEEC-93B0-4FE1-88BB-F531EDAC38D6</SzamlaToken>Token>
</DbConnectorResponse>

Rögzítés
upload upload

Számla csatolmány feltöltése

POST
     http://server/dbconnector/api/v1/upload

A 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 XML-t 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 az <Elojegyzett_Szamlak><Szamlak><Szamla><Csatolmanyok> adattagban.

CURL.EXE    ^
  -X POST   ^
     http://server:8080/dbconnector/api/v1/upload ^
  -H pkod:SajatSupPartnerKod  ^
  -H lickod:SajatSupLicKod    ^
  -F file=@testupload.jpg

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<DbConnectorResponse>
    <Success>true</Success>
    <StatusCode>200</StatusCode>
    <Message>File feltöltés sikeres</Message>
    <Token>74cc7200-b9fc-4fd8-a1cf-8942c09afc35</Token>
</DbConnectorResponse>

Rögzítés
getStatus getStatus

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 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), 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>  <BizonylatAzon> : Az elkészült számla azonosítója a SUP rendszerben (napló | számla sorszám).
   XML - <PdfDocument>  <PdfDocument>   : Az elkészült számla PDF számlaképe (megfelelő SUP beállítás esetén).

...

 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<DbConnectorResponse>
    <Success>true</Success>
    <StatusCode>200</StatusCode>
    <SzamlaAzon>499<BizonylatAzon>499|DBC0001/18</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

Rögzítés
statusKodok statusKodok

Hibakódok

• 200 OK
• 290 Not yet processed
• 401 Unauthorized
• 404 Not Found
• 490 Auth param missing
• 491 Body or 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ő url 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