Fejlesztőknek

Általános leírás

Az ACS Invoicing rendszer rendelkezik API kapcsolódási lehetőséggel, amin keresztül automatikusan létrehozhatunk számlákat, ügyfeleket. API-n keresztül bármely webshoppal összekapcsolható az ACS Invoicing számlázó rendszere.

A rendszer REST API szolgáltatást használ a kommunikációra, ezzel a fejlesztőnek lehetőséget adunk adatok lekérdezésére, létrehozásra és módosításra. Ezeket az adatokat és végpontokat tudja használni saját rendszere fejlesztésénél.

A fejlesztéshez biztosítunk teszt környezetet. A teszt környezetet szabadon használhatja fejlesztésének a teszteléséhez.

Az API hívások listája, illetve az egyes végpontok paraméterei itt találhatóak:
https://staging.acsinvoicing.com/api/

A dokumentációban részletesen megtekinthetőek a végpontok, a hozzájuk tartozó paraméterek és egy helyes válasz.

 

 

A dokumentáció jobb felső sarkában be lehet állítani az authentikációt, így ténylegesen helyes adatokat lehet lekérni a teszt környezetből.

A teszt környezet végpontja: https://staging.acsinvoicing.com/api/v1/

 

FONTOS:

• A teszt környezet adatbázisát bizonyos időközönként szinkronizáljuk az éles rendszerrel, így a tesztkörnyezetben, kérjük mindig ellenőrizze a hívások paramétereit.
• A teszt környezetben valódi számlák és valódi ügyfelek nem jönnek létre.

 

Authentikáció

A tokenek (authentikációs kulcs) megszerzéséhez a felhasználói fióknak / vállalkozásnak élő előfizetéssel kell rendelkeznie!

A lekérdezésekhez egy egyedi auth-token (OAuth 2.0 authentikáció) szükséges. Ezt a token-t e-mailben tudja tőlünk kérni: support@acsinvoicing.com

Minden token egyedi, felhasználónként és fejlesztési környezetenként más. Nem lehet használni teszt környezetben és éles rendszerben ugyanazt az authentikációs kulcsot. 

Az authentikációs kulcsot GET paraméterként lehet átadni a meghívandó végpont után.

 

Válasz/Response

A rendszer minden lekérdezésre JSON formátumban válaszol. A válaszban megtalálható a „status” és a „result” értékek. 

Hiba esetén a status értéke „error”, a result mezőben pedig megtalálható a hiba jellege és szöveges leírása.
Minden helyes válaszra van példa a dokumentációban: https://staging.acsinvoicing.com/api/

 

Lekérdezések

Általános lekérdezések

Az általános lekérdezésekkel a rendszerben lévő egységeket/adatokat lehet lekérni, melyeket a számlázásnál, vagy az ügyfélnél lehet használni.

Time

/api/v1/time
GET lekérdezés

A szerver idő lekérdezése.

Languages

/api/v1/languages
GET lekérdezés

A rendszerben használt nyelveket adja vissza azonosítókkal.

Countries

/api/v1/countries
GET lekérdezés

A rendszerben lévő országokat adja vissza, azonosítóval és országkóddal.

Payment Methods

/api/v1/paymentmethods 
GET lekérdezés

A rendszerben használt fizetési módokat és a felhasználó által felvett fizetési módokat adja vissza

Currencies

/api/v1/currencies 
GET lekérdezés

A rendszerben használt valutákat adja vissza.

Units

/api/v1/units 
GET lekérdezés

A rendszerben használt egységeket adja vissza

VAT

/api/v1/vat 
GET lekérdezés

A rendszerben használt adó csoportokat adja vissza
 

 

Számlázási lekérdezések

Számlák lekérdezése

/api/v1/invoices 
GET lekérdezés

Ezzel a lekérdezéssel tudjuk lekérni a rendszerben tárolt számlákat. A lekérdezés beépített lapozót használ, így figyeljünk a lekérdezés paramétereire. A lekérdezésben lekérdezés szűrhető dátumtól dátumig és sorrendezhető.

Számlák létrehozása

/api/v1/invoices 
POST lekérdezés

Ezzel a lekérdezéssel tudunk tömegesen létrehozni számlákat. A beküldött számlákat a meghatározott formátumba kell beküldeni. Az esetleges hiányzó adatokról a rendszer hibaüzenet formájában visszajelez (ebben az esetben nem történik meg a létrehozás).

Számla lekérdezése

/api/v1/invoice/{invoiceId}
GET lekérdezés

Ezzel a lekérdezéssel tudjuk lekérni egy számla adatait. A lekérdezés URL-jében szerepelnie kell a számla azonosítójának.

Számla létrehozása

/api/v1/invoice
POST lekérdezés

Ezzel a lekérdezéssel tudunk egy számlát létrehozni. A beküldött számlát a meghatározott formátumba kell beküldeni. Az esetleges hiányzó adatokról a rendszer hibaüzenet formájában visszajelez (ebben az esetben nem történik meg a létrehozás).

Számla fizetés létrehozás

/api/v1/invoice/{invoiceId}/pay
POST lekérdezés

Ezzel a lekérdezéssel tudunk egy számlának a fizetési módját és fizetési adatait frissíteni. A lekérdezés URL-jében szerepelnie kell a számla azonosítójának.

 

 

Ügyfél lekérdezések

Ügyfelek lekérdezése

/api/v1/customers 
GET lekérdezés

Ezzel a lekérdezéssel tudjuk lekérni a rendszerben tárolt ügyfeleinket. A lekérdezés beépített lapozót használ, így figyeljünk a lekérdezés paramétereire.

Ügyfél lekérdezése

/api/v1/customer/{customerId}
GET lekérdezés

Ezzel a lekérdezéssel tudjuk lekérni egy ügyfelünk adatait. A lekérdezés URL-jében szerepelnie kell az ügyfél azonosítójának.

Ügyfél módosítás

/api/v1/customer/{customerId}
PUT lekérdezés

Ezzel a lekérdezéssel tudjuk egy ügyfelünk adatait módosítani. A lekérdezés URL-jében szerepelnie kell az ügyfél azonosítójának.

Ügyfél létrehozás

/api/v1/customer
POST lekérdezés

Ezzel a lekérdezéssel tudunk egy új ügyfelet létrehozni a rendszerben. Létrehozás után a rendszerben létrehozott ügyfelet visszakapjuk a lekérdezés válaszában.