# Node.js SDK (/cs/online/integration/node_sdk) `@tapayadot/checkout` je serverové TypeScript SDK pro Tapaya Checkout. Tato reference popisuje verzi **0.3.0**. | Údaj | Hodnota | | ------------------------ | ---------------------------------------------------------------------------------------- | | **Balíček** | `@tapayadot/checkout` | | **Verze** | 0.3.0 | | **Běhové prostředí** | Node.js 22.13.0 nebo novější, ES moduly, včetně deklarací TypeScriptu | | **Skript pro prohlížeč** | Tapaya.js 0.2.0, načítaný pro [Embedded Checkout](/online/integration/embedded_checkout) | | **Zdrojový kód** | [tapayadot/checkout-node](https://github.com/tapayadot/checkout-node) | npm pnpm Bun ```sh npm install @tapayadot/checkout ``` ```sh pnpm add @tapayadot/checkout ``` ```sh bun add @tapayadot/checkout ``` ```ts import { Tapaya } from '@tapayadot/checkout'; const tapaya = new Tapaya(); ``` Klient načítá `TAPAYA_SECRET_KEY` z prostředí serveru. Balíček obsahuje také loader pro prohlížeč a React hook pro [Embedded Checkout](/online/integration/embedded_checkout). Loader stahuje Tapaya.js **0.2.0** z `https://js.tapaya.com/checkout/0.2.0/checkout.js`; verze skriptu pro prohlížeč je na verzi tohoto balíčku nezávislá. Soubory `.env` nenačítá. Klíč i klienta držte pouze v kódu běžícím na serveru. [Průvodce Hosted Checkout](/online/integration/hosted_checkout) popisuje vytvoření objednávky, přesměrování zákazníka a ověření platby. ## Konfigurace [#configuration] ```ts const tapaya = new Tapaya(apiKey, { environment: 'sandbox', timeoutMs: 30_000, maxRetries: 2, }) ``` | Možnost | Výchozí hodnota | Popis | | ------------------------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `apiKey` (první argument) | `TAPAYA_SECRET_KEY` | Checkout klíč obchodníka, nebo v režimu platformy Secret key organizace. | | `environment` | `TAPAYA_ENVIRONMENT`, jinak `production` pro klíč `tapaya_live_` a v ostatních případech `sandbox` | `sandbox` (`https://api.sandbox.tapaya.com`) nebo `production` (`https://api.tapaya.com`). Ostrý klíč mimo produkci nebo testovací klíč v produkci vyvolá chybu už při vytvoření klienta. | | `baseUrl` | `TAPAYA_BASE_URL`, jinak URL zvolená podle `environment` | Přepíše URL API pro volání Hosted i Embedded Checkoutu. | | `timeoutMs` | `30000` | Časový limit každého pokusu v milisekundách. | | `merchantToken` | Žádná | Token obchodníka, odesílaný jako `X-Tapaya-Merchant-Token`. V režimu platformy je povinný. | | `maxRetries` | `2` | Počet opakování po chybě sítě, vypršení časového limitu, HTTP 429, 502, 503 nebo 504 nebo po vytvoření, které ještě probíhá. | | `fetch` | Globální `fetch` | Vlastní implementace `fetch`, například pro přidání proxy nebo instrumentace. | Chcete-li použít vlastní API endpoint, nastavte na svém serveru `TAPAYA_BASE_URL=https://api.example.com`. Explicitně zadaná `baseUrl` má přednost před `TAPAYA_BASE_URL`; obě přepisují volbu podle prostředí. Klient určí API klíč a URL API jednou, při svém vytvoření. Použijte klíč, který odpovídá zvolenému prostředí. URL API, návratové URL a URL hostovaného Checkoutu musí používat HTTPS, s výjimkou HTTP pro `localhost`, `127.0.0.1` a `[::1]` mimo `NODE_ENV=production`. SDK kontroluje aktuální `NODE_ENV` při každém ověření lokální URL s HTTP. `timeoutMs` musí být celé číslo od 1 do 2 147 483 647. `maxRetries` musí být nezáporné bezpečné celé číslo. Výchozí počet opakování umožňuje až tři pokusy na jedno volání, každý s vlastním časovým limitem. Každá metoda přijímá také `signal`, `timeoutMs` a `maxRetries` pro jednotlivý požadavek: ```ts const current = await tapaya.checkout.sessions.get(sessionId, { signal: request.signal, timeoutMs: 5_000, }) ``` Když je signál přerušen, metoda okamžitě skončí bez opakování a vrácený promise se odmítne s důvodem (reason) signálu. ## Relace Checkoutu [#checkout-sessions] ### Výběr obchodníka [#select-a-merchant] V režimu obchodníka určuje obchodníka jeho Checkout klíč. Použijte `new Tapaya()` bez `merchantToken`. V režimu platformy obsluhuje jeden Secret key organizace mnoho obchodníků. Každý požadavek potřebuje token obchodníka; žádný výchozí obchodník neexistuje a požadavek bez tokenu selže s chybou `TapayaAuthenticationError`. Tokeny zkopírujte z tabulky obchodníků v [nastavení Checkoutu](/online/integration/checkout_settings) a token dané objednávky předávejte jak při vytvoření, tak při načtení: ```ts const tapaya = new Tapaya(process.env.TAPAYA_SECRET_KEY) const session = await tapaya.checkout.sessions.create(params, { merchantToken: order.merchantToken, idempotencyKey: order.checkoutAttemptKey, }) const current = await tapaya.checkout.sessions.get(session.id, { merchantToken: order.merchantToken, }) ``` Výchozí token můžete nastavit také pomocí `new Tapaya(key, { merchantToken })`. Token platí pro volání Hosted i Embedded Checkoutu. Tapaya odmítá tokeny mimo organizaci daného klíče. S klíčem obchodníka je token volitelný a musí označovat obchodníka, kterému klíč patří. Viz [Autentizace Checkoutu](/online/integration/api_integration#authentication). ### Vytvoření relace [#create-a-session] `tapaya.checkout.sessions.create(params, options?)` vyžaduje `merchantOrderId`, `amount` a `currency`. `merchantOrderId` je vaše označení objednávky o délce 1 až 200 znaků. Objednávku lze zaplatit pouze jednou; nová relace pro nezaplacenou objednávku nahradí tu předchozí. Viz [Jedna platba na objednávku](/online/integration/api_integration#one-payment-per-order). `amount` je konečná celková částka včetně daně a dopravy, celé číslo od 1 do 2 147 483 647 v nejmenších jednotkách měny. `currency` je třípísmenný kód podle ISO 4217. Tapaya jej ukládá a vrací velkými písmeny. Volitelná pole: | Pole | Popis | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `locale` | Jazyk hostované stránky, například `en`. Výchozí hodnota je `en`. | | `successUrl`, `cancelUrl` | Návratové URL. Výchozí jsou URL z vašeho nastavení Checkoutu. | | `tax`, `shipping` | Daň a doprava zahrnuté v `amount`, v nejmenších jednotkách měny. | | `taxRate` | Jediná daňová sazba v procentních bodech, například `21`. | | `taxBreakdown` | Daň podle sazeb, `[{ taxRate, tax }]`, pro objednávky se smíšenými sazbami. Použijte místo `taxRate`: typy nepřipouštějí obojí současně. | | `items` | Produkty zobrazené na hostované stránce: `reference`, `name`, `description`, `imageUrl`, `quantity` a `unitAmount`. Položky slouží jen k zobrazení a nemění účtovanou částku. | | `customer` | Volitelné údaje `email`, `billingAddress` a `shippingAddress`. Odesílejte jen údaje, které sbíráte. | Před odesláním SDK kontroluje typy, povinná pole, celočíselné částky, formát měny a maximální délku e-mailu 254 znaků. Návratové URL musí být absolutní URL s HTTPS, s výjimkou pro lokální HTTP popsanou v části [Konfigurace](#configuration). Tapaya ověřuje obchodní pravidla, jako je formát e-mailu, limity adresy a kódy zemí, a problémy hlásí jako `TapayaInvalidRequestError`. Pravidla polí, součty daní a limity adresy zákazníka najdete v části [Relace Checkoutu](/online/integration/api_integration#checkout-sessions). ### Načtení relace [#get-a-session] `tapaya.checkout.sessions.get(id, options?)` vrací aktuální stav relace. ID musí být neprázdný řetězec o délce nejvýše 200 znaků; `.` a `..` jsou neplatné. SDK ID kóduje do URL. Vytvoření a načtení hostované relace vrací `HostedCheckoutSession`. Metody Embedded Checkoutu `prepare()`, `verify()` a `configuration()` popisuje stránka [Embedded Checkout](/online/integration/embedded_checkout). Pole hostované relace: | Pole | Popis | | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | `id` | ID relace, například `cs_Y7u2d`. | | `url` | Hostovaná platební stránka. Přesměrujte na ni beze změny. | | `merchantOrderId`, `amount`, `currency` | Údaje objednávky k porovnání s vaší uloženou objednávkou. | | `status` | `open`, `completed` nebo `expired`. Relace přijímají nové platby po dobu 30 minut. Mohou přibýt nové hodnoty. | | `paymentStatus` | `unpaid`, `successful`, `failed`, `cancelled` nebo `action_needed`. Mohou přibýt nové hodnoty. | | `paymentReference` | Token posledního pokusu o platbu, nebo `null` před prvním pokusem. | | `tax`, `shipping`, `taxRate`, `taxBreakdown` | Součty odeslané při vytvoření relace. Výchozí hodnoty jsou `0`, `0`, `null` a `[]`. | | `items` | Položky odeslané při vytvoření relace, nebo prázdné pole. | | `createdAt`, `expiresAt`, `completedAt` | Časová razítka ve formátu ISO 8601. `completedAt` je `null`, dokud platba neproběhne úspěšně. | Ošetřete neznámé hodnoty `status` a `paymentStatus`, například tak, že s nimi budete zacházet jako s dosud nezaplacenými. Platbu prokazuje pouze `paymentStatus: 'successful'`. Zamítnutá karta je výsledek platby, ne chyba. Relace zůstane `open` s `paymentStatus: 'failed'` a zákazník to může zkusit znovu. Zatímco Tapaya potvrzuje nejistý výsledek, relace zůstává `open` a `unpaid`. Webhooky zatím nejsou k dispozici; z úlohy pro odsouhlasení pravidelně volejte `get()`. ## Idempotence a opakování požadavků [#idempotency-and-retries] Každý požadavek na vytvoření odesílá `Idempotency-Key`. Explicitně zadaný klíč musí být neprázdný řetězec z tisknutelných znaků ASCII. Tapaya přijímá nejvýše 250 znaků. Pokud `idempotencyKey` vynecháte, SDK pro každé volání vygeneruje náhodný klíč. V rámci tohoto volání opakování klíč znovu používají, takže opakování nikdy nevytvoří druhou relaci. Aby bylo vytváření bezpečné i napříč samostatnými voláními a restarty procesu, uložte klíč spolu s objednávkou a předávejte jej pokaždé, když pro daný pokus vytváříte relaci, se stejnými parametry. Tapaya vrátí původní relaci, místo aby vytvořila novou. Nový klíč použijte pouze pro nový pokus o zaplacení, nikdy k opakování nejistého výsledku. Opakované vytvoření hostované relace vrátí stejnou relaci s jejími aktuálními hodnotami `status` a `paymentStatus`. Před vyřízením objednávky zavolejte `tapaya.checkout.sessions.get(session.id)` a stav znovu ověřte. Pro stejného obchodníka musí opakování hostovaných požadavků používat stejné tělo požadavku a stejný režim přihlašovacích údajů: Checkout klíč obchodníka, nebo Secret key organizace. Změna kteréhokoli z nich vrátí HTTP 409 s kódem `API-0025`. Přepnutí režimu přihlašovacích údajů vede ke konfliktu i při shodném těle, protože každý režim používá vlastní nastavení přesměrování. SDK opakuje obě metody po chybách sítě, vypršení časového limitu a HTTP 429, 502, 503 a 504. Opakuje také vytvoření, které selže s HTTP 409 `API-0024`. Opakování odesílají stejný klíč a tělo, takže vrátí původní relaci. SDK mezi pokusy čeká s exponenciálně se prodlužující prodlevou (exponential backoff) a náhodným rozptylem (jitter) a respektuje `Retry-After` až do 10 sekund. Když Tapaya požádá o delší čekání, SDK přestane opakovat a vyvolá chybu odpovídající danému stavu HTTP: `TapayaRateLimitError` pro 429, `TapayaServerError` pro 502, 503 nebo 504, nebo `TapayaConflictError` pro 409. Požadovanou prodlevu jako `retryAfterMs` zpřístupňuje pouze `TapayaRateLimitError`; ostatní chyby HTTP uchovávají hlavičku `Retry-After` v `headers`. Všechna opakování sdílejí limit `maxRetries`. Nastavením `maxRetries: 0` opakování vypnete. Nikdy nepřecházejte na nový klíč, abyste obešli nejistý výsledek. Původní požadavek už mohl vytvořit relaci; s novým klíčem a stejnou nezaplacenou objednávkou ji nová relace nahradí. ## Chyby [#errors] Třídy chyb SDK rozšiřují `TapayaError`. Přerušený požadavek se odmítne s důvodem uvedeným v signálu. | Chyba | Kdy | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `TapayaError` | Chybí API klíč nebo je konfigurace klienta neplatná; základní třída chyb SDK. | | `TapayaValidationError` | Parametry neprošly validací ještě před odesláním požadavku. | | `TapayaAuthenticationError` | HTTP 401: klíč chybí nebo je neplatný, v režimu platformy chybí token obchodníka, nebo token neodpovídá aktivnímu obchodníkovi. | | `TapayaInvalidRequestError` | HTTP 400 nebo 422: Tapaya parametry odmítla. | | `TapayaPermissionError` | HTTP 403. | | `TapayaNotFoundError` | HTTP 404: relace pro tohoto obchodníka neexistuje. | | `TapayaConflictError` | HTTP 409. `code` je `API-0025`, pokud byl idempotency key už použit s jinými parametry. Vytvoření relace pro objednávku, která je už zaplacená nebo u které probíhá platba, také vrátí 409. | | `TapayaRateLimitError` | HTTP 429 po vyčerpání opakování, nebo ihned, když je `Retry-After` delší než 10 sekund. `retryAfterMs` obsahuje požadovanou prodlevu, pokud ji Tapaya pošle. | | `TapayaServerError` | HTTP 5xx. Opakují se pouze 502, 503 a 504, a to jen tehdy, když opakování nejsou vypnutá a `Retry-After` nepřesahuje 10 sekund. Ostatní stavy 5xx selžou okamžitě. | | `TapayaApiError` | Základní třída výše uvedených chyb HTTP a jakéhokoli jiného chybového stavu HTTP. | | `TapayaConnectionError` | Požadavek selhal nebo se odpověď po vyčerpání opakování ztratila. Původní chyba je v `cause`. | | `TapayaTimeoutError` | `TapayaConnectionError` pro pokus, který překročil `timeoutMs`. | | `TapayaResponseError` | Tapaya vrátila odpověď, kterou SDK nedokázalo přečíst. | Chyby HTTP nesou `status`, chybový `code` Tapaya, `fieldErrors` (`{ field, message, code? }[]`), `headers` odpovědi a `requestId` z hlavičky `X-Request-Id`, pokud je přítomna. Backend tuto hlavičku v současnosti nenastavuje. Do požadavků na podporu uveďte ID relace nebo označení objednávky a čas požadavku, a také `requestId`, je-li k dispozici. `TapayaResponseError` nese rovněž `status`, `headers` a `requestId`. `TapayaValidationError` nese rovněž `fieldErrors`, kde `field` obsahuje cestu k parametru, například `customer.email`. ```ts import { TapayaConnectionError, TapayaError, TapayaValidationError } from '@tapayadot/checkout' try { const session = await tapaya.checkout.sessions.create(params, { idempotencyKey }) return Response.redirect(session.url, 303) } catch (error) { if (error instanceof TapayaValidationError) { console.error(error.fieldErrors) } else if (error instanceof TapayaConnectionError) { // The outcome is unknown. Retry later with the same idempotency key. } else if (error instanceof TapayaError) { console.error(error.message) } throw error } ``` ## Exportované typy [#exported-types] Balíček exportuje `TapayaEnvironment`, `TapayaOptions`, `RequestOptions`, `CreateSessionOptions`, `CreateCheckoutSessionParams`, `CheckoutSessions`, `CheckoutSession`, `CheckoutSessionStatus`, `CheckoutPaymentStatus`, `CheckoutItem`, `TaxBreakdownEntry`, `CheckoutCustomer`, `CheckoutContactAddress` a `TapayaFieldError`. `VERSION` obsahuje verzi SDK. Typy importujte jako pojmenované importy pomocí `import type`: ```ts import type { CheckoutSession, CreateCheckoutSessionParams } from '@tapayadot/checkout'; ``` ## Přechod z verze 0.2.x [#upgrade-from-02x] * Loader pro prohlížeč načítá Tapaya.js 0.2.0, který podporuje Apple Pay a Google Pay. Již načtený skript 0.1.x odmítne. Každou značku script, kterou spravujete, aktualizujte na `https://js.tapaya.com/checkout/0.2.0/checkout.js`. * `environment: 'production'` podporuje hostované i vložené platby. `configuration()` vrací `environment: 'production'` s klíči ostré platební brány. * Bez explicitně zadaného prostředí nebo `TAPAYA_ENVIRONMENT` volí klíč `tapaya_live_` produkci. Přihlašovací údaje, které neodpovídají zvolenému prostředí, selžou při vytváření klienta. `baseUrl` stále přepisuje URL API.