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 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.
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] =>
)
)
)
)