> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zabcik.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Doporučené postupy

> Produkční vzory pro integraci GoPay se GoPay SDK.

# Doporučené postupy

<Tip>
  Odpovídá běžné architektuře platebních backendů: **tajemství na serveru**, **celočíselné částky**, **idempotentní callbacky** a **jasná sémantika chyb**.
</Tip>

Doporučení pro odolné a udržovatelné platební integrace.

## 1. Přihlašovací údaje jen na serveru

Nikdy nevystavujte `clientSecret` ani backendové údaje ve frontend bundle.

* SDK inicializujte jen v backendových službách
* Údaje čtěte z proměnných prostředí nebo secret manageru
* Pravidelně rotujte přihlašovací údaje

## 2. Unikátní čísla objednávek

`order_number` je unikátní obchodní identifikátor.

* Vložte interní ID objednávky
* Vyhněte se náhodným hodnotám bez vazby na vaše systémy
* Udržujte stabilní mapování mezi objednávkou a ID platby GoPay

## 3. Částky v minor jednotkách

GoPay odesílá částky v minor jednotkách měny.

* `10000` minor jednotek CZK = `100,00 CZK`
* Vyhněte se float aritmetice pro částky
* Preferujte celočíselné výpočty

## 4. Asynchronní dokončení platby

Vytvoření platby a přesměrování je jen část toku.

* Uživatel může opustit checkout
* Návrat z prohlížeče může selhat
* Konečný stav ověřte na serveru

Doporučený postup:

1. Vytvořit platbu
2. Přesměrovat na `gw_url`
3. Zpracovat notifikaci na backendu
4. Ověřit stav pomocí `getPayment`
5. Označit objednávku jako zaplacenou až po terminálním úspěšném stavu

## 5. Rozlišení opakovatelných a neopakovatelných chyb

Používejte metadata `GoPayApiError`:

* `status` — třída HTTP
* `errors` — detaily polí
* `endpoint` — diagnostika a logy

Strategie:

* Opakovat přechodné chyby infrastruktury (timeouty, 5xx) s backoffem
* Neopakovat slepě validační/obchodní chyby (4xx)

## 6. Sdílet instance klienta

Dlouho žijící instance klienta na konfiguraci obchodníka místo instance na každý request.

* Lepší využití cache tokenů
* Méně zátěže na token endpoint
* Nižší latence běžných operací

## 7. Ladění timeoutů

`timeoutMs` podle sítě a infrastruktury:

* příliš nízké: zbytečná selhání při jitteru
* příliš vysoké: pomalá zpětná vazba a zaseknuté zdroje

Začněte výchozí hodnotou a upravte podle měření.

## 8. Vlastní transport pro observabilitu

Vlastní `HttpTransport` pro:

* trasovací ID požadavků
* metriky (latence, stavy)
* strukturované logy
* proxy / interní síť

Viz [Rozšiřitelnost](/cs/api-reference/extensibility).

## 9. Integrační testy obchodního toku

Testy knihovny pokrývají SDK izolovaně; vaše aplikace by měla testovat také:

* mapování objednávka → platba
* zpracování callbacku a idempotenci
* přechody stavů ve vašem datovém modelu

## 10. Aktualizace verze SDK

* Připněte `gopay-sdk` na explicitní semver rozsah (v produkci ne `*`).
* Při upgrade čtěte [`CHANGELOG.md`](https://unpkg.com/gopay-sdk@latest/CHANGELOG.md).
* Po upgrade spusťte integrační testy proti sandboxu.

Viz také [Kontrolní seznam pro produkci](/cs/production-checklist).