Konto API

Dokumentacja Konto API systemu CallAPI / VPBX.

Informacje rozliczeniowe

Informacje rozliczeniowe API służy do pobrania aktualnego stanu rozliczeniowego konta: salda, typu konta (przedpłacone / postpaid), limitów wydatków oraz pozostałych środków.

Zapytanie zawsze dotyczy konta, do którego należy użyty token JWT.

Przykład z wykorzystaniem cURL: GET https://api.vpbx.pl/api/v1/account/accounting

curl --header "Content-Type: application/json" \
--header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAoMS0Iiwi" \
--request GET \
https://api.vpbx.pl/api/v1/account/accounting

Przykład poprawnej odpowiedzi:

{
    "result": "OK",
    "accounting": {
        "account_type": "prepaid",
        "currency": "Zloty",
        "currency_iso": "PLN",
        "balance": "95.06",
        "available_credit": "19.03",
        "limits": {
            "daily": {
                "spent": "80.97",
                "global": {
                    "limit": "200.00",
                    "remaining": "119.03",
                    "percentage_used": 40.48
                },
                "self_imposed": {
                    "limit": "100.00",
                    "remaining": "19.03",
                    "percentage_used": 80.97
                },
                "binding": "self_imposed"
            },
            "monthly": {
                "spent": "80.97",
                "global": {
                    "limit": "200.00",
                    "remaining": "119.03",
                    "percentage_used": 40.48
                },
                "self_imposed": {
                    "limit": null,
                    "remaining": null,
                    "percentage_used": null
                },
                "binding": "global"
            }
        },
        "as_of": "2026-07-31T12:01:02Z"
    }
}

Przykład błędu:
{
    "error": "token expired",
    "result": "error"
}

Odpowiedź

Obiekt accounting

Saldo a typ konta

Pole balance jest zawsze liczbą dodatnią, a jego znaczenie określa account_type:

Do decyzji, czy konto może wykonać połączenie lub wysłać wiadomość, należy używać pola available_credit, a nie balance. Dla kont prepaid jest to saldo ograniczone dodatkowo przez obowiązujące limity. Dla kont postpaid o dostępnych środkach decydują wyłącznie limity - saldo nie ogranicza wydatków.

Obiekt limits

Każdy z okresów (daily, monthly) zawiera:

Oba limity obowiązują jednocześnie - decyduje ten bardziej restrykcyjny. Pole binding wskazuje, z którego z nich wyliczono available_credit. W przypadku równych wartości zwracany jest global.

Obiekty global i self_imposed

Wartość null w polu limit oznacza, że limit nie jest ustawiony, czyli nie ogranicza konta. Nie należy jej interpretować jako limitu równego zero. Gdy limit nie jest ustawiony, pola remaining oraz percentage_used również przyjmują wartość null.

Jeśli konto przekroczy limit, pole remaining przyjmuje wartość 0.00, a percentage_used wartość 100 - wartości te nigdy nie są ujemne ani większe niż 100.

Format kwot

Wszystkie kwoty zwracane są jako łańcuchy znaków (String), a nie jako liczby, z dokładnością wynikającą z waluty konta - dla PLN, EUR i GBP są to dwa miejsca po przecinku ("95.06", "200.00").

Zapis tekstowy pozwala zachować pełną dokładność kwoty, w tym końcowe zera, co nie jest możliwe przy użyciu typu liczbowego w formacie JSON. Przed wykonaniem obliczeń lub porównań na tych wartościach należy przekonwertować je na typ dziesiętny - porównywanie ich jako tekstu da błędne wyniki.

Pole percentage_used nie jest kwotą i zwracane jest jako liczba.

Odpowiedź - błąd

Kody błędów HTTP

Kod 503 oznacza, że stanu konta nie udało się ustalić. W takiej sytuacji odpowiedź nigdy nie zawiera danych rozliczeniowych - w szczególności nie należy interpretować jej jako zerowego salda.