> For the complete documentation index, see [llms.txt](https://docs.ecommerce.seb.ee/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ecommerce.seb.ee/seb-docs-draft/seb-docs-public-et/integratsioon/api-kliendi-sdk/sdk-kasutamine/node.js-typescript.md).

# Node.js / TypeScript

Looge Node.js makseintegratsioone klientide, päringu DTO-de, API-kõnede, veakäsitluse ja webhookidega.

Kasutage seda juhendit, kui olete läbinud [Node.js kiirjuhend](/seb-docs-draft/seb-docs-public-et/integratsioon/api-kliendi-sdk/kiirstardid/node.js-typescript.md) ja soovite luua täieliku integratsiooni: koostada klient, vormistada päringuobjektid, kutsuda API-t, käsitleda tõrkeid ja töödelda **Veebikonksu (nimetatakse ka tagasikutse teavitusteks)**. Üks [täielik näide](#complete-example) koondab sammud kokku.

## Samm 1 — Looge klient

Kõik algab `DefaultEgwClientFactory`. Erinevalt Java ja PHP sujuvatest tehasest võtab Node.js-i tehas ühe konfiguratsiooniobjekti ega tuleta midagi baas-URL-ist — peate baas-URL-i, tokeni lõpp-punkti ja JWK lõpp-punkti ise selgesõnaliselt esitama:

```ts
import { DefaultEgwClientFactory } from "@tieto/egw-sdk";

const client = new DefaultEgwClientFactory().create({
  baseUri: new URL("https://sandbox.api.ecommerce.sebgroup.com"),
  authentication: {
    tokenEndpoint: new URL("https://api.ecommerce.sebgroup.com/auth/realms/participants-seb/protocol/openid-connect/token"),
    clientId: process.env.EGW_CLIENT_ID!,
    clientSecret: process.env.EGW_CLIENT_SECRET!,
  },
  jwkUri: new URL("https://checkout.ecommerce.sebgroup.com/api/keys/card-encryption.jwk"),
});
```

Tehase importimine registreerib vaikimisi adapterid (HTTP-klient, serialiseerija, krüpteerija, vaikne logija) automaatselt, seega on ülaltoodud koodijupp terviklik. Adapteri asendamiseks — tavapärane lahendus ajalõppude, puhverserverite või logimise jaoks — kutsuge `registerProvider({...})` *enne* `create()`; tehas teeb registreeritud pakkujatest loomisel hetktõmmise. Juurdepääsemiseks `registerProvider` on praegu vaja süvaviidet.

Looge klient käivitamisel üks kord ja kasutage seda korduvalt — OAuthi token salvestatakse vahemällu ja uuendatakse automaatselt. Node.js SDK-s ei ole ühtegi kuulajat, mida vabastada ([Samm 5](#step-5--process-webhooks)); `dispose()` on olemas sümmeetria huvides, kuid praeguses versioonis pole sellel midagi peatada.

## Samm 2 — Koostage päringu DTO-d

Päringud ja vastused on andmeedastusobjektid (DTO-d): muutumatud klassid koos `readonly` omadustega, mida loetakse otse (`response.paymentId`). Igal päringu DTO-l on kaasnev ehitajaklass, mis on saadaval nii nimega ekspordina (`AmountBuilder`) ja DTO staatilise aliase kujul (`new Amount.Builder()`).

**Klassikaline ehitaja.** Seadistusmeetodid on camelCase-kujul, nimetatud omaduse järgi ja tagastavad ehitaja; `build()` loob DTO:

```ts
import { Amount } from "@tieto/egw-sdk";

const amount = new Amount.Builder()
  .amount("100.00")
  .currency("EUR")
  .build();
```

**Pesastatud lambda-builder.** Iga omaduse jaoks, mis ise on DTO, pakub ehitaja `<property>Builder(...)` varianti, mis võtab sisseehitatud ehitaja üle funktsiooni — kirjeldage pesastatud objekti otse koha peal, selle asemel et seda eraldi ehitada. Funktsioon saab uue ehitaja ja peab selle tagastama:

```ts
import { CitPaymentChannel, InitiateCitPaymentRequest } from "@tieto/egw-sdk";

const request = new InitiateCitPaymentRequest.Builder()
  .channel(CitPaymentChannel.Browser)
  .instructedAmountBuilder((a) => a.amount("100.00").currency("EUR"))
  .orderNumber("ORD-1001")
  .participantId(process.env.EGW_PARTICIPANT_ID!)
  .shopAgreementId(process.env.EGW_SHOP_AGREEMENT_ID!)
  .shopRedirectUrl("https://shop.example.com/return")
  .build();
```

**Üksikelementide lisajad.** Massiiviomadused saavad täiendava `<property>Item(...)` meetodi, mis lisab ühe elemendi, nii et saate tsüklis üksusi lisada ilma massiivi ise haldamata:

```ts
import { Basket } from "@tieto/egw-sdk";

const basket = new Basket.Builder()
  .itemsItem(rodItem)
  .itemsItem(reelItem)
  .subtotalAmountBuilder((a) => a.amount("100.00").currency("EUR"))
  .build();
```

**Valideerimine.** Node.js SDK ei kontrolli kohustuslikke välju ehitamise ajal — erinevalt Javast ehitab ehitaja rõõmuga ka siis, kui kohustuslikud väljad on määramata, ning viga avaldub serveripoolse HTTP 400-na.

## Samm 3 — Kutsuge API-t

Toimingud on domeenide järgi rühmitatud ja neile pääseb kliendi juurdepääsumeetodite kaudu: `client.payments()`, `client.refunds()`, `client.tokens()`, `client.shop()`, ning kassaseansi rühmad `client.cardSessions()`, `client.bankSessions()`, `client.tokenSessions()`, `client.clickToPaySessions()`.

```ts
import { randomUUID } from "node:crypto";

const payments = client.payments();
```

Kõik toimingud on `async` ja võtavad esimese argumendina päringu ID stringi. Looge see iga kutse jaoks eraldi ja hoidke see koos oma tellimuse kirjetega — see on teie korrelatsiooniviide toe jaoks.

Päringu kehaga toimingud esinevad kahel kujul: `<operation>(...)` mis võtab koostatud DTO, ning `<operation>WithBuilder(...)` mis võtab päringu ehitaja üle funktsiooni:

```ts
// Valmistatud DTO-ga:
const created = await payments.initiateCitPayment(randomUUID(), request);

// Või ehitaja-funktsiooniga otse kohapeal (CancelReasoni enumit mõjutab
// avatud enumide serialiseerimisviga, nagu kõik enumid võrgus):
const cancelled = await payments.cancelPaymentWithBuilder(
  randomUUID(),
  created.paymentId!,
  (b) => b.reason(CancelReason.SuspectedFraud)
);
```

Seisundi lugemine ja püüdmine pärast kassaprotsessi lõppu:

```ts
const info = await payments.getPaymentInformation(randomUUID(), created.paymentId!);
console.log("Olek:", info.paymentStatus);

const captured = await payments.capturePaymentWithBuilder(
  randomUUID(),
  created.paymentId!,
  (b) => b.instructedAmountBuilder((a) => a.amount("100.00").currency("EUR"))
);
```

Iga kõne taga hangib SDK OAuth 2.0 juurdepääsumärgi ja salvestab selle vahemällu, seab `X-Request-ID` päise, serialiseerib päringu ja deserialiseerib vastuse tüpiseeritud vastuse DTO-sse.

## 4. samm — käsitlege vigu

Kõik SDK tõrked pärinevad klassist `ECommException`, mis laiendab `Error` ja seab `name` konkreetse klassi nimeks — `"AuthenticationException"`, `"ConnectionException"`, ja nii edasi — ning aluseks olev tõrge on väljal `cause`. Erandiklassid ei ole selles versioonis paketi juurest eksporditud, seega lähtuge `name` selle asemel et `instanceof`:

```ts
try {
  const created = await payments.initiateCitPayment(randomUUID(), request);
} catch (e) {
  if (e instanceof Error) {
    switch (e.name) {
      case "AuthenticationException":
        // Tokeni hankimine ebaõnnestus — kontrollige mandaate ja tokeni lõpp-punkti.
        break;
      case "ConnectionException":
        // Edastuse tõrge. SDK ei proovi kunagi uuesti: küsige makse olekut
        // koos meetodiga getPaymentInformation() enne olekut muutva kõne uuesti saatmist.
        break;
      default:
        // ECommException: API lükkas kutse tagasi (olekukood on
        // sõnumis, nt "Client error during initiateCitPayment: 400") või
        // vastust ei saanud töödelda.
        break;
    }
  }
}
```

API veadetailid ei ole selles versioonis veaga kaasas — lubage logija kaudu `registerProvider` ja seostage selle järgi `X-Request-ID`; vt [API vigade lugemine](/seb-docs-draft/seb-docs-public-et/integratsioon/api-kliendi-sdk/juhendid/vigade-kasitlemine.md#reading-api-errors). Täielik hierarhia on [Vigade käsitlemine](/seb-docs-draft/seb-docs-public-et/integratsioon/api-kliendi-sdk/juhendid/vigade-kasitlemine.md).

## 5. samm — töödelge webhook'e

Platvorm teavitab teid makse olekumuutustest, POSTides teie avaldatud lõpp-punkti. Erinevalt Java, PHP ja C# SDK-dest ei käivita Node.js SDK kuulajat — käivitate HTTP lõpp-punkti ise (või kasutate oma olemasolevat Expressi/Fastify rakendust uuesti) ja kasutate `parseWebhook()` sisu deserialiseerimiseks:

```ts
import { createServer } from "node:http";

interface PaymentNotification {
  type: string;
  paymentId: string;
  paymentStatus: string;
}

const notifications = client.notifications();

createServer((req, res) => {
  const chunks: Buffer[] = [];
  req.on("data", (c) => chunks.push(c));
  req.on("end", async () => {
    res.writeHead(200).end(); // kinnita esmalt, tööta pärast

    const n = notifications.parseWebhook<PaymentNotification>(Buffer.concat(chunks));
    if (n.type === "PAYMENT") {
      const info = await payments.getPaymentInformation(randomUUID(), n.paymentId);
      // Uuendage tellimust info.paymentStatus-i järgi — mitte ainult teavituse põhjal.
    }
  });
}).listen(8080);
```

`parseWebhook<T>()` on geneeriline — määrate sisu kuju, nagu `PaymentNotification` ülal. Teavituse sisu leping (kanoniline väljade loend ja sündmusetüübid): **\[TBC — link]**

Kohelge teavitust alati käivitajana, mitte tõena: praegune versioon ei kontrolli sissetulevate webhook-kutsete autentsust, seega pärige makseolek API kaudu uuesti enne tellimuse uuendamist. Avaldage lõpp-punkt TLS-i taga. Mõlemat punkti käsitletakse [Turvamehhanismid](/seb-docs-draft/seb-docs-public-et/integratsioon/api-kliendi-sdk/juhendid/turvamehhanismid.md#webhook-notifications).

## Täielik näide

Minimaalne otsast lõpuni voog — looge klient, avaldage webhook-lõpp-punkt, algatage makse ja kinnitage see, kui kassaprotsess lõpeb:

```ts
import { DefaultEgwClientFactory, CitPaymentChannel } from "@tieto/egw-sdk";
import { createServer } from "node:http";
import { randomUUID } from "node:crypto";

const client = new DefaultEgwClientFactory().create({
  baseUri: new URL("https://sandbox.api.ecommerce.sebgroup.com"),
  authentication: {
    tokenEndpoint: new URL("https://api.ecommerce.sebgroup.com/auth/realms/participants-seb/protocol/openid-connect/token"),
    clientId: process.env.EGW_CLIENT_ID!,
    clientSecret: process.env.EGW_CLIENT_SECRET!,
  },
  jwkUri: new URL("https://checkout.ecommerce.sebgroup.com/api/keys/card-encryption.jwk"),
});

const payments = client.payments();
const notifications = client.notifications();

createServer((req, res) => {
  const chunks: Buffer[] = [];
  req.on("data", (c) => chunks.push(c));
  req.on("end", () => {
    res.writeHead(200).end();
    const n = notifications.parseWebhook<{ paymentId: string; paymentStatus: string }>(
      Buffer.concat(chunks)
    );
    console.log(`Makse ${n.paymentId} → ${n.paymentStatus}`);
  });
}).listen(8080);

try {
  const created = await payments.initiateCitPaymentWithBuilder(randomUUID(), (b) =>
    b.channel(CitPaymentChannel.Browser) // mõjutatud avatud enumide serialiseerimisveast
     .instructedAmountBuilder((a) => a.amount("100.00").currency("EUR"))
     .orderNumber("ORD-1001")
     .participantId(process.env.EGW_PARTICIPANT_ID!)
     .shopAgreementId(process.env.EGW_SHOP_AGREEMENT_ID!)
     .shopRedirectUrl("https://shop.example.com/return")
     .description("Õngeritv, 2,7 m")
  );
  console.log("Makse loodud:", created.paymentId);

  // ... ostja viib kassaprotsessi lõpule; te saate tulemuse teada
  // webhook-lõpp-punkti kaudu ülal või getPaymentInformation()-i perioodiliselt pärides.

  const captured = await payments.capturePaymentWithBuilder(
    randomUUID(),
    created.paymentId!,
    (b) => b.instructedAmountBuilder((a) => a.amount("100.00").currency("EUR"))
  );
  console.log("Kinnitatud.");
} catch (e) {
  console.error("Maksevoog ebaõnnestus:", e instanceof Error ? e.message : e);
}
```

## Järgmised sammud

* [Vigade käsitlemine](/seb-docs-draft/seb-docs-public-et/integratsioon/api-kliendi-sdk/juhendid/vigade-kasitlemine.md) — kogu erindite hierarhia ja korduskatsete juhised.
* [Turvamehhanismid](/seb-docs-draft/seb-docs-public-et/integratsioon/api-kliendi-sdk/juhendid/turvamehhanismid.md) — kaardikrüptimine, veebikonksu turvalisus.
* [Node.js kiirjuhend](/seb-docs-draft/seb-docs-public-et/integratsioon/api-kliendi-sdk/kiirstardid/node.js-typescript.md) — paigaldus, mandaadid, teadaolevad piirangud.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.ecommerce.seb.ee/seb-docs-draft/seb-docs-public-et/integratsioon/api-kliendi-sdk/sdk-kasutamine/node.js-typescript.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.