# Správa obchodníků (/cs/platform-api/merchant_management)
Spravujte obchodníky ve své organizaci ze svého backendu. Každé volání používá váš Server Secret Token, proto jej uchovávejte na serveru.
| Údaj | Hodnota |
| -------------------- | --------------------------------------------------------------------------------------------------------- |
| Základní URL | `https://api.sandbox.tapaya.com` pro sandbox, `https://api.tapaya.com` pro produkci |
| Autentizace | Server Secret Token v hlavičce `Authorization`. Viz [Autentizace](/platform-api#authentication). |
| Částky | Nejmenší jednotky měny: `2500` s `EUR` je 25,00 EUR. Relativní poplatky v bazických bodech: `100` je 1 %. |
| Související průvodce | [Onboarding obchodníků](/platform-api/merchant_onboarding) |
## Všechny operace [#all-operations]
| Operace | K čemu slouží |
| ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| [Načtení uloženého onboardingu](#read-a-saved-onboarding) | Pokračování ve formuláři onboardingu obchodníka tam, kde skončil. |
| [Uložení výběru kanálů](#save-channel-selections) | Uložení platebních kanálů, které obchodník zvolil, bez odeslání. |
| [Výpis členů](#list-members) | Zjištění, kdo už má k obchodníkovi přístup. |
| [Výpis terminálů](#list-terminals) | Zobrazení terminálů obchodníka a jejich zařízení. |
| [Výpis e-mailových pozvánek](#list-email-invites) | Sledování jednorázových pozvánek odeslaných známým příjemcům. |
| [Výpis opakovaně použitelných odkazů](#list-reusable-links) | Sledování odkazů kampaní a toho, zda jsou pozastavené. |
| [Vytvoření opakovaně použitelného odkazu](#create-a-reusable-link) | Spuštění kampaně, přes kterou se může zaregistrovat mnoho obchodníků. |
| [Změna expirace pozvánky](#change-an-invites-expiry) | Prodloužení nebo zkrácení pozvánky, včetně již expirované. |
| [Pozastavení nebo obnovení opakovaně použitelného odkazu](#pause-or-resume-a-reusable-link) | Dočasné zastavení nových registrací bez zrušení odkazu. |
| [Výpis cenových sad](#list-pricing-sets) | Nalezení cenových sad, ze kterých může vaše organizace sestavovat profily. |
| [Výpis cenových profilů](#list-commission-profiles) | Výběr profilu, který přiřadíte pozvánce. |
| [Vytvoření cenového profilu](#create-a-commission-profile) | Nabídka ceníku sestaveného z cenové sady obchodníkům. |
| [Úprava cenového profilu](#update-a-commission-profile) | Přejmenování profilu nebo změna jeho sazeb. |
| [Odstranění cenového profilu](#delete-a-commission-profile) | Odstranění profilu, který už nenabízíte. |
| [Nastavení výchozího profilu](#set-the-default-profile) | Výběr profilu, který použijí pozvánky, jež žádný profil neuvádějí. |
| [Načtení cen obchodníka](#read-merchant-pricing) | Zobrazení sazeb, se kterými se obchodník zaregistroval. |
## Rozpracovaný onboarding [#onboarding-drafts]
**Slouží k** pokračování ve formuláři onboardingu obchodníka se vším, co dosud uložil.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/onboarding' \
-H 'Authorization: REPLACE_ME'
```
**Dobré vědět:**
* Jedině toto volání vrací celý uložený onboarding; volání profilu a procesoru vracejí jen jeho části.
* `pricingConstraints` uvádí, co si obchodník smí zvolit, nikoli sazebníky poplatků.
**Vrací:**
| Pole | Popis |
| ---------------------- | --------------------------------------------------------------------------------------------- |
| `identity` | Identifikační údaje obchodníka. |
| `address` | Adresa obchodníka. |
| `business` | Obchodní údaje společné pro oba kanály. |
| `kyb` | Bankovní účty, primární účet, stakeholdeři společnosti nebo fyzická osoba a jejich dokumenty. |
| `capability` | Vybraná capability. |
| `terminal` | Uložené údaje kanálu plateb v prodejně. |
| `online` | Uložené údaje online kanálu. |
| `processors` | Stav u jednotlivých zpracovatelů plateb. |
| `commissionProfileIds` | Cenové profily přiřazené obchodníkovi. |
| `pricingConstraints` | Povolené měny zúčtování a MCC. |
**Slouží k** uložení platebních kanálů, které obchodník zvolil ve vašem formuláři, ještě před 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é vědět:**
* Funguje pouze u obchodníka, jehož rozpracovaný onboarding a profil jsou již uložené.
* Aktualizuje rozpracovaná data a vrací `200`. Neodesílá onboarding ani neregistruje účet u procesoru.
* Posílejte pouze sekce kanálů, které obchodník vybral.
**Parametry:**
| Pole | Popis |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| `capability` | Vybrané kanály. Stejné hodnoty jako v [Onboardingu obchodníků](/platform-api/merchant_onboarding#request-online-payment-capabilities). |
| `terminal` | Údaje kanálu plateb v prodejně se stejnými poli jako v Onboardingu obchodníků. |
| `online` | Údaje online kanálu se stejnými poli jako v Onboardingu obchodníků. |
## Členové a terminály [#members-and-terminals]
**Slouží ke** zjištění, kdo už má k obchodníkovi přístup.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/members' \
-H 'Authorization: REPLACE_ME'
```
**Dobré vědět:**
* Vrací pole aktuálních členů.
* Nevyřízené pozvánky nejsou zahrnuté; vypisují se samostatně.
**Vrací:** pro každého člena:
| Pole | Popis |
| ----------- | ------------------------------------ |
| `userId` | ID uživatele člena. |
| `firstName` | Jméno. |
| `lastName` | Příjmení. |
| `email` | E-mailová adresa. |
| `joinedAt` | Kdy se člen připojil k obchodníkovi. |
**Slouží k** zobrazení terminálů obchodníka a zařízení, která jsou k nim přiřazená.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/terminal?page=1&pageSize=25' \
-H 'Authorization: REPLACE_ME'
```
**Dobré vědět:**
* Vrací terminály, nikoli aktivní lokality; lokality mají vlastní výpis.
* Odpověď obsahuje `items` a `totalCount`. Každá položka obsahuje ID terminálu a lokality, popisek a údaje o zařízení.
* `terminalType` a `deviceIdentifier` popisují aktuálně přiřazené zařízení, nikoli zařízení, které přijalo dřívější platbu.
**Parametry:**
| Pole | Popis |
| --------------- | ---------------------------- |
| `page` | Číslo stránky. |
| `pageSize` | Počet řádků na stránku. |
| `sortBy` | Pole, podle kterého se řadí. |
| `sortDirection` | Směr řazení. |
## Registrační pozvánky [#registration-invites]
Pro známého příjemce použijte [e-mailovou pozvánku](/platform-api/merchant_onboarding#invite-a-merchant-to-complete-hosted-onboarding), pro kampaň opakovaně použitelný odkaz. Obojí může omezit kanály a přiřadit cenové profily.
**Slouží ke** sledování odeslaných jednorázových pozvánek.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/merchant/invites' \
-H 'Authorization: REPLACE_ME'
```
**Dobré vědět:**
* Každá pozvánka uvádí e-mail příjemce, URL, `capability` a `commissionProfileIds`.
* Pozvánky obsahují také `commissionProfileId`, tedy podobu `commissionProfileIds` pro jeden profil.
**Slouží ke** sledování odkazů vašich kampaní a zjištění, které z nich jsou pozastavené.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/merchant/reusable-registration-invites' \
-H 'Authorization: REPLACE_ME'
```
**Dobré vědět:**
* Každý odkaz uvádí svou `capability`, přiřazené profily a `pausedAt`.
* `pausedAt` je `null`, dokud odkaz není pozastavený.
* Pozastavený odkaz, který neexpiroval a nebyl zrušen, stále odpovídá `isActive=true`. K jejich rozlišení kontrolujte `pausedAt`.
**Slouží ke** spuštění kampaně, přes kterou se může zaregistrovat mnoho obchodníků.
```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é vědět:**
* `capability` omezuje, které kanály si obchodníci mohou zvolit. Neuděluje schválení procesoru.
* Vynecháním polí profilů přiřadíte výchozí profil organizace.
* `commissionProfileId` se pro jeden profil stále přijímá. Používejte místo něj `commissionProfileIds` a nikdy neposílejte obě pole.
**Parametry:**
| Pole | Popis |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | Název kampaně. |
| `expiresAt` | Časové razítko ISO 8601 UTC alespoň jeden den v budoucnosti. Maximum není stanovené. |
| `capability` | Nepovinné. Stejné hodnoty jako u [e-mailových pozvánek](/platform-api/merchant_onboarding#invite-a-merchant-to-complete-hosted-onboarding). |
| `commissionProfileIds` | Nepovinné. Stejná pravidla jako u e-mailových pozvánek. |
**Slouží k** prodloužení nebo zkrácení pozvánky, včetně té, která 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é vědět:**
* U e-mailové pozvánky volejte `PUT /integrator/merchant/invites/{inviteId}/expires-at` se stejným tělem.
* Vrací `204`.
* Zrušené pozvánky a použité e-mailové pozvánky nelze prodloužit.
**Parametry:**
| Pole | Popis |
| ----------- | ------------------------------------------------------------------------------------ |
| `expiresAt` | Časové razítko ISO 8601 UTC alespoň jeden den v budoucnosti. Maximum není stanovené. |
**Slouží k** dočasnému zastavení nových registrací bez zrušení 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é vědět:**
* Voláním `.../resume` na stejný odkaz znovu povolíte registrace. Obnovení neprodlužuje expiraci.
* Obě operace vracejí `204` a jsou idempotentní.
* Otevření pozastaveného odkazu vrací `410`.
## Cenové profily [#commission-profiles]
Cenový profil je ceník, který nabízíte obchodníkům. Sestavte jej z cenové sady, ke které má vaše organizace oprávnění.
**Slouží k** nalezení cenových sad, ze kterých můžete sestavovat cenové profily.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/organization/pricing-sets?pricingType=instore' \
-H 'Authorization: REPLACE_ME'
```
**Dobré vědět:**
* Každá sada obsahuje své smluvní sazebníky pro obchodníka a integrátora.
* Při vytváření profilu použijte vrácené `pricingSetId`.
**Parametry:**
| Pole | Popis |
| ------------- | ----------------------------------- |
| `pricingType` | Nepovinné. `online` nebo `instore`. |
**Slouží k** výběru profilu, který přiřadíte pozvánce.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/organization/commission-profiles?pricingType=online' \
-H 'Authorization: REPLACE_ME'
```
**Dobré vědět:**
* Vrací pouze povolené a úplné profily vaší organizace.
* Každý profil pokrývá jeden typ cen.
* Pokud plánujete profil upravit, uchovejte si jeho `revision`.
**Parametry:**
| Pole | Popis |
| ------------- | ----------------------------------- |
| `pricingType` | Nepovinné. `online` nebo `instore`. |
**Slouží k** nabídce ceníku sestaveného z cenové sady obchodníkům.
```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é vědět:**
* Profil pokrývá jeden typ cen, převzatý z jeho cenových sad.
* Náklady integrátora a podíly na marži pocházejí z cenové sady; vy nastavujete pouze sazby obchodníka.
* `region` je `1` tuzemský nebo `2` zahraniční, `holderType` je `1` spotřebitel nebo `2` společnost a `scheme` je `1` Visa nebo `2` Mastercard.
**Parametry:**
| Pole | Popis |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `name` | Název profilu. |
| `pricingModel` | `1` pro MDR nebo `2` pro IC++. |
| `cardTypes` | Každá kombinace regionu, typu držitele karty a karetního schématu, kterou profil přijímá, s jejími referral poplatky. |
| `pricings` | Měna a `pricingSetId` pro každou měnu, kterou nabízíte. |
| `merchantPricingOverrides` | Nepovinné. Položky s `holderCategory`, `regionSegment`, `relative` a `absolute`. Vynechané kombinace zachovají sazby cenové sady. |
**Slouží k** přejmenování profilu nebo změně jeho sazeb.
```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é vědět:**
* Naposledy načtenou `revision` pošlete jako `expectedRevision`. Zastaralá revize vrací `409`.
* Vynecháním `pricings` zachováte uložené sazby.
* Profil, který je přiřazený obchodníkům nebo není upravitelný, přijme pouze nový název.
**Parametry:**
| Pole | Popis |
| ------------------ | ---------------------------------------------------- |
| `name` | Povinné. Název profilu. |
| `pricingModel` | Povinné. `1` pro MDR nebo `2` pro IC++. |
| `cardTypes` | Povinné. Stejné jako při vytvoření. |
| `pricings` | Nepovinné. Stejné jako při vytvoření. |
| `expectedRevision` | `revision` profilu v okamžiku, kdy jste jej načetli. |
**Slouží k** odstranění profilu, který už nenabízíte.
```bash
curl -X DELETE 'https://api.sandbox.tapaya.com/integrator/organization/commission-profiles/018f8f2a-7a1c-7b2d-8e3f-6c1d2e3f4a5b' \
-H 'Authorization: REPLACE_ME'
```
**Dobré vědět:**
* Výchozí profil nelze odstranit. Nejprve nastavte jako výchozí jiný profil.
* Profil přiřazený obchodníkům nelze odstranit. Oba případy vracejí `400`.
**Slouží k** výběru profilu, který použijí pozvánky, jež žádný profil neuvádějí.
```bash
curl -X PUT 'https://api.sandbox.tapaya.com/integrator/organization/commission-profiles/018f8f2a-7a1c-7b2d-8e3f-6c1d2e3f4a5b/default' \
-H 'Authorization: REPLACE_ME'
```
**Dobré vědět:**
* Vaše organizace má jeden výchozí profil.
* Výchozí profil nelze odstranit.
## Ceny obchodníka [#merchant-pricing]
**Slouží k** zobrazení sazeb, se kterými se obchodník zaregistroval, pro platby v prodejně a online.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/pricing' \
-H 'Authorization: REPLACE_ME'
```
**Dobré vědět:**
* Kanál bez uložených cen je `null`. Obchodník bez jakéhokoli uloženého ceníku vrací `404`.
* Vrací smluvní sazby, nikoli základní sazebníky poskytovatele plateb. Sazby čtěte z `cells`; složky `commission` nejsou realizované provize.
* Neznámý model nebo náklad integrátora je `null`, nikoli nula.
* Podíly na marži rozdělují rozdělovanou marži, nikoli celou částku platby.
**Vrací:**
| Pole | Popis |
| ------------------------------------- | --------------------------------------------------------------- |
| `instore` | Ceny pro platby v prodejně, nebo `null`. |
| `online` | Ceny pro online platby, nebo `null`. |
| `currency` | Měna ceníku. |
| `pricingModel` | Cenový model obchodníka. |
| `integratorPricingModel` | Cenový model integrátora, nezávislý na modelu obchodníka. |
| `priceListId` | Uložený ceník obchodníka, pokud je dostupný. |
| `pricingSetVersionId` | Verze zdrojové cenové sady, pokud je dostupná. |
| `pricingSetName` | Název zdrojové cenové sady, pokud je dostupný. |
| `cells` | Sazby podle kategorie držitele karty a regionu. |
| `cells[].discountBps` | Konečná relativní sazba obchodníka v bazických bodech. |
| `cells[].transactionFeeMinor` | Konečný pevný poplatek obchodníka v nejmenších jednotkách měny. |
| `cells[].integratorCostRelativeBps` | Smluvní relativní náklad integrátora v bazických bodech. |
| `cells[].integratorCostAbsoluteMinor` | Smluvní pevný náklad integrátora v nejmenších jednotkách měny. |
| `cells[].revenueShareTapayaBps` | Podíl Tapaya na rozdělované marži v bazických bodech. |
| `cells[].revenueShareIntegratorBps` | Váš podíl na rozdělované marži v bazických bodech. |
## Chyby [#errors]
Při neúspěšném požadavku odpovídá každá operace těmito stavovými kódy.
| Kód | Popis |
| ----- | ------------------------------------------------------------------------------------------------------------------- |
| `400` | Neplatné údaje kanálů, výběr profilů, filtry nebo expirace; případně pokus odstranit výchozí nebo přiřazený profil. |
| `401` | Server Secret Token chybí nebo je neplatný. |
| `404` | Zdroj není dostupný vaší organizaci nebo uložený onboarding či ceny neexistují. |
| `409` | Zastaralá revize profilu, konfliktní stav onboardingu nebo použitá či zrušená pozvánka. |