Dokumentacja

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

Spis treści

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 ZE SŁOWNIKA",
      "totalAmount": 443907,
      "deliveryCost": 1230,
      "deliveryNetCost": 1000,
      "deliveryCostVatRate": 23,
      "deliveryCostVatAmount": 230,
      "products": [
          {
              "name": "Lenovo Ideapad 120S-14IAP",
              "quantity": 1,
              "price": 246000,
              "netPrice": 200000,
              "vatRate": 23
              "vatAmount": 46000,
              "photoUrl": "01e5f8",
              "ean": "9002490100070",
              "externalId": "123"
              "category": "productCategory"
          },
          {
              "name": "Lenovo Ideapad 120S-14IAP",
              "quantity": 1,
              "price": 196677,
              "netPrice": 159900,
              "vatRate": 23,
              "vatAmount": 36777,
              "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": "Różana",
          "buildingNumber": "1",
          "apartmentNumber": "1",
          "postalCode": "10-899",
          "city": "Warszawa",
          "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. 140). 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 brutto wszystkich produktow wraz z kosztem dostawy
deliveryCost int, null nie Znaki numeryczne, pusta wartosc - koszt dostawy brutto
deliveryNetCost int, null nie Znaki numeryczne, pusta wartosc - koszt dostawy netto
deliveryCostVatRate int, null nie Znaki numeryczne, pusta wartosc - stawka VAT kosztu dostawy (null - VAT ZW)
deliveryCostVatAmount int, null nie Znaki numeryczne, pusta wartosc - wartosc VAT kosztu dostawy
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 - cena brutto
netPrice int, null nie Znaki numeryczne, pusta wartosc - cena netto
vatRate int, null nie Znaki numeryczne, pusta wartosc - stawka VAT (null - VAT ZW)
vatAmount int, null nie Znaki numeryczne, pusta wartosc - wartosc VAT
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