Miben segíthetünk?

Billingo API v3 - Swagger példa

Módosítva: 2020-06-12 11:15:06

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

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

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

<?php

require_once(__DIR__ . '/vendor/autoload.php');

$config = Swagger\Client\Configuration::getDefaultConfiguration()->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:

<?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
);

$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:

<?php
require_once(__DIR__ . '/vendor/autoload.php');

$config = Swagger\Client\Configuration::getDefaultConfiguration()->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.

Swagger\Client\Model\Document Object
(
    [container:protected] => Array
        (
            [id] => 7
            [invoice_number] => 2020-000006
            [type] => advance
            [block_id] => 2
            [payment_status] => paid
            [payment_method] => bankcard
            [gross_total] => 1270
            [currency] => HUF
            [conversion_rate] => 1
            [invoice_date] => DateTime Object
                (
                    [date] => 2020-05-08 00:00:00.000000
                    [timezone_type] => 3
                    [timezone] => Europe/Berlin
                )

            [fulfillment_date] => DateTime Object
                (
                    [date] => 2020-05-07 00:00:00.000000
                    [timezone_type] => 3
                    [timezone] => Europe/Berlin
                )

            [due_date] => DateTime Object
                (
                    [date] => 2020-05-07 00:00:00.000000
                    [timezone_type] => 3
                    [timezone] => Europe/Berlin
                )

            [paid_date] => DateTime Object
                (
                    [date] => 2020-05-08 00:00:00.000000
                    [timezone_type] => 3
                    [timezone] => Europe/Berlin
                )

            [organization] => Swagger\Client\Model\DocumentOrganization Object
                (
                    [container:protected] => Array
                        (
                            [name] => Teszt Attila Ev.
                            [tax_number] => 68723763-1-43
                            [bank_account] => Swagger\Client\Model\DocumentBankAccount Object
                                (
                                    [container:protected] => Array
                                        (
                                            [id] => 4
                                            [name] => Test Bank
                                            [account_number] => 00000000-00000000-00000000
                                            [account_number_iban] => 
                                            [swift] => 
                                        )

                                )

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

                                )

                            [small_taxpayer] => 
                            [ev_number] => 
                            [eu_tax_number] => 
                            [cash_settled] => 
                        )

                )

            [partner] => Swagger\Client\Model\Partner Object
                (
                    [container:protected] => Array
                        (
                            [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] => 
                            [id] => 12
                        )

                )

            [electronic] => 
            [comment] => here comes the invoice comment
            [tags] => Array
                (
                )

            [notification_status] => none
            [language] => hu
            [items] => Array
                (
                    [0] => Swagger\Client\Model\DocumentItem Object
                        (
                            [container:protected] => Array
                                (
                                    [product_id] => 8
                                    [name] => Teszt
                                    [net_unit_amount] => 1000
                                    [quantity] => 1
                                    [net_amount] => 1000
                                    [gross_amount] => 1270
                                    [vat] => 27%
                                    [vat_amount] => 270
                                )

                        )

                )

            [summary] => Swagger\Client\Model\DocumentSummary Object
                (
                    [container:protected] => Array
                        (
                            [net_amount] => 1000
                            [net_amount_local] => 0
                            [gross_amount_local] => 0
                            [vat_amount] => 270
                            [vat_amount_local] => 0
                            [vat_rate_summary] => Array
                                (
                                    [0] => Swagger\Client\Model\DocumentVatRateSummary Object
                                        (
                                            [container:protected] => Array
                                                (
                                                    [vat_name] => 27%
                                                    [vat_percentage] => 0.27
                                                    [vat_rate_net_amount] => 1000
                                                    [vat_rate_vat_amount] => 270
                                                    [vat_rate_vat_amount_local] => 0
                                                    [vat_rate_gross_amount] => 1270
                                                )

                                        )

                                )

                        )

                )

            [settings] => Swagger\Client\Model\DocumentSettings Object
                (
                    [container:protected] => Array
                        (
                            [mediated_service] => 
                            [without_financial_fulfillment] => 
                            [online_payment] => 
                            [round] => 0
                            [place_id] => 
                        )

                )

        )

)