API

Dzięki przygotowanemu przez nas API możesz zintegrować serwis NIEZAPLACONE.INFO z dowolną aplikacją.

Aktualna wersja API (1.0.0), której dokumentacje znajdziesz poniżej, pozwala na dodawanie oraz aktualizowanie (w tym publikację, ukrywanie oraz archiwizowanie) długów na giełdzie. Wykorzystanie API oznacza akceptację regulaminu oraz polityki prywatności serwisu.

Rozwój giełdy może spowodować konieczność wprowadzenia zmian w API. Będziemy przekazywać informacje o zmianach za pomocą tej strony oraz za pośrednictwem dostępnych kanałów komunikacji z użytkownikami API.

Spis treści

Informacja ogólne
Metoda CREATE
Metoda UPDATE
- Publikacja i ukrywanie długu
- Archiwizacja długu
Zwracane odpowiedzi

Informacje ogólne

Adres URL

Zapytania powinny być wysyłane pod adres:

http://www.niezaplacone.info/api/debt

Zapytania są wysyłane przy pomocy protokołu HTTP.

Kodowanie

Wszystkie dane wysłane do API powinny być zakodowane w UTF-8.

Autoryzacja

Zapytanie powinno posiadać w nagłówku token: "Token: [token_aplikacji]”. Aby uzyskać token skontaktuj się z Biurem Obsługi Klienta.

Typy długu

W zapytaniu parametr "type" dot. długu może przyjmować wartości: "personal", "corporate".

Typy należności

W zapytaniu parametr "type" dot. należności może przyjmować wartości:

"invoice",
"transport_invoice",
"leasing_installment",
"interest_note",
"wz_document",
"payment_order",
"charge_note",
"advance_payment",
"excess_payment",
"businesses_contract",
"individuals_contract",
"business_individual_contract".

Pola obowiązkowe

id
name
type
identificationNumber
address
city
price
postcode
dla invoices:
- number
- amount
- saleDate
- paymentDate

Pola nieobowiązkowe

comments
email
phone
published
archiveReason
dla invoices:
- type

Minimalna kwota długu

Aby dodać dług w systemie Giełda Długów kwota długu powinna być większa bądź równa 1 zł. W jsonie wartość pola "amount" musi wynosić minimum 1,00.

Limity jednoczesnych wywołań API

W związku z limitami nałożonymi na bazę danych maksymalna liczba jednoczesnych zapytań do API wynosi 60. W celu uzyskania szczegółowych informacji prosimy o kontakt na adres bok@niezaplacone.info.

Metoda CREATE

Dodaje długi do systemu NIEZAPLACONE.INFO. Dane przesyłane metodą POST. W jedynym jsonie możliwe jest dodanie na raz wielu dłużników wraz z długami.

Przykładowe dane:

[
    {
        "id" : "ID1",
        "name": "Firma S.A.",
        "type": "corporate",
        "identificationNumber": "23423266490",
        "address": "os. Firmowe C51/1",
        "comments": "Sprzedam dług pilnie!",
        "email": "adres@domena.pl",
        "phone": "0048100200300",
        "city": "Kraków",
        "price": "1000.00",
        "postcode": "32-500",
        "invoices": [
            {
                "type": "leasing_installment",
                "number": "DOK 1",
                "amount": "1523,95",
                "saleDate": "2015-01-01",
                "paymentDate": "2015-01-14"
            }
        ]
    },
  {
        "id" : "ID2",
        "name": " Nowa firma Sp. z o.o",
        "type": "corporate",
        "identificationNumber": "6331723681",
        "address": "ul. Fabryczna 3A",
        "email": "adres@firma.pl",
        "city": "Warszawa",
        "price": "2200,00",
        "postcode": "11-340",
        "invoices": [
            {
                "type": "invoice",
                "number": "FR/20138276",
                "amount": "1864,01",
                "saleDate": "2015-02-02",
                "paymentDate": "2015-02-16"
            },
            {
                "type": "invoice",
                "number": "FR/20138280",
                "amount": "538,00",
                "saleDate": "2015-02-05",
                "paymentDate": "2015-03-01"
            }
        ]
    }
]

Metoda UPDATE

Aktualizuje długi w systemie NIEZAPLACONE.INFO. Dane przesyłane metodą PUT. W jedynym jsonie możliwe jest aktualizowanie wielu dłużników wraz z długami na raz.

Przykładowe dane:

 [
    {
        "id" : "ID1",
        "name": "Nowa Firma S.A.",
        "type": "corporate",
        "identificationNumber": "23423266490",
        "address": "os. Firmowe C51/1",
        "comments": "Sprzedam dług pilnie!",
        "email": "adres@domena.pl",
        "phone": "0048100200300",
        "city": "Kraków",
        "price": "1000.00",
        "postcode": "32-500",
        "invoices": [
            {
                "type": "invoice",
                "number": "FR/01",
                "amount": "200.02",
                "saleDate": "2015-01-01",
                "paymentDate": "2015-01-14"
            },
            {
                "type": "invoice",
                "number": "FR/02",
                "amount": "300,01",
                "saleDate": "2015-02-01",
                "paymentDate": "2015-02-14"
            }
        ]
    },
    {
        "id" : "ID2",
        "name": " Nowa firma Sp. z o.o",
        "type": "corporate",
        "identificationNumber": "6331723681",
        "address": "ul. Fabryczna 3A",
        "email": "adres@firma.pl",
        "city": "Warszawa",
        "price": "2200,00",
        "postcode": "11-340",
        "invoices": [
            {
                "type": "invoice",
                "number": "FR/20138276",
                "amount": "2000,00",
                "saleDate": "2015-02-02",
                "paymentDate": "2015-02-16"
            }
         ]
   }
]

Publikacja i ukrywanie długu

Aby opublikować lub ukryć dług w systemie Giełda Długów w jsonie należy przesłać parametr "published" podając odpowiednią wartość: true lub false.

W przypadku, gdy parametr "published " nie jest przesłany w jsonie, dług domyślnie traktowany jest jako opublikowany.

Archiwiziacja długu

Aby zarchiwizować dług w systemie Giełda Długów w jsonie należy przesłać parametr "archiveReason", który może przyjmować następujące wartości:

"spłata",
"sprzedaż",
"sprzeciw dłużnika",
"usunięcie konta klienta",
"inny powód".

Zwracane odpowiedzi

"result":
- "result": true - identyfikuje powodzenie akcji
- "result": false - identyfikuje wystąpienie błędu
"error": kod_błędu (opcjonalnie)
"warnings": json_z_warningami(opcjonalnie)

Skuces

{"result": true }

Skuces z ostrzeżeniami

W przypadku brakujących, nieprawidłowych argumentów skrypt zostanie wykonany, ale do bazy danych systemu Giełda Długów zostaną dodane tylko te dane, do których nie zostały zgłoszone ostrzeżenia.

Dług bez podanego id(liczba przesyłana w odpowiedzi wskazuje na kolejność, w której występuje dług w jsonie):

{"result":true,"warnings":{"DEBTS_WITHOUT_ID":[1]}}

Nieznaleziono długu o podanym id(liczba przesyłana w odpowiedzi wskazuje na kolejność, w której występuje dług w jsonie):

{"result":true,"warnings":{"DEBTS_NOT_FOUND":[1]}}

Dług o podanym id istnieje w systemie(liczba przesyłana w odpowiedzi wskazuje na kolejność, w której występuje dług w jsonie):

{"result":true,"warnings":{"DEBTS_ALREADY_EXISTING":[1]}}

ID długu powtarza się w przesłanym jsonie:Kotwica

{"result":true,"warnings":{"DEBTS_DUPLICATED_IDS":["ID2"]}}

Niepoprawna wartość długu:

{"result":true,"warnings":{"DEBTS_INVALID":{"1":["type"]}}}

Numery należności powtarzają się w długu:

{"result":true,"warnings":{"INVOICES_DUPLICATED_IDS":{"1":["DOK 1"]}}}

Niepoprawna wartość należności w długu:

{"result":true,"warnings":{"INVOICES_INVALID":{"1":{"1":["amount"]}}

Dług jest (już) zarchiwizowany

{"result":true,"warnings":{"DEBTS_ARCHIVED":[1]}}

Błąd API

Błąd API oznacza brak możliwości wykonania skryptu, dane podane w jsonie nie zostaną dodane do bazy danych w systemie Giełda Długów.

Brak lub pusty token w zapytaniu:

{"result": false,"error": "NO_AUTH_TOKEN"}

Token nie jest przypisany do żadnego klienta API:

{"result": false,"error": "AUTH_TOKEN_INVALID"}

Puste zapytanie:

{"result": false,"error": "NO_JSON"}

Niepoprawny json w zapytaniu:

{"result": false,"error": "INVALID_JSON"}

Osiągnięto limit dodawania długów na dany miesiąc

{"result":false,"error":"DEBTS_LIMIT_REACHED"}

W celu uzyskania szczegółowych informacji prosimy o kontakt na adres bok@niezaplacone.info.