Dokumentacja

Dokumentacja przedstawia krok po kroku jak w prosty i szybki sposób skomunikować
Twój sklep z Comfino.

Spis treści

Integracja Sklepu

  1. Wprowadzenie
  2. Uwierzytelnienie użytkownika API
  3. Pobieranie produktów finansowych
  4. Pobieranie parametrów najlepszej oferty
  5. Składanie wniosku kredytowego
  6. Notyfikowanie statusu do sklepu
  7. Zmiana kwoty zamówienia
  8. Anulowanie wniosku
  9. Zlecenie wypłaty środków
  10. Dodawanie punktu sprzedaży usług
  11. Aktualizacja danych punktu sprzedaży usług
  12. Pobieranie punktu sprzedaży usług
  13. Pobieranie listy wszystkich punktów sprzedaży usług
  14. Wartości słownikowe
  15. Rejestracja nowego sklepu
  16. Rejestracja nowego sklepu - pobieranie zgód
  17. Rejestracja nowego sklepu - sprawdzanie statusu aktywacji
  18. Widgety

Składanie wniosku kredytowego

  • Wszystkie kwoty przesyłane do API powinny być polem typu int oraz podane w groszach.
  • Zapytanie jest sprawdzane pod kątem poprawności przesyłanych wartości.
  • Zamówienie może zawierać rabaty, które pomniejszają wartość koszyka i kredytu
  • Zamówienie może zawierać dodatkowe koszty, które wynikają z obsługi zamówienia
  • W szczególnych przypadkach możliwa jest późniejsza zmiany kwoty zamówienia.

Zapytanie:

curl -X POST 'http://{HOST_API}/v1/orders' \
--header 'API-KEY: {API-KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "notifyUrl": "https://your-shop.tld/notify",
  "returnUrl": "https://your-shop.tld/thanks",
  "orderId": "{twój_identyfikator_zamówienia}",
  "loanParameters": {
    "term": 123,
    "type": "INSTALLMENTS_ZERO_PERCENT",
    "allowedProductTypes": ["INSTALLMENTS_ZERO_PERCENT","PAY_LATER"]
  },
  "cart": {
      "category": "KATEGORIA Z SŁOWNIKA",
      "totalAmount": 100000,
      "deliveryCost": 1000,
      "products": [
          {
              "name": "Lenovo Ideapad 120S-14IAP",
              "quantity": 1,
              "price": 12321,
              "photoUrl": "01e5f8",
              "ean": "9002490100070",
              "externalId": "123"
              "category": "productCategory"
          },
          {
              "name": "Lenovo Ideapad 120S-14IAP",
              "quantity": 1,
              "price": 159900,
              "photoUrl": "01e5f8",
              "ean": "9002490100070",
              "externalId": "123",
              "category": "productCategory"
          }
      ]
  },
  "customer": {
    "firstName": "John",
    "lastName": "John",
    "taxId": null,
    "email": "dadas@da.pl",
    "phoneNumber": "312213213",
    "ip": "ip klienta",
    "regular": false,
    "logged": false,
    "address": {
      "street": "Rowowa",
      "buildingNumber": "1",
      "apartmentNumber": "1",
      "postalCode": "10-899",
      "city": "Karłowice",
      "countryCode": "PL"
    }
  },
  "seller": {
    "taxId": "1234567890"
  },
  "accountNumber": "75114011244753619198148640",
  "transferTitle": "Płatność za zamówienie 1234ABCDE"
}'

Definicja pól:

Nazwa pola Typ Wymagane Format
notifyUrl string nie Znaki alfanumeryczne (max. 255)
returnUrl string tak Znaki alfanumeryczne (max. 255)
orderId string tak Znaki alfanumeryczne (max. 36)
loanParameters object tak Obiekt w formacie JSON
cart object tak Obiekt w formacie JSON
customer object tak Obiekt w formacie JSON
seller object nie Obiekt w formacie JSON lub pusta wartosc. Dla typu konta merchant pole jest pomijane. Dla marketplace'u jest wymagane oraz NIP musi byc wczesniej zdefiniowany metoda sale-point-add.
accountNumber string nie Znaki numeryczne (max. 26)
transferTitle string, null nie Znaki numeryczne (max. 160). Tytul przelewu jaki otrzyma Sklep od Comfino w przypadku udanego sfinansowania zakupu. Pole jest nieobowiazkowe, jesli tytul przelewu nie zostanie spracyzowany w tym polu, to przelew zatytulujemy wartoscia z pola orderId.

loanParameters:

Nazwa pola Typ Wymagane Format
term int, null nie Znaki numeryczne, pusta wartosc
type string, null nie null lub wartosc slownikowa - zobacz sekcje typy produktow finansowych w dokumentacji wartosci slownikowych.
allowedProductTypes array, null nie null lub tablica wartosci slownikowych typu string - zobacz sekcje typy produktow finansowych w dokumentacji wartosci slownikowych.

Przekazanie opcjonalnego parametru allowedProductTypes w strukturze loanParameters powoduje zawężenie listy ofert na wniosku kredytowym do pozycji, których typ znajduje się na liście allowedProductTypes. Wartość null znosi ograniczenia i jest traktowana tak samo jak pominięcie parametru allowedProductTypes. Przekazanie pustej tablicy [] całkowicie blokuje wyświetlanie ofert na wniosku.

cart:

Nazwa pola Typ Wymagane Format
category string nie Znaki alfanumeryczne
totalAmount int tak Znaki numeryczne (kwota w groszach) - suma wszystkich produktow wraz z kwota dostawy
deliveryCost int nie Znaki numeryczne, pusta wartosc
products array tak obiekt JSON

cart.product:

Nazwa pola Typ Wymagane Format
name string tak Znaki alfanumeryczne
quantity int tak Znaki numeryczne
price int tak Znaki numeryczne
photoUrl string, null nie Znaki alfanumeryczne, pusta wartosc
ean string, null nie Znaki alfanumeryczne, pusta wartosc
externalId string, null nie Znaki alfanumeryczne, pusta wartosc
category string, null nie Znaki alfanumeryczne, pusta wartosc lub warto?ci zwi?zane z dodatkowymi op?atami za transakcje lub rabaty

customer:

Nazwa pola Typ Wymagane Opis Format
firstName string, null tak Imie Znaki alfanumeryczne (min. 2, max. 63) - jesli sklep ma imie i nazwisko w jednym polu, dzielimy lancuch po spacji i przekazujemy 1. element.
lastName string, null tak Nazwisko Znaki alfanumeryczne (min. 2, max. 63) - jesli sklep ma imie i nazwisko w jednym polu, dzielimy lancuch po spacji i przekazujemy wszystko od 2. elementu rozdzielajac spacja.
taxId string, null nie NIP Znaki alfanumeryczne
email string tak Adres e-mail Znaki alfanumeryczne
phoneNumber string tak Numer telefonu Znaki numeryczne (9 cyfr)
ip string tak Adres IP klienta (IPv4, IPV6) Znaki numeryczne z dozwolona kropka
regular bool, null nie Staly klient/ponowny zakup true, false, null
logged bool, null nie Zalogowany/niezalogowany true, false, null
address object, null nie Adres klienta obiekt JSON

customer.address:

Nazwa pola Typ Wymagane Format
street string, null nie Znaki alfanumeryczne, pusta wartosc
buildingNumber string, null nie Znaki alfanumeryczne, pusta wartosc
apartmentNumber string, null nie Znaki alfanumeryczne, pusta wartosc
postalCode string, null nie Znaki alfanumeryczne, pusta wartosc
city string, null nie Znaki alfanumeryczne, pusta wartosc
countryCode string, null nie Znaki alfanumeryczne, pusta wartosc

seller:

Nazwa pola Typ Wymagane Format
taxId string, null nie Znaki alfanumeryczne (10 znakow), pusta wartosc

Dodatkowe koszty związane z obsługą płatności i przesyłką:

Jeśli do wartości kredytu chcemy doliczyć dodatkowe koszty związane z obsługą płatności lub wysyłką, musimy dodać produkt o kategorii ADDITIONAL_FEE wraz z wartością. Suma wszystkich wartości w koszyku razy ilość produktów musi się równać wartości koszyka w totalAmount.

curl -X POST 'http://{HOST_API}/v1/orders' \
--header 'API-KEY: {API-KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "notifyUrl": "https://your-shop.tld/notify",
  "returnUrl": "https://your-shop.tld/thanks",
  "orderId": "{twój_identyfikator_zamówienia}",
  "loanParameters": {
    "term": 10,
    "type": "INSTALLMENTS_ZERO_PERCENT"
  },
  "cart": {
      "category": "KATEGORIA Z SŁOWNIKA",
      "totalAmount": 36000,
      "deliveryCost": 1000,
      "products": [
          {
              "name": "Lenovo Ideapad 120S-14IAP",
              "quantity": 1,
              "price": 10000,
              "photoUrl": "01e5f8",
              "ean": "9002490100070",
              "externalId": "123"
              "category": "productCategory"
          },
          {
              "name": "Lenovo Ideapad 120S-14IAP",
              "quantity": 1,
              "price": 20000,
              "photoUrl": "01e5f8",
              "ean": "9002490100070",
              "externalId": "123",
              "category": "productCategory"
          },
          {
            "name": "Dopłata rodzaj płatności",
            "quantity": 1,
            "price": 5000,
            "category": "ADDITIONAL_FEE"
          }
      ]
  },
  "customer": {
    "firstName": "John",
    "lastName": "John",
    "taxId": null,
    "email": "dadas@da.pl",
    "phoneNumber": "312213213",
    "ip": "ip klienta",
    "regular": false,
    "logged": false,
    "address": {
      "street": "Rowowa",
      "buildingNumber": "1",
      "apartmentNumber": "1",
      "postalCode": "10-899",
      "city": "Karłowice",
      "countryCode": "PL"
    }
  },
  "seller": {
    "taxId": "1234567890"
  },
  "accountNumber": "75114011244753619198148640",
  "transferTitle": "Płatność za zamówienie 1234ABCDE"
}'

Rabaty:

Zamówienie może zawierać rabaty, które pomniejszają wartość kredytu, wtedy musimy dodać produkt o kategorii DISCOUNT i ujemnej kwocie rabatu. Suma wszystkich wartości w koszyku razy ilość produktów musi się równać wartości koszyka w totalAmount.

curl -X POST 'http://{HOST_API}/v1/orders' \
--header 'API-KEY: {API-KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "notifyUrl": "https://your-shop.tld/notify",
  "returnUrl": "https://your-shop.tld/thanks",
  "orderId": "{twój_identyfikator_zamówienia}",
  "loanParameters": {
    "term": 10,
    "type": "INSTALLMENTS_ZERO_PERCENT"
  },
  "cart": {
      "category": "KATEGORIA Z SŁOWNIKA",
      "totalAmount": 26000,
      "deliveryCost": 1000,
      "products": [
          {
              "name": "Lenovo Ideapad 120S-14IAP",
              "quantity": 1,
              "price": 10000,
              "photoUrl": "01e5f8",
              "ean": "9002490100070",
              "externalId": "123"
              "category": "productCategory"
          },
          {
              "name": "Lenovo Ideapad 120S-14IAP",
              "quantity": 1,
              "price": 20000,
              "photoUrl": "01e5f8",
              "ean": "9002490100070",
              "externalId": "123",
              "category": "productCategory"
          },
          {
            "name": "Nazwa rabatu",
            "quantity": 1,
            "price": -5000,
            "category": "DISCOUNT"
          }
      ]
  },
  "customer": {
    "firstName": "John",
    "lastName": "John",
    "taxId": null,
    "email": "dadas@da.pl",
    "phoneNumber": "312213213",
    "ip": "ip klienta",
    "regular": false,
    "logged": false,
    "address": {
      "street": "Rowowa",
      "buildingNumber": "1",
      "apartmentNumber": "1",
      "postalCode": "10-899",
      "city": "Karłowice",
      "countryCode": "PL"
    }
  },
  "seller": {
    "taxId": "1234567890"
  },
  "accountNumber": "75114011244753619198148640",
  "transferTitle": "Płatność za zamówienie 1234ABCDE"
}'

Odpowiedź:

{
    "status": "CREATED",
    "externalId": "{twój_identyfikator_zamówienia}",
    "applicationUrl": "{url_do_przekierowania_na_stronę_formularza}"
}

Kody odpowiedzi:

  • 201 Created
  • 400 Bad Request
  • 401 Unauthorized
  • 405 Method Not Allowed
  • 500 Internal Server Error