Billingo API v3 - Swagger példa
SwaggerHub dokumentáció: https://api.billingo.hu/
Bevezető
A Billingo API v3 segítségével lehetőség van meglévő rendszereket összekötni a Billingo számlázó rendszerével. Egyszerű REST alapú API hívásokkal lehetőség van többek között az alábbi funkciókra:
Számla műveletek
Vevők létrehozás, szerkesztése
Bankszámlák létrehozás, szerkesztése
Számlatömbök létrehozás, szerkesztése
Termékek létrehozás, szerkesztése
Dokumentáció - SwaggerHub
A mindenkori legfrissebb Billingo API dokumentáció a SwaggerHub-on érhető el. Az oldal segítségével különböző kliensek/szerverek generálhatóak (Java, PHP, …), ezzel megkönnyítve a fejlesztők dolgát.
PHP alapú kliens példa
A példa egy PHP alapú kliens beüzemelését és kommunikációját mutatja be. Lépésről lépésre egy példa kéréssel és válaszokkal továbbá egyéb megjegyzésekkel jelenítjük meg a folyamatot.
Tartalmak
API token generálás
API token generáláshoz látogass el a Billingo API menüpontba.
Új kulcs létrehozáshoz kattints az “Új kulcs létrehozása“ gombra
Adj meg egy olyan nevet a kulcsnak amely jól meghatározza annak használatát, illetve válaszd ki, hogy milyen hatáskörrel rendelkezzen a kulcs.
Hatáskörök:
Olvasás: csak adatot kikérni tudunk, beszúrni, módosítani nem
Olvasás, írás: nem csak adatot tudunk kérni az API-tól, de tudunk módosítani és létrehozni is
A mentés gombra kattintva, az általad létrehozott kulcs megjelenik a listában, és ezzel egy időben használatra készen áll.
Jelen példában az API kulcs a következő: 63faa428-9044-11ea-8ed0-0242ac120005
API KULCS elkészült Ezzel készen is állsz az integráció használatára. Már csak a kapott kulcsot a kliensbe be kell illesztened és már hozhatod is létre a számláidat és partneredet az API-n keresztül.
Kliens letöltése
A megfelelő kliens letöltéséhez látogass el a https://api.billingo.hu weboldalra. Majd a jobb oldal Export fül lenyitásával válaszd ki a Client SDK és a listából töltsd le a megfelelő klienst(PHP).
Csomagold ki a megfelelő helyre és ugorj a Kliens telepítése szekcióra.
Kliens telepítése
A kicsomagolt mappába lépve telepítsd a kliens dependenciáit.
$ composer installPélda PHP file készítése
A YOUR_API_KEY cseréld ki a saját kulcsodra, és ezzel már készen is áll a kliensed a használatra.
<?php
require_once(__DIR__ . '/vendor/autoload.php');
$config = Swagger\Client\Configuration::getDefaultConfiguration()->setApiKey('X-API-KEY', 'YOUR_API_KEY');
$apiInstance = new Swagger\Client\Api\BankAccountApi(
new GuzzleHttp\Client(),
$config
);Számlakészítés és hozzá kapcsolódó példák
Egy egész példa sorozat ahhoz hogy számlát tudj létrehozni, egy bizonyos partnernek.
Partner létrehozása
POST https://app.swaggerhub.com/apis/Billingo/Billingo/3.0.0#/Partner/CreatePartner
Első lépésként hozd létre a partnert az alábbi módon:
<?php
require_once(__DIR__ . '/vendor/autoload.php');
$config = Swagger\Client\Configuration::getDefaultConfiguration()->setApiKey('X-API-KEY', 'YOUR_API_KEY');
$apiInstance = new Swagger\Client\Api\PartnerApi(
new GuzzleHttp\Client(),
$config
);
$body = new \Swagger\Client\Model\PartnerUpsert([
'name' => 'Test Partner',
'address' => [
'country_code' => \Swagger\Client\Model\Country::HU,
'post_code'=> '1133',
'city' => 'Budapest',
'address' => 'Árbóc utca 6'
],
'emails' => ['hello@billingo.hu'],
'taxcode' => '1234567-2-10'
]);
try {
$result = $apiInstance->createPartner($body);
print_r($result);
} catch (Exception $e) {
echo 'Exception when calling PartnerApi->createPartner: ', $e->getMessage(), PHP_EOL;
}Példa válasz, amely már tartalmazza az általad létrehozott Partner ID-ját. Később ezzel hivatkozhatsz a partnerre.
A létrejött partnerünk ID-ja jelen esetben 12
Számlatömbök lekérdezése
GET https://app.swaggerhub.com/apis/Billingo/Billingo/3.0.0#/DocumentBlock/ListDocumentBlock
Válaszban megkapod a számlatömbjeidet és azok egyéb adatait:
Bankszámla létrehozása
POST https://app.swaggerhub.com/apis/Billingo/Billingo/3.0.0#/BankAccount/CreateBankAccount
Kérés:
Válasz:
Számla létrehozása
POST https://app.swaggerhub.com/apis/Billingo/Billingo/3.0.0#/Document/CreateDocument
Az előző példákon át megkaptál minden szükséges információt ahhoz, hogy elő tudj állítani egy számlát. Vagyis rendelkezel partner_id -val illetve block_id -val valamint bank_account_id -val. Ezek elengedhetetlenek az új számla készítéséhez. Következő lépésként készítsd elő az új számla adatait:
Korábban létrehozott értékek:
partner_id: 12
block_id: 2
bank_account_id: 4
Számla adatok JSON formában
A számla létrehozása:
Eredményként megkapjod a Document Swagger objektumot, amely már tartalmazza a létrejött számla adatait, és természetesen az ID-ját is. Ez a válasz megfelel a Document Schema-nak.