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

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 alapú REST API 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.

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.
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.


Tartalom

Számla beküldése

POST

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.

 Megjegyzés

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 - <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.

Hívás minta
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 @testUpload.xml
Válasz minta
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<DbConnectorResponse>
    <Success>true</Success>
    <StatusCode>200</StatusCode>
    <Token>7085BEEC-93B0-4FE1-88BB-F531EDAC38D6</Token>
</DbConnectorResponse>

 Megjegyzés

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

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 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.

Hívás minta
CURL.EXE    ^
  -X POST   ^
     http://server:8080/dbconnector/api/v1/upload ^
  -H pkod:SajatSupPartnerKod  ^
  -H lickod:SajatSupLicKod    ^
  -F file=@testupload.jpg
Vá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>
    <Token>74cc7200-b9fc-4fd8-a1cf-8942c09afc35</Token>
</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 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 - <DocumentType>, <DocumentData> : Az elkészült számla PDF számlaképe (megfelelő SUP beállítás esetén).

Kérés minta
CURL.EXE    ^
  -X GET    ^
     http://server:8080/dbconnector/api/v1/getstatus?token=7085BEEC-93B0-4FE1-88BB-F531EDAC38D6  ^
  -H pkod:SajatSupPartnerKod   ^
  -H lickod:SajatSupLicKod
Vá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>
Válasz minta #2
 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<DbConnectorResponse>
    <Success>true</Success>
    <StatusCode>200</StatusCode>
    <BizonylatAzon>411|KI-0001/22</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
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.

 Megjegyzés

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 BizonylatAzon információ jön vissza

 Megjegyzés

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.

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.