Pojęcia

Dostawca (Biller)

BillTech API wspiera kilkaset różnych dostawców usług takich jak telefonia, internet, energia, ochrona, a także spółdzielnie i wspólnoty mieszkaniowe. Listę obsługiwanych dostawców można pobrać korzystając z:

GET /api/billers HTTP/1.1

Atrybuty Dostawcy:

atrybutopis
billerId: stringIdentyfikator Dostawcy
Przykład: "PGNIG_MOH"
displayName: stringCzytelna nazwa Dostawcy
Przykład: "PGNiG Region mazowiecki"
directSyncEnabled: booleantrue, jeśli dla danego Dostawcy włączona jest synchronizacja poprzez logowanie do Systemu Dostawcy
url: string (opcjonalny)Adres url Systemu Dostawcy. Może posłużyć do prezentacji użytkownikowi, w celu klaryfikacji, do jakiego systemu ma podać dane uwierzytelniające.
Przykład: https://mbok.pgnig.pl
configurationHint: string (opcjonalny)Fragment html z sugestiami dla użytkownika np. link do zmiany hasła w Systemie Dostawcy, informacja o preferowanym sposobie uwierzytelnienia itp. Przykład:

Pomoc
rank: numberWskaźnik popularności Dostawcy. Większa wartość oznacza większą popularność.
aliases: string[]Nazwy zastępcze dla Dostawcy, rozwinięcia skrótów. Przydatne przy implementacji wyszukiwania.
Przykład: ["Polska Energia i Gaz"]
categories: string[]Kategorie usług świadczonych przez Dostawcę.
Przykład: ["Energia"]
billerStatus: stringInformacja o Statusie strony dostawcy
Przykład
{
"billerId": "MPWIK_LESZNO",
"displayName": "MPWiK Leszno",
"directSyncEnabled": true,
"url": "https://ebok.mpwik-leszno.pl/#/login",
"configurationHint": "<strong>Pomoc</strong> <ul> <li> Nie pamiętasz hasła? <a target=\"_blank\" href=\"https://ebok.mpwik-leszno.pl/#/login\"> Odzyskaj hasło </a> </li> <li> Nie masz jeszcze konta eBOK? <a target=\"_blank\" href=\"https://ebok.mpwik-leszno.pl/#/security/register\"> Zarejestruj się </a> </li> </ul>",
"rank": 2885,
"aliases": [
"Miejskie Przedsiębiorstwo Wodociągów i Kanalizacji Sp. z o.o. w Lesznie"
],
"categories": [
"Woda"
],
"billerStatus": "ACTIVE"
}

Konto (Account)

Utworzenie Konta jest równoznaczne z zapisaniem danych uwierzytelniających, które będą wykorzystane do logowania w Systemie Dostawcy. Tworząc Konto należy przekazać zgodę użytkownika na Regulamin Usługi.

Atrybuty Konta:

atrybutopis
accountId: stringIdentyfikator Konta
Przykład: "00E9CE3C-A66C-4B1E-8B5E-96DE252E9B80"
billerId: stringIdentyfikator Dostawcy
Przykład: "PGNIG_MOH"
principal: stringLogin/nazwa użytkownika/adres e-mail użytkownika w Systemie Dostawcy
Przykład: "[email protected]"
credentialStatus: stringStatus Danych Uwierzytelniających
Przykład: "VALID"
syncStatus: stringStatus Synchronizacji Konta.
Przykład: "SYNCHRONIZING"
consent: booleanAkceptacja Regulaminu Usługi przez użytkownika. Musi mieć wartość true.
lastLiabilityUpdateTime: numberData ostatniej zmiany szczegółów listy opłat w formacie UNIX timestamp (liczba sekund od 01-01-1970)
lastSyncTime: numberData ostatniej ukończonej synchronizacji w formacie UNIX timestamp (liczba sekund od 01-01-1970)
createdAt: numberData utworzenia Konta w formacie UNIX timestamp (liczba sekund od 01-01-1970)
subaccountsSubaccount[] (opcjonalny)Lista Subkont (jeśli są dostępne)
Przykład
{
"accountId": "5c7eb8bb-1be5-41a0-8d90-7f78c0c25f8c",
"billerId": "INNOGY",
"principal": "9000899268",
"credentialStatus": "UNVERIFIED",
"syncStatus": "IDLE",
"consent": true,
"lastLiabilityUpdateTime": "1970-01-01T00:00:00Z",
"lastSyncTime": "1970-01-01T00:00:00Z",
"accountType": "DIRECT_SYNC",
"createdAt": "2020-05-07T11:00:10.474237Z",
"subaccounts": [{
"subaccountId": "2af177af-3f10-4f4f-9f8a-232b5e3ef2a5",
"name": "42342655334"
},{
"subaccountId": "66c68b65-9197-47d8-bbc6-8c6ca33e4929",
"name": "86783445543"
}]
}

Subkonto (Subaccount)

W systemach niektórych Dostawców daje się wyróżnić subkonta na kontach użytkowników, które oznaczają wiele usług z osobną umową dostępnych po zalogowaniu pojedynczym zestawem danych uwierzytelniających. Jeśli dane konto użytkownika zawiera subkonta, w szczegółach Konta pojawia się lista Subkont, a poszczególne Opłaty zawierają Identyfikator Subkonta oznaczające przyporządkowanie do danego Subkonta.

Atrybuty Subkonta:

atrybutopis
subaccountId: stringIdentyfikator Subkonta
Przykład: "4F0E692A-F852-4A57-BEA8-6869E0FE25CA"
name: stringNazwa Subkonta - najczęściej numer umowy.
Przykład: "PL0037310001223103"
Przykład
{
"subaccountId": "2af177af-3f10-4f4f-9f8a-232b5e3ef2a5",
"name": "42342655334"
}

Opłata (Liability)

Opłata reprezentuje pojedyncze zobowiązanie użytkownika wobec Dostawcy np. fakturę. BillTech API pobiera najnowsze Opłaty oraz historię co najmniej 24 miesięcy (o ile jest dostępna).

Pobranie opłat przypisanych do danego Konta jest możliwe przy użyciu:

GET /api/accounts/{accountId}/liabilities HTTP/1.1

Jeśli Konto posiada subkonta, można również pobrać opłaty przypisane do konkretnego subkonta:

GET /api/accounts/{accountId}/subaccounts/{subaccountId}/liabilities HTTP/1.1

Atrybuty opłaty:

atrybutopis
liabilityId: stringIdentyfikator Opłaty
Przykład: "075F947F-9E28-4E8C-97FD-2A172CF9319E"
title: stringTytuł Opłaty - docelowo tytuł przelewu
Przykłady: "FV 5/2020", "Internet 01/2020", "Czynsz Kwiatowa 5 Jan Kowalski"
amount: numberKwota oryginalnego zobowiązania
Przykład: 59.99
amountToPay: number (opcjonalny)Pozostała kwota do opłacenia, jeśli znana
Przykład: 0.99
nrb: stringNumer konta bankowego do przelewu w formacie BBAN
Przykład: "94547475457591545979967060"
paymentDue: stringTermin płatności
Przykład: "2020-04-30"
paymentStatus: stringStatus opłacenia
documents: LiabilityDocument[] (opcjonalny)Lista możliwych do pobrania Dokumentów dotyczących opłaty, jeśli są dostępne.
subaccountId: string (opcjonalny)Identyfikator Subkonta, jeśli występuje
Przykład
{
"liabilityId": "23c64db3-b9b7-42ea-ab59-0635e96eb3e1",
"title": "181075910672341",
"amount": 36.89,
"amountToPay": 0.00,
"nrb": "85114012411068000015860984",
"paymentDue": "2018-10-31",
"paymentStatus": "KNOWN",
"documents": [],
"subaccountId": null
}

Dokument (LiabilityDocument)

W przypadku wybranych dostawców istnieje możliwość pobrania dokumentu PDF z fakturą przyporządkowaną do opłaty. W celu pobrania dokumentu, należy wygenerować link korzystając z:

POST /api/accounts/{accountId}/documents/{documentId}/link HTTP/1.1

Uzyskany link jest ważny przez 30 minut.

Atrybuty dokumentu:

atrybutopis
documentId: stringIdentyfikator Dokumentu
Przykład: "4F0E692A-F852-4A57-BEA8-6869E0FE25CA"
documentType: stringTyp dokumentu
Możliwe typy: "INVOICE"
documentFormat: stringFormat dokumentu
Możliwe formaty: "PDF","PNG"
Przykład
{
"documentId": "af759298-ca80-4912-bf62-c50cd35dfcd1",
"documentType": "INVOICE",
"documentFormat": "PDF"
}

Status Danych Uwierzytelniających (CredentialStatus)

Status Danych Uwierzytelniających odzwierciedla aktualny stan wiedzy na temat danych uwierzytelniających użytkownika do Systemu Dostawcy. Tuż po Zapisaniu Dostępu status ma wartość "UNVERIFIED". Po pierwszej Synchronizacji Danych status może zmienić wartość na jedną z: "VALID", "INVALID", "USER_ACTION_NEEDED"

Możliwe statusy:

statusopis
"UNVERIFIED"Dane Uwierzytelniające nie zostały jeszcze zweryfikowane przez BillTech API.
"VALID"Dane Uwierzytelniające są prawidłowe. Konto będzie cyklicznie synchronizowane.
"INVALID"Dane Uwierzytelniające są nieprawidłowe. Synchronizacja konta wyłączona do czasu poprawienia Danych Uwierzytelniających przez użytkownika.
"USER_ACTION_NEEDED"Dostęp do Systemu Dostawcy niemożliwy z powodu oczekującej akcji użytkownika (więcej informacji poniżej)

USER_ACTION_NEEDED

Sporadycznie zdarza się, że mimo prawidłowych Danych Uwierzytelniających, dostęp do Systemu Dostawcy jest zablokowany przez jakąś akcję, która może być wykonana jedynie osobiście przez użytkownika. Przykładem takiej sytuacji jest wymaganie zmiany hasła w Systemie Dostawcy. W takim przypadku użytkownik powinien samodzielnie zalogować się do Systemu Dostawcy i wykonać wymaganą akcję. W tym celu można wyświetlić użytkownikowi komunikat np.:

note

Synchronizacja niemożliwa. Zaloguj się do systemu dostawcy i sprawdź komunikaty.

Status Synchronizacji (SyncStatus)

Określa status Synchronizacji Danych.

Możliwe statusy:

statusopis
"IDLE"W tym momencie nie trwa żadna synchronizacja. Czekanie na kolejną synchronizację.
"SYNCHRONIZING"Synchronizacja trwa w tym momencie.
"DISABLED"Synchronizacja wyłączona.

Status Opłacenia (PaymentStatus)

Określa status opłacenia Opłaty. Co do zasady, BillTech API powinno być traktowane jako źródło prawdy o statusie opłacenia danej Opłaty. Status Opłacenia oraz pozostała kwota do zapłaty mogą zmieniać się w czasie. System Klienta powinien aktualizować te dane bazując na informacji zwracanej z BillTech API.

O ile status opłacenia jest znany ("KNOWN"), wartość pola amountToPay definiuje kwotę, którą użytkownik powinien opłacić.

info

Zazwyczaj mija kilka dni, zanim wpłata użytkownika zostaje zaksięgowana i zaprezentowana w Systemie Dostawcy. W tym czasie, BillTech API zwraca Status Opłacenia oraz pozostałą kwotę do zapłaty zgodnie z informacją dostępną w Systemie Dostawcy. Zalecamy implementację statusu przejściowego w Systemie Klienta, który będzie informował, że płatność została wykonana, ale nie została jeszcze zaksięgowana.

W niektórych przypadkach status opłacenia może być niedostępny. Jeśli status jest nieznany ("UNKNOWN"), pole amountToPay ma wartość null. W takim przypadku można umożliwić użytkownikowi podjęcie decyzji, czy Opłata była już opłacona.

Możliwe statusy:

statusopis
"KNOWN"status znany
"UNKNOWN"status nieznany

Przykłady

  1. Należy zapłacić 100 zł
    {
    "amount": 100.0,
    "amountToPay": 100.0,
    "paymentStatus": "KNOWN"
    }
  2. Należy zapłacić 0.64 zł
    {
    "amount": 66.0,
    "amountToPay": 0.64,
    "paymentStatus": "KNOWN"
    }
  3. Opłata w pełni opłacona
    {
    "amount": 28.22,
    "amountToPay": 0.0,
    "paymentStatus": "KNOWN"
    }
  4. Status opłacenia nieznany. Użytkownik może zdecydować o statusie
    {
    "amount": 127.73,
    "amountToPay": null,
    "paymentStatus": "UNKNOWN"
    }

Kategoria Dostawcy (Category)

Każdy Dostawca jest przypisany do jednej lub więcej kategorii w zależności od rodzaju świadczonych usług. Kategorie mogą być przydatne przy wyszukiwaniu Dostawców przez użytkownika.

Możliwe kategorie:

kategoria
"Telefon"
"Internet"
"Telewizja"
"Woda"
"Energia"
"Gaz"
"Czynsz"
"Ochrona"
"Ubezpieczenia"
"Inne"

Status dostawcy (Biller Status)

Status dostawcy informuje o tym, czy strona dostawcy działa poprawnie. Jeżeli na stronie nie są prowadzone żadne prace utrzymaniowe i strona działa poprawnie, możliwa jest następna synchronizacja. W przypadku wykrycia prac utrzymaniowych na stronie, dane konta mogą nie być aktualizowane.

Możliwe statusy:

statusopis
"ACTIVE"Strona dostawcy działa poprawnie, synchronizacje będą wykonywane
"MAINTENANCE"Na stronie dostawcy prowadzone są prace utrzymaniowe, dane kont mogą nie być aktualizowane do zakończenia prac