POST /v1/subaccounts
Založí subúčet pro vašeho klienta podle identifikátoru, který klient má ve vašem systému.
Partnerský klíč s oprávněním subaccounts
pk_) s oprávněním subaccounts a podpis požadavku; klientský klíč dostane 403 INSUFFICIENT_PERMISSION. Postup je na stránkách Podpis požadavků a Klíč partnera.Tělo požadavku
application/json · CreateSubaccountBodyPodepište a odešlete bajt po bajtu totéž tělo, bez přeformátování. Neznámá pole API ignoruje a pole s hodnotou null je totéž jako pole vynechané.
| Pole | Popis |
|---|---|
| externalClientRefpovinnéstring | Povinné. Identifikátor klienta ve vašem systému: 1 až 64 písmen bez diakritiky, číslic, pomlček a podtržítek. Přesně v tomto tvaru ho používejte v cestě všech endpointů subúčtu. |
| firstNamepovinnéstring | Povinné. Jméno klienta, nejvýše 100 znaků. |
| lastNamepovinnéstring | Povinné. Příjmení klienta, nejvýše 100 znaků. |
| contactEmailpovinnéstring | Povinné. Kontaktní e-mail klienta. |
| contactPhonepovinnéstring | Povinné. Kontaktní telefon klienta v mezinárodním tvaru, například +420601234567. |
| relatedPersonUserIdvolitelnéstring | Nepovinné. Identifikátor existujícího klienta Coinera, který je touž osobou jako váš klient, pokud ho znáte. |
| kycvolitelnéSubaccountKycBody | Nepovinné. Identifikace klienta, kterou jste provedli. Posílá se spolu s consents a profile, nebo žádný ze tří bloků. S balíčkem Coinero provede vlastní kontrolu sankcí, PEP a rizikového profilu a subúčet je hned aktivní, nebo zůstane k posouzení. Osobní údaje se nikdy nevracejí. |
| kyc.nationalIdvolitelnéstring | Podmíněně povinné. Rodné číslo. Pošlete buď nationalId, nebo dateOfBirth spolu s gender, nikdy obojí. |
| kyc.dateOfBirthvolitelnéstring | Podmíněně povinné. Datum narození, YYYY-MM-DD. Povinné, když neposíláte nationalId, s ním nepovolené. |
| kyc.gendervolitelnéstring | Podmíněně povinné. Pohlaví. Povinné, když neposíláte nationalId, s ním nepovolené. Hodnoty: male, female, other. |
| kyc.placeOfBirthvolitelnéstring | Nepovinné. Místo narození, nejvýše 128 znaků. |
| kyc.nationalitypovinnéstring | Povinné. Státní občanství, kód ISO 3166-1 alpha-2, například CZ. |
| kyc.secondNationalityvolitelnéstring | Nepovinné. Druhé státní občanství, kód ISO 3166-1 alpha-2. |
| kyc.addresspovinnéSubaccountAddressBody | Povinné. Adresa trvalého pobytu. |
| kyc.address.streetpovinnéstring | Povinné. Ulice, nejvýše 128 znaků. |
| kyc.address.houseNumberpovinnéstring | Povinné. Číslo domu, nejvýše 32 znaků. |
| kyc.address.citypovinnéstring | Povinné. Obec, nejvýše 128 znaků. |
| kyc.address.postalCodepovinnéstring | Povinné. PSČ, nejvýše 16 znaků. |
| kyc.address.countrypovinnéstring | Povinné. Stát, kód ISO 3166-1 alpha-2, například CZ. |
| kyc.documentpovinnéSubaccountDocumentBody | Povinné. Doklad totožnosti a kdo, jak a kdy klienta identifikoval. |
| kyc.document.typepovinnéstring | Povinné. Druh dokladu totožnosti. Hodnoty: identityCard, passport, drivingLicence, other. |
| kyc.document.numberpovinnéstring | Povinné. Číslo dokladu, nejvýše 64 znaků. |
| kyc.document.validUntilvolitelnéstring | Nepovinné. Platnost dokladu do, YYYY-MM-DD. |
| kyc.document.issuingCountryvolitelnéstring | Nepovinné. Stát vydání dokladu, kód ISO 3166-1 alpha-2. |
| kyc.document.identifiedBypovinnéstring | Povinné. Kdo klienta identifikoval (váš pracovník nebo pobočka), nejvýše 200 znaků. |
| kyc.document.identifiedHowpovinnéstring | Povinné. Jak byl klient identifikován. Hodnoty: inPerson, remote, bankIdentity, other. |
| kyc.document.identifiedAtpovinnéstring | Povinné. Kdy byl klient identifikován, ISO 8601 s posunem časového pásma. |
| kyc.pepStatuspovinnéstring | Povinné. Zda je klient politicky exponovaná osoba podle vašeho posouzení. Hodnoty: no, yes. |
| kyc.sanctionsScreeningpovinnéSubaccountSanctionsScreeningBody | Povinné. Výsledek vaší kontroly sankčních seznamů. |
| kyc.sanctionsScreening.resultpovinnéstring | Povinné. Výsledek vaší kontroly; hit nechá subúčet k posouzení. Hodnoty: clear, hit. |
| kyc.sanctionsScreening.checkedAtpovinnéstring | Povinné. Kdy jste klienta prověřili, ISO 8601 s posunem časového pásma. |
| kyc.taxResidenciespovinnépole SubaccountTaxResidencyBody | Povinné. Daňové rezidence klienta, aspoň jedna, každý stát nejvýše jednou. |
| kyc.taxResidencies[].countrypovinnéstring | Povinné. Stát daňové rezidence, kód ISO 3166-1 alpha-2. |
| kyc.taxResidencies[].tinvolitelnéstring | Nepovinné. Daňové identifikační číslo v daném státě, nejvýše 64 znaků. |
| kyc.riskProfilevolitelnéstring | Nepovinné. Rizikový profil klienta podle vašeho hodnocení; high nechá subúčet k posouzení. Hodnoty: low, medium, high. |
| kyc.purposeOfRelationshipvolitelnéstring | Nepovinné. Účel obchodního vztahu, nejvýše 500 znaků. |
| kyc.sourceOfFundsvolitelnéstring | Nepovinné. Zdroj prostředků, nejvýše 500 znaků. |
| consentsvolitelnépole SubaccountConsentBody | Nepovinné, jen spolu s kyc a profile. Souhlasy klienta s dokumenty Coinera, aspoň jeden, každý dokument nejvýše jednou. |
| consents[].documentpovinnéstring | Povinné. Dokument Coinera, se kterým klient souhlasil. Hodnoty: frameworkAgreement, priceList, executionPolicy, riskInformation, privacy. |
| consents[].versionpovinnéstring | Povinné. Verze dokumentu, 1 až 32 znaků. |
| consents[].acceptedAtpovinnéstring | Povinné. Kdy klient souhlasil, ISO 8601 s posunem časového pásma. |
| profilevolitelnéSubaccountProfileBody | Nepovinné, jen spolu s kyc a consents. Krypto profil klienta. |
| profile.experiencepovinnéstring | Povinné. Zkušenosti klienta s investováním do kryptoaktiv. Hodnoty: none, basic, experienced. |
| profile.expectedMonthlyVolumepovinnéstring | Povinné. Očekávaný měsíční objem obchodů v korunách, nezáporné desetinné číslo jako řetězec, například "50000". |
| profile.shareOfInvestmentspovinnéstring | Povinné. Podíl kryptoaktiv na investicích klienta. Hodnoty: upTo10Percent, from10To25Percent, from25To50Percent, over50Percent. |
Odpověď
201 · application/json · SubaccountResponseBez balíčku identifikace je nový subúčet ve stavu review; obchodovat může až po aktivaci, kterou provede Coinero.
S balíčkem identifikace (bloky kyc, consents a profile, vždy všechny tři) Coinero převezme vaši identifikaci klienta, v témže požadavku provede vlastní kontrolu sankčních seznamů, politicky exponovaných osob a rizikového profilu a subúčet je hned active, nebo zůstane review k posouzení.
Požadavek je idempotentní: opakování se stejným externalClientRef nic nezaloží a vrátí existující subúčet s odpovědí 200 v jeho aktuálním stavu. Balíček identifikace jde poslat jen v požadavku, který subúčet zakládá.
Osobní údaje jsou jen v těle požadavku; odpověď ani chybové texty je nevracejí.
Vyžaduje partnerský API klíč s oprávněním subaccounts a podepsaný požadavek. Odpověď se neukládá do cache.
Částky a ceny jsou desetinné řetězce, aby nedocházelo ke ztrátě přesnosti.
| Pole | Popis |
|---|---|
| externalClientRefstring | Identifikátor klienta ve vašem systému, jak byl uložen při založení. |
| statusstring | Stav subúčtu. Hodnoty: review, active, blocked, rejected, closed. |
| createdAtstring | Kdy subúčet vznikl, ISO 8601, UTC. |
| createdAtMsinteger (int64) | Stejný okamžik jako Unix timestamp v milisekundách. |
| activatedAtstring nebo null | Kdy byl subúčet naposledy aktivován, ISO 8601, UTC; null, pokud nikdy. Pole je v odpovědi vždy. |
| activatedAtMsinteger nebo null | Stejný okamžik jako Unix timestamp v milisekundách. Případně null. |
| closedAtstring nebo null | Kdy byl subúčet ukončen, ISO 8601, UTC; null, dokud ukončený není. Pole je v odpovědi vždy. |
| closedAtMsinteger nebo null | Stejný okamžik jako Unix timestamp v milisekundách. Případně null. |
| updatedAtstring | Kdy se subúčet naposledy změnil (stav nebo kontakt), ISO 8601, UTC. Podle něj GET /v1/subaccounts řadí a filtruje: nejnovější přečtená hodnota je updatedAfter vašeho dalšího čtení. V události webhooku je to okamžik události, nikdy pozdější než hodnota v seznamu. |
| updatedAtMsinteger (int64) | Stejný okamžik jako Unix timestamp v milisekundách. |
| limitsSubaccountLimitsResponse | Limity pokynů vašeho partnerského účtu, které platí pro subúčet. |
| limits.minOrderAmountApiMoney | Nejmenší pokyn v korunách. |
| limits.minOrderAmount.amountstring | Částka jako desetinný řetězec s tečkou a nejméně s tolika místy, kolik má její měna. Zpracujte ji jako desetinné číslo, ne jako číslo s pohyblivou řádovou čárkou. |
| limits.minOrderAmount.currencystring | Kód měny částky, například BTC nebo CZK. |
| limits.maxOrderAmountApiMoney nebo null | Největší pokyn v korunách; null bez horní meze. Pole je v odpovědi vždy. |
| limits.maxOrderAmount.amountstring | Částka jako desetinný řetězec s tečkou a nejméně s tolika místy, kolik má její měna. Zpracujte ji jako desetinné číslo, ne jako číslo s pohyblivou řádovou čárkou. |
| limits.maxOrderAmount.currencystring | Kód měny částky, například BTC nebo CZK. |
| limits.dailyLimitApiMoney | Denní limit pokynů jednoho klienta v korunách. |
| limits.dailyLimit.amountstring | Částka jako desetinný řetězec s tečkou a nejméně s tolika místy, kolik má její měna. Zpracujte ji jako desetinné číslo, ne jako číslo s pohyblivou řádovou čárkou. |
| limits.dailyLimit.currencystring | Kód měny částky, například BTC nebo CZK. |
| limits.dailyLimitRemainingApiMoney | Zbývající část denního limitu pro dnešní den podle pražského času, v korunách. Zrušené a odmítnuté pokyny se nepočítají. |
| limits.dailyLimitRemaining.amountstring | Částka jako desetinný řetězec s tečkou a nejméně s tolika místy, kolik má její měna. Zpracujte ji jako desetinné číslo, ne jako číslo s pohyblivou řádovou čárkou. |
| limits.dailyLimitRemaining.currencystring | Kód měny částky, například BTC nebo CZK. |
| allowedMarketspole string | Trhy, na kterých subúčet smí obchodovat: kryptoměny, které partner nabízí, proti jeho měně vypořádání, například BTCCZK. |
| contactSubaccountContactResponse | Kontakt klienta, jak jste ho poslali. |
| contact.emailstring nebo null | Kontaktní e-mail klienta, nebo null. Pole je v odpovědi vždy. |
| contact.phonestring nebo null | Kontaktní telefon klienta v mezinárodním tvaru, nebo null. Pole je v odpovědi vždy. |
Hodnoty stavů
Nové hodnoty mohou přibýt i v rámci v1; neznámou hodnotu zpracujte bez selhání.
| PublicGender | Význam |
|---|---|
male | muž |
female | žena |
other | jiné |
| PublicIdentityDocumentType | Význam |
|---|---|
identityCard | občanský průkaz |
passport | cestovní pas |
drivingLicence | řidičský průkaz |
other | jiný doklad |
| PublicIdentificationMethod | Význam |
|---|---|
inPerson | za fyzické přítomnosti klienta |
remote | na dálku |
bankIdentity | bankovní identitou, například Bank iD |
other | jiným způsobem |
| PublicPepStatus | Význam |
|---|---|
no | klient není politicky exponovaná osoba |
yes | klient je politicky exponovaná osoba; subúčet zůstane k posouzení |
| PublicSanctionsScreeningResult | Význam |
|---|---|
clear | kontrola shodu nenašla |
hit | kontrola našla shodu; subúčet zůstane k posouzení |
| PublicPartnerRiskProfile | Význam |
|---|---|
low | nízké riziko |
medium | střední riziko |
high | vysoké riziko; subúčet zůstane k posouzení |
| PublicConsentDocument | Význam |
|---|---|
frameworkAgreement | rámcová smlouva |
priceList | ceník |
executionPolicy | zásady provádění pokynů |
riskInformation | informace o rizicích |
privacy | informace o zpracování osobních údajů |
| PublicInvestmentExperience | Význam |
|---|---|
none | bez zkušeností |
basic | základní zkušenosti |
experienced | zkušený investor |
| PublicShareOfInvestments | Význam |
|---|---|
upTo10Percent | do 10 % |
from10To25Percent | 10 až 25 % |
from25To50Percent | 25 až 50 % |
over50Percent | nad 50 % |
| PublicSubaccountStatus | Význam |
|---|---|
review | subúčet čeká na posouzení Coinerem a zatím nemůže obchodovat |
active | subúčet může obchodovat |
blocked | Coinero subúčet zablokovalo a ten nemůže obchodovat; důvod se nesděluje |
rejected | aktivace subúčtu byla trvale zamítnuta; detail a endpointy pod prefixem subúčtu ho vracejí jako 404, objeví se v seznamu GET /v1/subaccounts a v odpovědi opakovaného založení |
closed | subúčet je ukončený a nemůže obchodovat ani se měnit; data jdou dál číst a znovu otevřít ho nejde |
Chyby
Chyby mají formát application/problem+json; zpracovávejte je podle pole code. Podrobnosti najdete v přehledu chyb.
| Stav | Kódy | Řešení |
|---|---|---|
| 400 | INVALID_PARAMETER | Opravte parametry uvedené v poli detail podle dokumentace. Opakovaný parametr se bere jako chybný. |
| 401 | MISSING_API_KEY, INVALID_API_KEY, SIGNATURE_REQUIRED, INVALID_SIGNATURE, TIMESTAMP_OUT_OF_WINDOW | Doplňte hlavičku X-COINERO-APIKEY. Ověřte hodnotu a stav klíče i aktivitu účtu. Doplňte hlavičky X-COINERO-TIMESTAMP a X-COINERO-SIGNATURE podle stránky Podpis požadavků. Zkontrolujte kanonický řetězec (časová značka, metoda velkými písmeny, cesta s dotazem, tělo bajt po bajtu) a že secret před HMAC dekódujete z Base64; stránka Podpis požadavků má referenční vektor. Použijte aktuální čas v milisekundách; pole serverTime a serverTimeMs v odpovědi nesou čas serveru, podle kterého opravte hodiny klienta. |
| 403 | INSUFFICIENT_PERMISSION, IP_NOT_ALLOWED | Pole requiredPermission uvádí, které oprávnění chybí. Oprávnění klíče nelze změnit; vytvořte nový klíč s potřebným oprávněním. Odešlete požadavek z adresy povolené u klíče, nebo vytvořte nový klíč, jehož seznam adresu obsahuje; seznam nelze dodatečně změnit. |
| 405 | METHOD_NOT_ALLOWED | Použijte metodu z hlavičky Allow: GET a HEAD ke čtení, POST a DELETE jen u operací, které je mají v dokumentaci. |
| 409 | PARTNER_SUSPENDED, CLIENT_CLOSED, CLIENT_REF_CONFLICT | Spolupráce je pozastavená nebo ukončená; kontaktujte Coinero. Čtení dat funguje dál. Subúčet je ukončený; čtení funguje dál, zápisy ani nové založení se stejným externalClientRef nejdou. Pro vracejícího se klienta založte subúčet s novým identifikátorem. Použijte externalClientRef přesně v tvaru, v jakém subúčet vznikl, nebo zvolte jiný; identifikátory lišící se jen velikostí písmen vedle sebe existovat nemůžou. |
| 429 | RATE_LIMIT_EXCEEDED | Před dalším pokusem vyčkejte počet sekund z Retry-After. |
| 503 | PARTNER_BUSY, SERVICE_MAINTENANCE | Stejný požadavek zopakujte za několik sekund; opakování je bezpečné. Subúčet už mohl vzniknout: opakované založení ho vrátí a dokončí jeho kontroly. Probíhá údržba nebo je dočasně vypnuté obchodování či WebSocket; ověřte GET /v1/status a vyčkejte podle Retry-After. |