Home Credit - Partner API - ORDER - Future

Dokumentace API pro Home Credit API pro partnery.

> Verze dokumentace: 3.4.0 (12/2025)

V případě jakýchkoli dotazů se prosím obraťte na naše integrační oddělení (integrace_eshop@homecredit.cz).

Verze	Vydání	Datum vydání	Novinky
3.4.0 (12/2025)	CS135	8.12.2025	Průvodce migrací
3.2.1 (04/2024)	CS115	13.2.2024	Byl publikován jeden nový zdroj: Kontrola stavu API
3.2.1 (02/2024)	CS113	13.2.2024	Byly publikovány dva nové zdroje: Zrušit aplikaci a Získat podrobnosti o aplikaci
3.1.1 (01/2024)	CS112	17.1.2024	Nová verze API

> DŮLEŽITÁ POZNÁMKA: Volání zdrojů ze Slovenska MUSÍ používat příslušné vyhrazené koncové body .sk. Např. https://api.homecredit.sk/financning/v3/applications

Začínáme

Tento online dokument popisuje API Home Credit pro partnery - prostředek, pomocí kterého mohou partneři svým zákazníkům nabídnout výhody jedné z platebních metod nebo produktů Home Credit.

Popisované služby mají za cíl umožnit zákazníkům hladký průběh procesu online nákupu nebo sjednání úvěru. Služby, které umožňují dosažení tohoto cíle, jsou rozděleny do následujících skupin:

Skupina služeb	Účel
Bezpečnost	Bezpečnostní pravidla a zásady
Aplikační zdroje	Zdroje, které umožňují zpracování aplikace během celého jejího životního cyklu
Zdroje obchodního webu	Zdroje, které by měl partner vyvinout a zpřístupnit, aby mu HC mohla asynchronně sdělovat důležité změny týkající se konkrétních aplikací

Základní implementace

Základním a minimálním způsobem implementace HCO API je implementovat alespoň:

1. Přihlášení

• Partner musí být autorizován, aby měl přístup k většině zdrojů

2. Vytvoření aplikace

• Partner volá tento zdroj, aby zahájil proces schvalování úvěru vytvořením aplikace. Aplikace sama o sobě a její ID jsou nezbytné pro úspěšné dokončení procesu.

3. Přesměrování handlerů.

• Speciální URL adresy pro zákazníky, které zobrazují úspěšnost nebo zamítnutí platby (více informací zde).

4. Oznámení o žádosti

• Tento koncový bod musí být na vaší straně zpřístupněn, aby vám backend HC mohl asynchronně oznamovat důležité změny týkající se konkrétních žádostí.

5. Označit položky objednávky jako odeslané/doručené

• Home Credit nezačne proces finanční kompenzace, dokud není objednávka označena jako ODESLÁNA nebo DORUČENA .

Je nutné vyplnit všechny atributy označené jako "povinné" v žádosti. Vyplnění volitelných parametrů povede k lepší míře schválení žádosti. Partner by měl vždy zvážit vyplnění co největšího počtu atributů.

Zásady dokumentace

• atributy v objektu žádosti/odpovědi jsou volitelné, pokud není uvedeno jinak (příznak "povinné" pod názvem atributu)

• povinný atribut v nepovinném objektu znamená, že pokud je nepovinný objekt specifikován, musí obsahovat povinný atribut.

• všechny hodnoty v atributech požadavku/odpovědi jsou pouze příklady, s výjimkou hodnot výčtu - ty jsou jedinými možnými hodnotami pro daný atribut.

• dokumentace se řídí sémantickým verzováním, které rozlišuje mezi hlavními, vedlejšími a opravnými verzemi.

Konvence pojmenování

• pro všechny názvy objektů a atributů používáme camelCase

• pro hodnoty výčtu používáme CAPITAL_UNDERSCORE

• v názvech zdrojů používáme množné number

Klíčová slova použitá v tomto dokumentu (RFC 2119)

Klíčová slova "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY" a "OPTIONAL" v tomto dokumentu se interpretují tak, jak je popsáno v RFC 2119.

Zásady REST API Home Credit

Omezení požadavků

Mějte prosím na paměti následující omezení týkající se požadavků:

• Maximální velikost požadavku je 10 MB.

• Maximální velikost přijatého souboru je 500 kB.

• Zde je seznam podporovaných souborů:

Typ MIME	Příklad(y)
application/pdf	*.pdf
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet	*.xlsx
application/vnd.openxmlformats-officedocument.wordprocessingml.document	*.docx
application/vnd.openxmlformats-officedocument.presentationml.presentation	*.pptx
application/vnd.ms-excel	*.xls, *.xlt, *.xla
application/msword	*.doc, *.dot
application/vnd.ms-powerpoint	*.ppt, *.pot, *.pps, *.ppa
plain/text	*.csv, *.txt
image/jpeg	*.jpg, *.jpeg
image/png	*.png
image/gif	*.gif

Limity volání API

Když partner dosáhne limitu volání API (partner volá API vícekrát, než je jeho kvóta), obdrží HTTP chybu 429. K informování partnera o limitech používáme následující hlavičky odpovědi:

• X-Rate-Limit-Limit - Počet povolených požadavků v aktuálním období

• X-Rate-Limit-Remaining - počet zbývajících požadavků v aktuálním období

• X-Rate-Limit-Reset - počet sekund zbývajících v aktuálním období

Verze

V URL používáme verzi API (např. https://api.homecredit.cz/financing/v3/applications). Drobné změny a opravy (viz níže), které nenarušují zpětnou kompatibilitu, NEZVYŠUJÍ verzi API, tj. MOHOU se objevit bez předchozího upozornění a vaše aplikace by měla být připravena je zpracovat.

Drobné změny zahrnují:

• přidání nového zdroje

• přidání nového volitelného parametru záhlaví/URL nebo volitelného atributu těla k požadavku

• přidání nového atributu k tělu odpovědi

• přidání nových chybových kódů a zpráv, za předpokladu, že struktura chyb je stejná

Kódování odpovědi

Pokud není uvedeno jinak, všechny odpovědi jsou odesílány jako Content-Type: application/json; charset=utf-8.

Kódy stavu HTTP

V celé API používáme následující kódy stavu, s výjimkou toku OAuth, kdy jsou kódy odpovědí předepsány v RFC

• 200 OK - požadavek byl úspěšný

• 201 Created - požadavek byl úspěšný a zdroj byl vytvořen

• 202 Accepted - požadavek byl přijat ke zpracování, ale zpracování nebylo dokončeno

• 204 No Content - přijali jsme požadavek partnera, ale není co vrátit (např.např. odpověď je prázdná)

• 400 "Bad Request" - syntaktická chyba, např. v požadavku chybí požadované parametry/atributy nebo hodnoty parametrů jsou nesprávného typu

• 401 "Unauthorized" - partner není autorizován

• 403 "Forbidden" - přístup odepřen (např. uživatel/aplikace nemá povoleno používat zdroj)

• 404 "Not Found" - zdroj nebyl nalezen

• 405 "Method Not Allowed" - zadaná metoda není pro zdroj povolena

• 422 "Unprocessable Entity" - obchodní (sémantické) chyby. Žádost je správně formátovaná, ale nelze ji zpracovat (např. datum splatnosti platby je v minulosti). Chyby jsou uvedeny v těle odpovědi (viz níže)

• 429 Too many requests - partner překročil limit rychlosti (viz část Limit volání API výše)

• 500 Internal server error - na naší straně došlo k chybě

• 503 Service Unavailable - je plánované přerušení služby

Zpracování chyb

Kromě stavových kódů HTTP, které jsou hlavním indikátorem toho, že došlo k chybě, používáme také objekt errors k hlášení podrobnějších informací o chybách.

Příklad objektu errors:

{
    ...

    errors: [
        {
            "code": "ERR_100",
            "message": "Neplatné number smlouvy",
            "severity": "ERROR",
            "attribute": "partyAccount.accountNumber",          // volitelné
            "ticketId": "UAT1:AMS:20160516-091658.450:45e4" // volitelné
        },
        {
            "code": 352,
            "message": "Nedostatečné prostředky pro realizaci platebního příkazu",
            "severity": "WARN"
        },
        {
            "code": 523,
            "message": "Tento příkaz spustí operaci směny měny",
            "severity": "INFO"
        }
    ]
}

Atributy objektu chyby

Název atributu	Popis
code	jedinečný kód chyby
message	popis chyby čitelný pro člověka (nelokalizovaný)
severity	závažnost chyby (viz níže)
atribut	json cesta atributu požadavku, který způsobil chybu (volitelné)
ticketId	interní ID tiketu, používané pro zpětné sledování chyby

Existují 3 úrovně závažnosti chyby:

• ERROR - kritická chyba, provedení nelze pokračovat. To MUSÍ být také označeno příslušným stavovým kódem HTTP (např. 422 Unprocessable Entity)

• WARN - nekritická chyba, provedení lze pokračovat, ale je doporučeno další uživatelské zásahy (aby požadavek mohl pokračovat, partner MUSÍ specifikovat tento chybový kód v atributu požadavku override). To MŮŽE být také označeno příslušným stavovým kódem HTTP.

• INFO - pouze informace, provádění může pokračovat bez interakce uživatele.

Přehled chyb

Stavový kód	Kód	Vysvětlení	Zpráva
400	INVALID_REQUEST	Požadavek nebyl správně formátován (nesprávná syntaxe požadavku, příliš velká velikost atd.)	(Možné různé zprávy) např. Nepodporovaná kombinace stavu aplikace a stavu objednávky
404	OBJECT_NOT_FOUND	Požadovaný zdroj nebyl nalezen	(Možné různé zprávy) např. Zadaný objekt nebyl nalezen
422	NOT_ALLOWED	Operace není povolena (vnitřní důvod)	(Možné různé zprávy) např. Není povoleno (jiný důvod)
500	INTERNAL_SERVER_ERROR	Došlo k neočekávané situaci a není k dispozici žádná konkrétnější zpráva	(Možné různé zprávy) např. Selhalo zpracování zadaného JSON

Formáty

• date a time používají formátování ISO 8601, např.:

  • datum je vyjádřeno jako YYYY-mm-dd. Časové pásmo (místní) je přidáno v případě potřeby.
  • čas je vyjádřen jako Thh:mm:ss. Časové pásmo se přidává v případě potřeby. Akceptuje se také čas s libovolným počtem číslic představujících milisekundy (pokud jsou splněna kritéria formátu ISO 8601), ale vždy se vrací čas bez milisekund.
  • den v týdnu je vyjádřen číslem 1..7, přičemž 1 je pondělí.
  • týden č. 1 je týden, ve kterém je první čtvrtek v roce.

• telefonní čísla používají mezinárodní formát začínající znakem "+" a obsahující kód země (příklad platného čísla: +420739111222)

• formát čísel formát čísel je definován standardem JSON, např. desetinná místa jsou oddělena znakem .

• formát peněz používá formátování ISO 4217 (v menších jednotkách, např.: 12590 v menších jednotkách představuje 125,90 CZK/EUR)

Parametry přidané do návratových URL

• Během přesměrování zákazníka z front-endu Home Credit zpět na web partnera (na jednu z poskytnutých URL - approvedRedirectUrl, rejectedRedirectUrl) jsou přidány některé potenciálně užitečné informace o výsledku zákazníka ve front-endu Home Credit:

• applicationId (string) - Identifikátor žádosti HCO

• applicationStatus (enum) - Stav žádosti

• orderNumber (string) - Interní number objednávky e-shopuv rámci volání API Vytvořit žádost (je-li k dispozici)

• orderStatus (enum) - stav objednávky (je-li k dispozici)

• cashStatus (enum) - stav hotovostní půjčky (je-li k dispozici)

• withdrawal (boolean) - True, pokud je nákup zákazníka financován přímo z jeho již existujícího revolvingového úvěru; false, pokud je vytvářena nová smlouva (je-li k dispozici)

• downPayment (number) - Hodnota zálohy, obvykle nastavena na 0 (používá se formát menších jednotek - 100000 představuje 1000, ISO 4217)

• checkSum (string) - hashovaná zpráva

• např. http://youreshop.cz?&applicationId;=123e4567-e89b-12d3-a456-426655440000&applicationStatus;=CONFIRMED&orderNumber;=018884&orderStatus;=TO_SHIP&downPayment;=100000&checkSum;=443E150D3406F6A8DC62C1DB224AFDD84FA9907071BB1AD9B2C7701031793662191501B26AADF3A31361341EA176C80B23D8A9A5E5B5219538289945FE0C20A7

Průvodce migrací: API v1 → v3

Tento průvodce migrací se zaměřuje na změny v sekci Aplikační zdroje při přechodu z API verze 1 na verzi 3. Cílem je poskytnout přehled klíčových změn, které vyžadují úpravy implementace.

1. Přehled změn koncových bodů API

1.1 Struktura URL

• v1: /financing/v1/applications

• v3: /financing/v3/applications

Ověřování: Obě verze API používají stejný ověřovací koncový bod /authentication/v1/partner k získání bezpečnostního tokenu (viz část Přihlášení partnera).

1.2 Nové koncové body ve verzi v3

• GET /financing/v3/applications/{applicationId} - načtení podrobností aplikace

• PUT /financing/v3/applications/{applicationId}/cancel - zrušení aplikace

• PUT /financing/v3/applications/{applicationId}/orders/ship - označení objednávky jako odeslané

• PUT /financing/v3/applications/{applicationId}/orders/deliver - označení objednávky jako doručené

1.3 Změněné koncové body z v1

• Koncový bod zrušení byl upraven (viz část 2.4)

2. Změny datové struktury

2.1 ApplicationRequest - významné strukturální změny

V1 podporovala pouze fyzické osoby. V3 zavádí nové rozlišení typů zákazníků:

• Fyzická osoba (PERSON) - běžný zákazník

• Osoba samostatně výdělečně činná (ENTREPRENEUR) - živnostník

• Právnická osoba (LEGAL_ENTITY) - společnost, LLC, korporace atd.

Tato změna vyžaduje úpravy datové struktury v objektu customer, který nyní obsahuje pole type a konkrétní vnořené objekty v závislosti na typu zákazníka.

Struktura v1:

{
  "customer": {
    "firstName": "string",
    "lastName": "string",
    "fullName": "string",
    "email": "string",
    "phone": "string",
    "addresses": [
      {
        "name": "string",
        "city": "string",
        "streetAddress": "string",
        "streetNumber": "string",
        "zip": "string",
        "addressType": "PERMANENT|CONTACT|DELIVERY|BILLING"
      }
    ],
    "ipAddress": "string",
    "tin": "string",
    "fingerprintComponents": [
      {
        "key": "string",
        "value": "string"
      }
    ],
    "extraData": {
      "transactionsNumber": "number",
      "cashlessTransactionsNumber": "number",
      "transactionsSum": {
        "amount": "number",
        "currency": "string"
      },
      "cashlessTransactionsSum": {
        "amount": "number",
        "currency": "string"
      },
      "latestTransactionDate": "string (date)",
      "earliestTransactionDate": "string (date)",
      "pageTotalTime": "number",
      "pageReviewsTime": "number",
      "cartItemsRemoved": "number",
      "itemsViewed": "number"
    }
  },
  "order": {
    "number": "string",
    "variableSymbols": ["string"],
    "totalPrice": {
      "amount": "number",
      "currency": "string"
    },
    "totalVat": [
      {
        "amount": "number",
        "currency": "string",
        "vatRate": "number"
      }
    ],
    "addresses": [
      {
        "name": "string",
        "city": "string",
        "streetAddress": "string",
        "streetNumber": "string",
        "zip": "string",
        "addressType": "DELIVERY|BILLING"
      }
    ],
    "deliveryType": "DELIVERY_CARRIER|PERSONAL_BRANCH|PERSONAL_PARTNER|ONLINE",
    "reservationDate": "string (datetime)",
    "items": [
      {
        "code": "string",
        "ean": "string",
        "name": "string",
        "quantity": "number",
        "type": "PHYSICAL|DISCOUNT|SHIPPING_FEE|SALES_TAX|DIGITAL|GIFT_CARD|STORE_CREDIT|FEE|INSURANCE",
        "producer": "string",
        "unitPrice": {
          "amount": "number",
          "currency": "string"
        },
        "unitVat": {
          "amount": "number",
          "currency": "string",
          "vatRate": "number"
        },
        "totalPrice": {
          "amount": "number",
          "currency": "string"
        },
        "totalVat": {
          "amount": "number",
          "currency": "string",
          "vatRate": "number"
        },
        "image": {
          "filename": "string",
          "url": "string",
          "content": "string (base64)"
        }
      }
    ]
  },
  "type": "INSTALLMENT",
  "settingsInstallment": {
    "preferredMonths": "number",
    "preferredInstallment": {
      "amount": "number",
      "currency": "string"
    },
    "preferredDownPayment": {
      "amount": "number",
      "currency": "string"
    },
    "productCode": "string",
    "productSetCode": "string"
  },
  "merchantUrls": {
    "approvedRedirect": "string",
    "rejectedRedirect": "string",
    "notificationEndpoint": "string"
  },
  "precheckIds": ["string"]
}

Struktura v3:

{
  "customer": {
    "type": "PERSON|ENTREPRENEUR|LEGAL_ENTITY",
    "person": {
      "firstName": "string",
      "lastName": "string",
      "fullName": "string",
      "contacts": [
        {
          "type": "EMAIL|MOBILE|PHONE",
          "email": {
            "value": "string"
          },
          "mobile": {
            "countryCode": "string",
            "value": "string"
          },
          "phone": {
            "countryCode": "string",
            "value": "string"
          }
        }
      ],
      "addresses": [
        {
          "city": "string",
          "streetAddress": "string",
          "streetNumber": "string",
          "zip": "string",
          "flags": ["PERMANENT|CONTACT"]
        }
      ],
      "identificationNumber": "string",
      "ipAddress": "string",
      "fingerprintComponents": {
        "key": "string",
        "value": "string"
      }
    },
    "entrepreneur": {
      "businessName": "string",
      "businessIdentificationNumber": "string",
      "addresses": [
        {
          "city": "string",
          "streetAddress": "string",
          "streetNumber": "string",
          "zip": "string",
          "flags": ["PERMANENT|CONTACT"]
        }
      ],
      "ipAddress": "string",
      "fingerprintComponents": {
        "key": "string",
        "value": "string"
      }
    },
    "legalEntity": {
      "businessName": "string",
      "businessIdentificationNumber": "string",
      "addresses": [
        {
          "city": "string",
          "streetAddress": "string",
          "streetNumber": "string",
          "zip": "string",
          "flags": ["PERMANENT|CONTACT"]
        }
      ],
      "ipAddress": "string",
      "fingerprintComponents": {
        "key": "string",
        "value": "string"
      }
    }
  },
  "financedSubject": {
    "type": "ORDER",
    "order": {
      "type": "STANDARD|BROKERED",
      "number": "string",
      "variableSymbol": "string",
      "specificSymbol": "string",
      "totalPrice": {
        "value": "number",
        "currency": "string"
      },
      "preferredDownPayment": {
        "value": "number",
        "currency": "string"
      },
      "financings": [
        {
          "type": "INSTALLMENT",
          "amount": {
            "value": "number",
            "currency": "string"
          },
          "installment": {
            "preferredMonths": "number",
            "preferredInstallment": {
              "value": "number",
              "currency": "string"
            },
            "productCode": "string",
            "flags": ["BUYBACK"]
          }
        }
      ],
      "standard": {
        "deliveryType": "DELIVERY_CARRIER|PERSONAL_BRANCH|PERSONAL_PARTNER|ONLINE",
        "reservationDate": "string (datetime)",
        "items": [
          {
            "code": "string",
            "ean": "string",
            "name": "string",
            "quantity": "number",
            "type": "PHYSICAL|DISCOUNT|SHIPPING_FEE|SALES_TAX|DIGITAL|GIFT_CARD|STORE_CREDIT|FEE|INSURANCE",
            "producer": "string",
            "unitPrice": {
              "value": "number",
              "currency": "string"
            },
            "totalPrice": {
              "value": "number",
              "currency": "string"
            },
            "image": {
              "filename": "string",
              "url": "string",
              "content": "string (base64)"
            }
          }
        ]
      },
      "brokered": {
        "merchantOrders": [
          {
            "number": "string",
            "name": "string",
            "businessIdentificationNumber": "number",
            "url": "string",
            "logo": {
              "filename": "string",
              "url": "string",
              "obsah": "string (base64)"
            },
            "deliveryType": "DELIVERY_CARRIER|PERSONAL_BRANCH|PERSONAL_PARTNER|ONLINE",
            "reservationDate": "string (datetime)",
            "items": [
              {
                "code": "string",
                "ean": "string",
                "name": "string",
                "quantity": "number",
                "type": "PHYSICAL|DISCOUNT|SHIPPING_FEE|SALES_TAX|DIGITAL|GIFT_CARD|STORE_CREDIT|FEE|INSURANCE",
                "producer": "string",
                "unitPrice": {
                  "value": "number",
                  "currency": "string"
                },
                "totalPrice": {
                  "value": "number",
                  "currency": "string"
                },
                "image": {
                  "filename": "string",
                  "url": "string"
                }
              }
            ]
          }
        ]
      }
    }
  },
  "originationContext": {
    "channel": {
      "type": "ONLINE",
      "online": {
        "approvedRedirect": "string",
        "rejectedRedirect": "string",
        "notificationEndpoint": "string"
      }
    },
    "precheckIds": ["string"],
"sourceId": "string",
"extendedData": [
{
"key": "string",
"value": "string"
}
]
}
}

2.2 Zákazník - hlavní změny

Změna	v1	v3	Dopad
Struktura zákazníka	Přímé atributy (firstName, lastName, ...)	Typované struktury podle typu zákazníka (person, entrepreneur, legalEntity)	VYSOKÝ - Nutná refaktorizace všech volání
Požadavek zákazníka	required (s možností volitelných atributů)	required s type, ale data mohou být optional pro proces ONLINE	STŘEDNÍ
E-mail a telefon	Přímé atributy	Pole contacts[] s typem kontaktu	VYSOKÁ
Adresy	addresses[].addressType enum	Pole addresses[].flags[]	STŘEDNÍ
IP adresa	customer.ipAddress	customer.person.ipAddress / customer.entrepreneur.ipAddress / customer.legalEntity.ipAddress	NÍZKÁ
Identifikace osoby	Není v základní struktuře	customer.person.identificationNumber	NÍZKÁ - nové pole

Příklad migrace:

v1:

{
  "customer": {
    "firstName": "John",
    "lastName": "Newborn",
    "email": "john@example.com",
    "phone": "+420777123456",
    "addresses": [{
      "city": "Praha",
      "addressType": "PERMANENT"
    }]
  }
}

v3:

{
  "customer": {
    "type": "PERSON",
    "person": {
      "firstName": "John",
      "lastName": "Newborn",
      "contacts": [
        {
          "type": "EMAIL",
          "email": { "value": "john@example.com" }
        },
        {
          "type": "MOBILE",
          "mobile": { 
            "countryCode": "+420",
            "value": "777123456" 
          }
        }
      ],
      "addresses": [{
        "city": "Prague",
        "flags": ["PERMANENT"]
      }]
    }
  }
}

2.3 Objednávka - hlavní změny

Změna	v1	v3	Dopad
Umístění objednávky	Kořenová úroveň order	Vnořeno do financedSubject.order	VYSOKÝ
Typ objednávky	Neexistuje	type: STANDARD / BROKERED	VYSOKÝ - nová požadovaná struktura
Financování	type + settingsInstallment na kořenové úrovni	Pole financings[] v rámci order	VYSOKÝ - změna struktury financování
Položky	Vždy požadované	Požadované pouze pro STANDARD, volitelné pro BROKERED	STŘEDNÍ
MerchantUrls	Kořenová úroveň merchantUrls	Přesunuto do originationContext.channel.online	VYSOKÁ
Proměnné symboly	variableSymbols[] pole	variableSymbol string (jednoduchý) + specificSymbol	STŘEDNÍ

Příklad migrace:

v1:

{
  "order": {
    "number": "AA234",
    "variableSymbols": ["123456", "1234567"],
    "totalPrice": { "amount": 133000, "currency": "CZK" },
    "items": [...]
  },
  "type": "INSTALLMENT",
  "settingsInstallment": {
    "preferredMonths": 6,
    "productCode": "COCONL06"
  },
  "merchantUrls": {
    "approvedRedirect": "https://...",
    "rejectedRedirect": "https://...",
    "notificationEndpoint": "https://..."
  }
}

v3:

{
  "financedSubject": {
    "type": "ORDER",
    "order": {
      "type": "STANDARD",
      "number": "AA234",
      "variableSymbol": "123456",
      "specificSymbol": "1122334455",
      "totalPrice": { "value": 133000, "currency": "CZK" },
      "financings": [{
        "type": "INSTALLMENT",
        "installment": {
          "preferredMonths": 6,
          "productCode": "COCONL06"
        }
      }],
      "standard": {
        "deliveryType": "DELIVERY_CARRIER",
        "items": [...]
      }
    }
  },
  "originationContext": {
    "channel": {
      "type": "ONLINE",
      "online": {
        "approvedRedirect": "https://...",
        "rejectedRedirect": "https://...",
        "notificationEndpoint": "https://..."
      }
    }
  }
}

2.4 ApplicationResponse - hlavní změny

Atribut	v1	v3	Dopad
Stav aplikace	state + stateReason	Pouze status	VYSOKÝ - sloučení stavů
URL brány	gatewayRedirectUrl přímo	workflowSteps[] s objektem redirect	STŘEDNÍ
Stav objednávky	Přímo v odpovědi	Pouze přes GET /applications/{id}	STŘEDNÍ

Mapování stavu v1 → v3:

v1 state	v1 stateReason	v3 status
PROCESSING	PROCESSING_REDIRECT_NEEDED	CREATED
PROCESSING	PROCESSING_PREAPPROVED	PRESCORED
PROCESSING	PROCESSING_APPROVED	APPROVED
PROCESSING	PROCESSING_REVIEW	VERIFICATION
PROCESSING	PROCESSING_ALT_OFFER	ALTERNATIVE
PROCESSING	PROCESSING_SIGNED	APPROVED
PŘIPRAVENO	PŘIPRAVENO_K_ODESLÁNÍ	POTVRZENO + objednávka K_ODESLÁNÍ
PŘIPRAVENO	PŘIPRAVENO_ODESLÁNO	POTVRZENO + objednávka ODESLÁNO
PŘIPRAVENO	PŘIPRAVENO_DODÁVÁNO	POTVRZENO + objednávka KONTROLA_DODÁVKY
PŘIPRAVENO	PŘIPRAVENO_DORUČENO	POTVRZENO + objednávka DORUČENO
PŘIPRAVENO	PŘIPRAVENO_ZAPLACENO	POTVRZENO + objednávka ZAPLACENO
ZAMÍTNUTO	ZAMÍTNUTO	ZAMÍTNUTO
ZRUŠENO	ZRUŠENO_NEZAPLACENO	ZRUŠENO + objednávka ZRUŠENO
ZRUŠENO	ZRUŠENO_VRÁCENO	ZRUŠENO + objednávka UKONČENO

DŮLEŽITÉ: Ve verzi v3 je stav objednávky oddělen od stavu aplikace. Pro úplné informace použijte koncový bod GET /financing/v3/applications/{applicationId}.

2.5 Oznámení - změny struktury

Změna	v1	v3	Dopad
Struktura	Ploché atributy	Objekt notificationContent	STŘEDNÍ
Stav aplikace	stateReason	applicationStatus	VYSOKÝ - různé hodnoty
Stav objednávky	orderState	orderStatus	NÍZKÝ - přejmenování
Záloha	AmountOld (částka + měna)	Amount (hodnota + měna)	NÍZKÝ - přejmenování atributu

3. Změny v životním cyklu

3.1 Vytvoření aplikace

Dostupnost: Žádná změna v obou verzích
Metoda HTTP: POST
Dopad změny: KRITICKÝ

Klíčové změny:

1. Zcela odlišná struktura požadavku (viz sekce 2.1 - 2.3)
2. Změna struktury odpovědi
3. Duplicitní logika zůstává stejná (200 vs 201 vs 422)

3.2 Podrobnosti aplikace

Operace	v1	v3	Změna
Získat podrobnosti o žádosti	GET /financing/v1/applications/{applicationId}	GET /financing/v3/applications/{applicationId}	NOVÝ koncový bod ve v3 - doporučeno implementovat
Získat objednávku	GET /financing/v1/orders?applicationId={id}	Odstraněno	Podrobnosti objednávky nyní prostřednictvím podrobností aplikace

Dopad: STŘEDNÍ - změna způsobu získávání informací o objednávce

3.3 Označit zásilku/dodávku

Operace	v1	v3	Dopad
Označit jako odeslané	PUT /financing/v1/applications/{id}/order/send	PUT /financing/v3/applications/{id}/orders/ship	NÍZKÝ - změna URL
Označit jako doručené	PUT /financing/v1/applications/{id}/order/deliver	PUT /financing/v3/applications/{id}/orders/deliver	NÍZKÝ - změna URL

Klíčová změna: Ve verzi v3 neexistuje koncový bod pro send, pouze ship a deliver.

Dostupnost ve verzi v3:

• Odeslat: Pouze pro stavy CONFIRMED + TO_SHIP

• Doručit: Pouze pro stavy CONFIRMED + TO_SHIP

Odpověď ve verzi v3: Stav 204 (bez obsahu) namísto 200 s tělem odpovědi

3.4 Zrušení žádosti

Operace	v1	v3	Dopad
Zrušení žádosti	PUT /financing/v1/applications/{id}/cancel	PUT /financing/v3/applications/{id}/cancel	NÍZKÝ

Klíčové změny:

1. Mírně upravené tělo požadavku (v zásadě stejné hodnoty výčtu reason)
2. Odpověď ve v3: Stav 200 (namísto 200 s objektem Application)
3. Dostupnost ve v3 je rozšířena (lze zrušit více stavů)

Nové stavy dostupné pro zrušení ve v3:

• CREATED + IN_PROCESS

• PRESCORED + IN_PROCESS

• ALTERNATIVE + IN_PROCESS

• APPROVED + IN_PROCESS

• CONFIRMED + všechny kromě PAID

• CANCELLED + CANCELLED (idempotentní)

3.5 Úprava objednávky

v1: PUT /financing/v1/applications/{applicationId}/order
v3: Odstraněno

Dopad: VYSOKÝ - pokud byl tento koncový bod používán ke změně čísla objednávky nebo symbolu proměnné, je nutné najít alternativní řešení.

4. Nové funkce ve verzi v3

4.1 Podpora zprostředkovaných objednávek

Verze v3 zavádí možnost vytvářet "zprostředkované" objednávky pro obchodní vztahy mezi více stranami.

Příklad použití:

{
  "financedSubject": {
    "type": "ORDER",
    "order": {
      "type": "BROKERED",
      "brokered": {
        "merchantOrders": [
          {
            "name": "MALL",
            "number": "22222222",
            "items": [...]
          }
        ]
      }
    }
  }
}

4.2 Podpora podnikatelů a právnických osob

Ve verzi v3 lze nyní vytvářet aplikace pro:

• PERSON (fyzická osoba) - odpovídá verzi v1

• ENTREPRENEUR (podnikatel)

• LEGAL_ENTITY (právnická osoba)

4.3 Kroky pracovního postupu

Odpověď v3 obsahuje workflowSteps[] - strukturované informace o dalších krocích procesu.

4.4 Kontext vzniku

Nová struktura pro sledování zdroje žádosti:

• precheckIds - odkaz na předběžnou kontrolu

• sourceId - identifikátor kampaně

• extendedData - parametry UTM, informace o sledování

5. Změny formátu dat

5.1 Struktura částky

v1	v3
{ "amount": 13300, "currency": "CZK" }	{ "value": 13300, "currency": "CZK" }

Dopad: STŘEDNÍ - všude, kde se používá částka, musí být změněno amount → value.

5.2 Struktura telefonního čísla

v1	v3
"phone": "+420777123456"	"mobile": { "countryCode": "+420", "value": "777123456" }

Dopad: STŘEDNÍ - analýza telefonního čísla

5.3 Příznaky adresy vs. addressType

v1	v3
"addressType": "PERMANENT"	"flags": ["PERMANENT"]

Dopad: NÍZKÝ - změna z výčtu na pole

6. Změny parametrů přesměrování URL

Při přesměrování zákazníka zpět na partnerský web v3 přidává/upravuje parametry:

Parametr	v1	v3
stateReason	Ano	Odstraněno
applicationStatus	Ne	Nové
orderStatus	Ne	Nové
orderNumber	Ano	Ano (pokud je k dispozici)
applicationId	Ano	Ano
withdrawal	Ano	Ano (pokud je k dispozici)
downPayment	Ano	Ano
checkSum	Ano	Ano (checksum)

Dopad: STŘEDNÍ - je třeba aktualizovat analýzu parametrů přesměrování