Billingo API v3 - Swagger példa

2021.11.18. 08:07

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
Kliens letöltése
Kliens telepítése
Példa PHP file készítése
Számlakészítés és hozzá kapcsolódó példák
- Partner létrehozása
- Bankszámla létrehozása
Számla létrehozása
Node.JS

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 install

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

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:

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.

Swagger\Client\Model\Partner Object
(
    [container:protected] => Array
        (
            [id] => 12
            [name] => Test Partner
            [address] => Swagger\Client\Model\Address Object
                (
                    [container:protected] => Array
                        (
                            [country_code] => 
                            [post_code] => 1133
                            [city] => Budapest
                            [address] => Árbóc utca 6
                        )

                )

            [emails] => Array
                (
                    [0] => hello@billingo.hu
                )

            [taxcode] => 1234567-2-10
            [iban] => 
            [swift] => 
            [account_number] => 
            [phone] => 
            
        )
)

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

setApiKey('X-API-KEY', 'YOUR_API_KEY');

$apiInstance = new Swagger\Client\Api\DocumentBlockApi(
    new GuzzleHttp\Client(),
    $config
);
$page = 1;
$per_page = 25;

try {
    $result = $apiInstance->listDocumentBlock($page, $per_page);
    var_dump($result);
} catch (Exception $e) {
    echo 'Exception when calling DocumentBlockApi->listDocumentBlock: ', $e->getMessage(), PHP_EOL;
}

Válaszban megkapod a számlatömbjeidet és azok egyéb adatait:

Swagger\Client\Model\DocumentBlockList Object
(
    [container:protected] => Array
    (
        [data] => Array
        (
            [0] => Swagger\Client\Model\DocumentBlock Object
            (
                [container:protected] => Array
                (
                    [id] => 2
                    [name] => Számlák
                    [prefix] =>
                    [custom_field1] =>
                    [custom_field2] =>
                )
            )

            [1] => Swagger\Client\Model\DocumentBlock Object
            (
                [container:protected] => Array
                (
                    [id] => 3
                    [name] => Második számlatömb
                    [prefix] => MASOD
                    [custom_field1] => egyedi 1
                    [custom_field2] => egyedi 2
                )
            )

        )

        [total] => 2
        [per_page] => 25
        [current_page] => 1
        [last_page] => 1
        [prev_page_url] =>
        [next_page_url] =>
    )
)

Bankszámla létrehozása

POST https://app.swaggerhub.com/apis/Billingo/Billingo/3.0.0#/BankAccount/CreateBankAccount

Kérés:

setApiKey('X-API-KEY', 'YOUR_API_KEY');

$apiInstance = new Swagger\Client\Api\BankAccountApi(
    new GuzzleHttp\Client(),
    $config
);

$body = new \Swagger\Client\Model\BankAccount([
    'name' => 'Test Bank',
    'account_number' => '00000000-00000000-00000000',
    'currency' => 'HUF'
]);

try {
    $result = $apiInstance->createBankAccount($body);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling BankAccountApi->createBankAccount: ', $e->getMessage(), PHP_EOL;
}

Válasz:

Swagger\Client\Model\BankAccount Object
(
    [container:protected] => Array
        (
            [id] => 4
            [name] => Test Bank
            [account_number] => 00000000-00000000-00000000
            [account_number_iban] => 
            [swift] => 
            [currency] => HUF
            [need_qr] => 
        )
)

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

{
  "partner_id": 12,
  "block_id": 2,
  "bank_account_id": 4,
  "type": "advance",
  "fulfillment_date": "2020-05-07",
  "due_date": "2020-05-07",
  "payment_method": "bankcard",
  "language": "hu",
  "currency": "HUF",
  "electronic": false,
  "paid": false,
  "items": [
    {
      "product_id": 8,
      "quantity": 1
    }
  ],
  "comment": "here comes the invoice comment"
}

A számla létrehozása:

setApiKey('X-API-KEY', 'YOUR_API_KEY');

$apiInstance = new Swagger\Client\Api\DocumentApi(
    new GuzzleHttp\Client(),
    $config
);

$jsonBasedData = '{
    "partner_id": 12,
    "block_id": 2,
    "bank_account_id": 4,
    "type": "advance",
    "fulfillment_date": "2020-05-07",
    "due_date": "2020-05-07",
    "payment_method": "bankcard",
    "language": "hu",
    "currency": "HUF",
    "electronic": false,
    "paid": false,
    "items": [
        {
            "product_id": 8,
            "quantity": 1
        }
    ],
    "comment": "here comes the invoice comment"
}';

$data = json_decode($jsonBasedData, true);

$body = new \Swagger\Client\Model\DocumentInsert($data);

try {
    $result = $apiInstance->createDocument($body);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling DocumentApi->createDocument: ', $e->getMessage(), PHP_EOL;
}

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.