Az API-leírás

Az API-leírás a PmtSegéd API fejlesztőknek szóló, nyilvános műszaki dokumentációja a pmtseged.hu/api-leiras oldalon. Bemutatja a hitelesítést, az összes végpontot, a paramétereket, a válaszokat és a hibakódokat, és a végpontokat a böngészőből ki is próbálhatod a saját API-kulcsoddal. Belépés nélkül is megnyitható, így a fejlesztődnek vagy a szoftverpartnerednek egyszerűen elküldheted a linket.

Hol találod?

• A PmtSegédben az API-kulcsok oldal tetején az API-leírás gombbal (új lapon nyílik).
• A pmtseged.hu weboldal láblécéből.
• Közvetlenül a pmtseged.hu/api-leiras címen.

Mit tartalmaz az oldal?

Az oldal tetején három gomb van:

• API-kulcs létrehozása: a PmtSegéd API-kulcsok oldalára visz (ehhez be kell lépned).
• OpenAPI (YAML) és OpenAPI (JSON): a teljes leírás letöltése OpenAPI 3 formátumban. Ezt a legtöbb fejlesztői eszköz (például Postman vagy kódgenerátorok) közvetlenül be tudja olvasni.

Alatta a végpontok témakörök szerint csoportosítva látszanak, például Ügyfelek, Ügyfél-import és -export, Képviselők, Tulajdonosok, Tényleges tulajdonosok, Ügyféldokumentumok, Ügyfélcsoportok, Előfizetés, API-kulcsok és Számlák. Egy végpontra kattintva lenyílik a leírása, a kérés mezői és a válasz szerkezete példákkal.

A leírás elején az Alapok rész összefoglalja a legfontosabbakat: a címet (https://api.pmtseged.hu), a JSON formátumot, az időpontok alakját, a listák, a keresés és a lapozás működését, valamint a hibakódok jelentését.

Kipróbálás a böngészőből

1. Hozz létre egy API-kulcsot a PmtSegéd API-kulcsok oldalán, és másold ki.
2. Az API-leírás oldalon kattints az Authorize gombra.
3. Illeszd be a kulcsot, és hagyd jóvá.
4. Nyisd le a kipróbálni kívánt végpontot. A mezők rögtön szerkeszthetők: töltsd ki a paramétereket, és kattints az Execute gombra.
5. Alatta látod a szerver válaszát.

Vigyázz: a kipróbálás a saját, éles adataidon fut. Egy létrehozó, módosító vagy törlő végpont a valódi ügyfeleidet változtatja meg, pontosan úgy, mintha a felületen tennéd.

A böngésző megjegyzi a beírt kulcsot, hogy ne kelljen minden alkalommal újra megadnod. Közös gépen a munka végén nyisd meg újra az Authorize ablakot, és kattints a Logout gombra.

Mire figyelj?

• A kulcs a létrehozó felhasználó nevében működik, és csak az ő adatait látja.
• Aktív előfizetés vagy próbaidő nélkül az ügyféladatokat kezelő végpontok 402 hibát adnak. A csomagban nem szereplő funkciókhoz a megfelelő csomag kell.
• A leírás magyar nyelvű, a hibaüzenetek is magyarul jönnek.

Gyakori kérdések

Kell programozói tudás az API-hoz? Igen, az API egy másik program összekapcsolására szolgál. Ha egy kész rendszert kapcsolsz össze a PmtSegéddel (például a KapuSegédet), elég az API-kulcsot megadnod abban a rendszerben, az API-leírásra nincs szükséged.

Változik az API? A leírás elején lévő Változásnapló mutatja a változásokat és a verziószámot.

Kihez fordulhat a fejlesztőm kérdéssel? Az ügyfélszolgálathoz az ugyfelszolgalat@pmtseged.hu címen.