# Správa obchodníkov (/sk/platform-api/merchant_management)
Spravujte obchodníkov vo svojej organizácii zo svojho backendu. Každé volanie používa váš Server Secret Token, preto ho uchovávajte na svojom serveri.
| Údaj | Hodnota |
| --------------- | ---------------------------------------------------------------------------------------------------------- |
| Základná URL | `https://api.sandbox.tapaya.com` pre sandbox, `https://api.tapaya.com` pre produkčné prostredie |
| Autentifikácia | Server Secret Token v hlavičke `Authorization`. Pozrite si [Autentifikáciu](/platform-api#authentication). |
| Sumy | Najmenšie jednotky meny: `2500` s `EUR` je 25,00 EUR. Relatívne poplatky v bázických bodoch: `100` je 1 %. |
| Súvisiaci návod | [Onboarding obchodníkov](/platform-api/merchant_onboarding) |
## Všetky operácie [#all-operations]
| Operácia | Slúži na |
| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| [Načítanie uloženého onboardingu](#read-a-saved-onboarding) | Pokračovanie vo formulári onboardingu obchodníka tam, kde skončil. |
| [Uloženie výberu kanálov](#save-channel-selections) | Uloženie platobných kanálov, ktoré obchodník vybral, bez odoslania. |
| [Výpis členov](#list-members) | Zistenie, kto už má prístup k obchodníkovi. |
| [Výpis terminálov](#list-terminals) | Zobrazenie terminálov obchodníka a ich zariadení. |
| [Výpis e-mailových pozvánok](#list-email-invites) | Sledovanie jednorazových pozvánok odoslaných známym príjemcom. |
| [Výpis opakovane použiteľných odkazov](#list-reusable-links) | Sledovanie odkazov kampaní a toho, či sú pozastavené. |
| [Vytvorenie opakovane použiteľného odkazu](#create-a-reusable-link) | Spustenie kampane, cez ktorú sa môže zaregistrovať mnoho obchodníkov. |
| [Zmena expirácie pozvánky](#change-an-invites-expiry) | Predĺženie alebo skrátenie pozvánky vrátane už expirovanej. |
| [Pozastavenie alebo obnovenie opakovane použiteľného odkazu](#pause-or-resume-a-reusable-link) | Dočasné zastavenie nových registrácií bez zrušenia odkazu. |
| [Výpis cenových sád](#list-pricing-sets) | Nájdenie cenových sád, z ktorých môže vaša organizácia vytvárať profily. |
| [Výpis cenových profilov](#list-commission-profiles) | Výber profilu, ktorý priradíte pozvánke. |
| [Vytvorenie cenového profilu](#create-a-commission-profile) | Ponuka cenníka vytvoreného z cenovej sady obchodníkom. |
| [Úprava cenového profilu](#update-a-commission-profile) | Premenovanie profilu alebo zmena jeho sadzieb. |
| [Odstránenie cenového profilu](#delete-a-commission-profile) | Odstránenie profilu, ktorý už neponúkate. |
| [Nastavenie predvoleného profilu](#set-the-default-profile) | Výber profilu, ktorý použijú pozvánky bez uvedeného profilu. |
| [Načítanie cien obchodníka](#read-merchant-pricing) | Zobrazenie sadzieb, s ktorými sa obchodník zaregistroval. |
## Rozpracovaný onboarding [#onboarding-drafts]
**Slúži na** pokračovanie vo formulári onboardingu obchodníka so všetkým, čo doteraz uložil.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/onboarding' \
-H 'Authorization: REPLACE_ME'
```
**Dobré vedieť:**
* Toto je jediné volanie, ktoré vracia celý uložený onboarding; volania profilu a procesora vracajú iba jeho časti.
* `pricingConstraints` uvádza, čo si obchodník môže vybrať, nie sadzobníky poplatkov.
**Vracia:**
| Pole | Popis |
| ---------------------- | ------------------------------------------------------------------------------------------ |
| `identity` | Identifikačné údaje obchodníka. |
| `address` | Adresa obchodníka. |
| `business` | Obchodné údaje spoločné pre oba kanály. |
| `kyb` | Bankové účty, primárny účet, stakeholderi spoločnosti alebo fyzická osoba a ich dokumenty. |
| `capability` | Vybraná capability. |
| `terminal` | Uložené údaje kanála v predajni. |
| `online` | Uložené údaje online kanála. |
| `processors` | Stav u jednotlivých spracovateľov platieb. |
| `commissionProfileIds` | Cenové profily priradené obchodníkovi. |
| `pricingConstraints` | Povolené meny zúčtovania a MCC. |
**Slúži na** uloženie platobných kanálov, ktoré obchodník vybral vo vašom formulári, ešte pred dokončením onboardingu.
```bash
curl -X POST 'https://api.sandbox.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/channel' \
-H 'Authorization: REPLACE_ME' \
-H 'Content-Type: application/json' \
-d '{
"capability": 2,
"terminal": {
"mcc": "5411",
"statementDescriptor": "ACME STORE",
"productDescription": "Groceries",
"averageItemValue": 2500,
"expectedMonthlyTurnover": 500000,
"numberOfTerminals": 1
}
}'
```
**Dobré vedieť:**
* Funguje iba pre obchodníka, ktorý už má uložený rozpracovaný onboarding a profil.
* Aktualizuje rozpracované údaje a vracia `200`. Neodosiela onboarding ani neregistruje účet u procesora.
* Posielajte iba sekcie kanálov, ktoré obchodník vybral.
**Parametre:**
| Pole | Popis |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| `capability` | Vybrané kanály. Rovnaké hodnoty ako v [Onboardingu obchodníkov](/platform-api/merchant_onboarding#request-online-payment-capabilities). |
| `terminal` | Údaje kanála v predajni s rovnakými poľami ako v Onboardingu obchodníkov. |
| `online` | Údaje online kanála s rovnakými poľami ako v Onboardingu obchodníkov. |
## Členovia a terminály [#members-and-terminals]
**Slúži na** zistenie, kto už má prístup k obchodníkovi.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/members' \
-H 'Authorization: REPLACE_ME'
```
**Dobré vedieť:**
* Vracia pole aktuálnych členov.
* Nevybavené pozvánky nie sú zahrnuté; vypisujú sa samostatne.
**Vracia:** pre každého člena:
| Pole | Popis |
| ----------- | ------------------------------------- |
| `userId` | ID používateľa člena. |
| `firstName` | Krstné meno. |
| `lastName` | Priezvisko. |
| `email` | E-mailová adresa. |
| `joinedAt` | Kedy sa člen pripojil k obchodníkovi. |
**Slúži na** zobrazenie terminálov obchodníka a zariadení, ktoré sú k nim priradené.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/terminal?page=1&pageSize=25' \
-H 'Authorization: REPLACE_ME'
```
**Dobré vedieť:**
* Vracia terminály, nie aktívne lokality; lokality majú vlastný výpis.
* Odpoveď obsahuje `items` a `totalCount`. Každá položka obsahuje ID terminálu a lokality, označenie a údaje o zariadení.
* `terminalType` a `deviceIdentifier` opisujú aktuálne priradené zariadenie, nie zariadenie, ktoré prijalo skoršiu platbu.
**Parametre:**
| Pole | Popis |
| --------------- | ------------------------------ |
| `page` | Číslo strany. |
| `pageSize` | Počet riadkov na stranu. |
| `sortBy` | Pole, podľa ktorého sa triedi. |
| `sortDirection` | Smer triedenia. |
## Registračné pozvánky [#registration-invites]
Pre známeho príjemcu použite [e-mailovú pozvánku](/platform-api/merchant_onboarding#invite-a-merchant-to-complete-hosted-onboarding), pre kampaň opakovane použiteľný odkaz. Oboje umožňuje obmedziť kanály a priradiť cenové profily.
**Slúži na** sledovanie jednorazových pozvánok, ktoré ste odoslali.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/merchant/invites' \
-H 'Authorization: REPLACE_ME'
```
**Dobré vedieť:**
* Každá pozvánka uvádza e-mail príjemcu, URL, `capability` a `commissionProfileIds`.
* Pozvánky obsahujú aj `commissionProfileId`, podobu `commissionProfileIds` pre jeden profil.
**Slúži na** sledovanie odkazov vašich kampaní a zistenie, ktoré sú pozastavené.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/merchant/reusable-registration-invites' \
-H 'Authorization: REPLACE_ME'
```
**Dobré vedieť:**
* Každý odkaz uvádza svoju `capability`, priradené profily a `pausedAt`.
* `pausedAt` je `null`, kým odkaz nie je pozastavený.
* Pozastavený odkaz, ktorý neexpiroval ani nebol zrušený, stále zodpovedá `isActive=true`. Na ich rozlíšenie kontrolujte `pausedAt`.
**Slúži na** spustenie kampane, cez ktorú sa môže zaregistrovať mnoho obchodníkov.
```bash
curl -X POST 'https://api.sandbox.tapaya.com/integrator/merchant/reusable-registration-invites' \
-H 'Authorization: REPLACE_ME' \
-H 'Content-Type: application/json' \
-d '{
"name": "Partner onboarding",
"expiresAt": "2030-12-31T00:00:00Z",
"capability": 2
}'
```
**Dobré vedieť:**
* `capability` obmedzuje, ktoré kanály si obchodníci môžu vybrať. Neudeľuje schválenie procesora.
* Ak vynecháte polia profilov, priradí sa predvolený profil organizácie.
* `commissionProfileId` je pre jeden profil stále akceptované. Namiesto neho používajte `commissionProfileIds` a nikdy neposielajte obe polia.
**Parametre:**
| Pole | Popis |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | Názov kampane. |
| `expiresAt` | Časová pečiatka ISO 8601 UTC aspoň jeden deň v budúcnosti. Maximum nie je stanovené. |
| `capability` | Voliteľné. Rovnaké hodnoty ako pri [e-mailových pozvánkach](/platform-api/merchant_onboarding#invite-a-merchant-to-complete-hosted-onboarding). |
| `commissionProfileIds` | Voliteľné. Rovnaké pravidlá ako pri e-mailových pozvánkach. |
**Slúži na** predĺženie alebo skrátenie pozvánky vrátane takej, ktorá už expirovala.
```bash
curl -X PUT 'https://api.sandbox.tapaya.com/integrator/merchant/reusable-registration-invites/018f8f2a-4c2f-7d3b-8a2e-3f7b2c8d5e4f/expires-at' \
-H 'Authorization: REPLACE_ME' \
-H 'Content-Type: application/json' \
-d '{"expiresAt": "2031-01-31T00:00:00Z"}'
```
**Dobré vedieť:**
* Pre e-mailovú pozvánku zavolajte `PUT /integrator/merchant/invites/{inviteId}/expires-at` s rovnakým telom.
* Vracia `204`.
* Zrušené pozvánky a použité e-mailové pozvánky nemožno predĺžiť.
**Parametre:**
| Pole | Popis |
| ----------- | ------------------------------------------------------------------------------------ |
| `expiresAt` | Časová pečiatka ISO 8601 UTC aspoň jeden deň v budúcnosti. Maximum nie je stanovené. |
**Slúži na** dočasné zastavenie nových registrácií bez zrušenia odkazu.
```bash
curl -X PUT 'https://api.sandbox.tapaya.com/integrator/merchant/reusable-registration-invites/018f8f2a-4c2f-7d3b-8a2e-3f7b2c8d5e4f/pause' \
-H 'Authorization: REPLACE_ME'
```
**Dobré vedieť:**
* Ak chcete znova prijímať registrácie, zavolajte na rovnakom odkaze `.../resume`. Obnovenie nepredlžuje expiráciu.
* Obe volania vracajú `204` a sú idempotentné.
* Otvorenie pozastaveného odkazu vracia `410`.
## Cenové profily [#commission-profiles]
Cenový profil je cenník, ktorý ponúkate obchodníkom. Vytvorte ho z cenovej sady, pre ktorú má vaša organizácia oprávnenie.
**Slúži na** nájdenie cenových sád, z ktorých môžete vytvárať cenové profily.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/organization/pricing-sets?pricingType=instore' \
-H 'Authorization: REPLACE_ME'
```
**Dobré vedieť:**
* Každá sada obsahuje zmluvné sadzobníky obchodníka a integrátora.
* Pri vytváraní profilu použite vrátené `pricingSetId`.
**Parametre:**
| Pole | Popis |
| ------------- | ------------------------------------ |
| `pricingType` | Voliteľné. `online` alebo `instore`. |
**Slúži na** výber profilu, ktorý priradíte pozvánke.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/organization/commission-profiles?pricingType=online' \
-H 'Authorization: REPLACE_ME'
```
**Dobré vedieť:**
* Vracia iba povolené a úplné profily vašej organizácie.
* Každý profil pokrýva jeden typ cien.
* Ak plánujete profil upraviť, uchovajte si jeho `revision`.
**Parametre:**
| Pole | Popis |
| ------------- | ------------------------------------ |
| `pricingType` | Voliteľné. `online` alebo `instore`. |
**Slúži na** ponuku cenníka vytvoreného z cenovej sady obchodníkom.
```bash
curl -X POST 'https://api.sandbox.tapaya.com/integrator/organization/commission-profiles' \
-H 'Authorization: REPLACE_ME' \
-H 'Content-Type: application/json' \
-d '{
"name": "Standard profile",
"pricingModel": 1,
"cardTypes": [
{"region": 1, "holderType": 1, "scheme": 1, "enabled": true, "referralFeeRelative": 0, "referralFeeAbsolute": 0}
],
"pricings": [
{"currency": "eur", "pricingSetId": "018f8f2a-5d3a-7e4c-9b3f-4a8c3d9e6f5a"}
]
}'
```
**Dobré vedieť:**
* Profil pokrýva jeden typ cien, ktorý určujú jeho cenové sady.
* Náklady integrátora a podiely na marži pochádzajú z cenovej sady; vy nastavujete iba sadzby obchodníka.
* `region` je `1` pre domáce alebo `2` pre zahraničné, `holderType` je `1` pre spotrebiteľa alebo `2` pre firmu a `scheme` je `1` pre Visa alebo `2` pre Mastercard.
**Parametre:**
| Pole | Popis |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | Názov profilu. |
| `pricingModel` | `1` pre MDR alebo `2` pre IC++. |
| `cardTypes` | Každá kombinácia regiónu, typu držiteľa karty a schémy, ktorú profil prijíma, s jej odmenami za odporúčanie. |
| `pricings` | Mena a `pricingSetId` pre každú menu, ktorú ponúkate. |
| `merchantPricingOverrides` | Voliteľné. Položky s `holderCategory`, `regionSegment`, `relative` a `absolute`. Vynechané kombinácie si zachovajú sadzby cenovej sady. |
**Slúži na** premenovanie profilu alebo zmenu jeho sadzieb.
```bash
curl -X PUT 'https://api.sandbox.tapaya.com/integrator/organization/commission-profiles/018f8f2a-7a1c-7b2d-8e3f-6c1d2e3f4a5b' \
-H 'Authorization: REPLACE_ME' \
-H 'Content-Type: application/json' \
-d '{
"name": "Standard profile 2027",
"pricingModel": 1,
"cardTypes": [
{"region": 1, "holderType": 1, "scheme": 1, "enabled": true, "referralFeeRelative": 0, "referralFeeAbsolute": 0}
],
"expectedRevision": 3
}'
```
**Dobré vedieť:**
* Naposledy načítané `revision` pošlite ako `expectedRevision`. Zastaraná revízia vracia `409`.
* Vynechaním `pricings` zachováte uložené sadzby.
* Profil, ktorý je priradený obchodníkom alebo nie je upraviteľný, dovoľuje iba zmenu názvu.
**Parametre:**
| Pole | Popis |
| ------------------ | ----------------------------------------------- |
| `name` | Povinné. Názov profilu. |
| `pricingModel` | Povinné. `1` pre MDR alebo `2` pre IC++. |
| `cardTypes` | Povinné. Rovnaké ako pri vytváraní. |
| `pricings` | Voliteľné. Rovnaké ako pri vytváraní. |
| `expectedRevision` | `revision` profilu v čase, keď ste ho načítali. |
**Slúži na** odstránenie profilu, ktorý už neponúkate.
```bash
curl -X DELETE 'https://api.sandbox.tapaya.com/integrator/organization/commission-profiles/018f8f2a-7a1c-7b2d-8e3f-6c1d2e3f4a5b' \
-H 'Authorization: REPLACE_ME'
```
**Dobré vedieť:**
* Predvolený profil nemožno odstrániť. Najskôr nastavte ako predvolený iný profil.
* Profil priradený obchodníkom nemožno odstrániť. Oba prípady vracajú `400`.
**Slúži na** výber profilu, ktorý použijú pozvánky bez uvedeného profilu.
```bash
curl -X PUT 'https://api.sandbox.tapaya.com/integrator/organization/commission-profiles/018f8f2a-7a1c-7b2d-8e3f-6c1d2e3f4a5b/default' \
-H 'Authorization: REPLACE_ME'
```
**Dobré vedieť:**
* Vaša organizácia má jeden predvolený profil.
* Predvolený profil nemožno odstrániť.
## Ceny obchodníka [#merchant-pricing]
**Slúži na** zobrazenie sadzieb, s ktorými sa obchodník zaregistroval, pre platby v predajni aj online platby.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/pricing' \
-H 'Authorization: REPLACE_ME'
```
**Dobré vedieť:**
* Kanál bez uložených cien je `null`. Obchodník bez akéhokoľvek uloženého cenníka vracia `404`.
* Vracia zmluvné sadzby, nie základné sadzobníky poskytovateľa platieb. Sadzby čítajte z `cells`; zložky `commission` nie sú realizované provízie.
* Neznámy model alebo náklad integrátora je `null`, nie nula.
* Podiely na tržbách delia rozdeľovanú maržu, nie celú sumu platby.
**Vracia:**
| Pole | Popis |
| ------------------------------------- | --------------------------------------------------------------- |
| `instore` | Ceny pre platby v predajni alebo `null`. |
| `online` | Ceny pre online platby alebo `null`. |
| `currency` | Mena cien. |
| `pricingModel` | Cenový model obchodníka. |
| `integratorPricingModel` | Cenový model integrátora, nezávislý od modelu obchodníka. |
| `priceListId` | Uložený cenník obchodníka, ak je dostupný. |
| `pricingSetVersionId` | Verzia zdrojovej cenovej sady, ak je dostupná. |
| `pricingSetName` | Názov zdrojovej cenovej sady, ak je dostupný. |
| `cells` | Sadzby podľa kategórie držiteľa karty a regiónu. |
| `cells[].discountBps` | Konečná relatívna sadzba obchodníka v bázických bodoch. |
| `cells[].transactionFeeMinor` | Konečný pevný poplatok obchodníka v najmenších jednotkách meny. |
| `cells[].integratorCostRelativeBps` | Zmluvný relatívny náklad integrátora v bázických bodoch. |
| `cells[].integratorCostAbsoluteMinor` | Zmluvný pevný náklad integrátora v najmenších jednotkách meny. |
| `cells[].revenueShareTapayaBps` | Podiel Tapaya na rozdeľovanej marži v bázických bodoch. |
| `cells[].revenueShareIntegratorBps` | Váš podiel na rozdeľovanej marži v bázických bodoch. |
## Chyby [#errors]
Každá operácia pri neúspešnej požiadavke odpovedá týmito stavovými kódmi.
| Kód | Popis |
| ----- | --------------------------------------------------------------------------------------------------------------------------- |
| `400` | Neplatné údaje kanálov, výber profilov, filtre alebo expirácia; prípadne pokus odstrániť predvolený alebo priradený profil. |
| `401` | Server Secret Token chýba alebo je neplatný. |
| `404` | Zdroj nie je dostupný vašej organizácii alebo neexistuje uložený onboarding či ceny. |
| `409` | Zastaraná revízia profilu, konfliktný stav onboardingu alebo použitá či zrušená pozvánka. |