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

1 API token generálás
2 Kliens letöltése
3 Kliens telepítése
4 Példa PHP file készítése
5 Számlakészítés és hozzá kapcsolódó példák
- 5.1 Partner létrehozása
- 5.2 Bankszámla létrehozása
6 Számla létrehozása
7 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.

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

Third-party API csomagok

Node.JS

https://www.npmjs.com/package/@codingsans/billingo-client

Billingo help