Získat API klíč
Přehled API · Subúčty

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

Endpoint patří do sekce Subúčty. Vyžaduje partnerský API klíč (prefix 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 · CreateSubaccountBody

Podepiš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é.

PolePopis
externalClientRefpovinnéstringPovinné. 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éstringPovinné. Jméno klienta, nejvýše 100 znaků.
lastNamepovinnéstringPovinné. Příjmení klienta, nejvýše 100 znaků.
contactEmailpovinnéstringPovinné. Kontaktní e-mail klienta.
contactPhonepovinnéstringPovinné. Kontaktní telefon klienta v mezinárodním tvaru, například +420601234567.
relatedPersonUserIdvolitelnéstringNepovinné. Identifikátor existujícího klienta Coinera, který je touž osobou jako váš klient, pokud ho znáte.
kycvolitelnéSubaccountKycBodyNepovinné. 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éstringPodmíněně povinné. Rodné číslo. Pošlete buď nationalId, nebo dateOfBirth spolu s gender, nikdy obojí.
kyc.dateOfBirthvolitelnéstringPodmíněně povinné. Datum narození, YYYY-MM-DD. Povinné, když neposíláte nationalId, s ním nepovolené.
kyc.gendervolitelnéstringPodmíněně povinné. Pohlaví. Povinné, když neposíláte nationalId, s ním nepovolené. Hodnoty: male, female, other.
kyc.placeOfBirthvolitelnéstringNepovinné. Místo narození, nejvýše 128 znaků.
kyc.nationalitypovinnéstringPovinné. Státní občanství, kód ISO 3166-1 alpha-2, například CZ.
kyc.secondNationalityvolitelnéstringNepovinné. Druhé státní občanství, kód ISO 3166-1 alpha-2.
kyc.addresspovinnéSubaccountAddressBodyPovinné. Adresa trvalého pobytu.
kyc.address.streetpovinnéstringPovinné. Ulice, nejvýše 128 znaků.
kyc.address.houseNumberpovinnéstringPovinné. Číslo domu, nejvýše 32 znaků.
kyc.address.citypovinnéstringPovinné. Obec, nejvýše 128 znaků.
kyc.address.postalCodepovinnéstringPovinné. PSČ, nejvýše 16 znaků.
kyc.address.countrypovinnéstringPovinné. Stát, kód ISO 3166-1 alpha-2, například CZ.
kyc.documentpovinnéSubaccountDocumentBodyPovinné. Doklad totožnosti a kdo, jak a kdy klienta identifikoval.
kyc.document.typepovinnéstringPovinné. Druh dokladu totožnosti. Hodnoty: identityCard, passport, drivingLicence, other.
kyc.document.numberpovinnéstringPovinné. Číslo dokladu, nejvýše 64 znaků.
kyc.document.validUntilvolitelnéstringNepovinné. Platnost dokladu do, YYYY-MM-DD.
kyc.document.issuingCountryvolitelnéstringNepovinné. Stát vydání dokladu, kód ISO 3166-1 alpha-2.
kyc.document.identifiedBypovinnéstringPovinné. Kdo klienta identifikoval (váš pracovník nebo pobočka), nejvýše 200 znaků.
kyc.document.identifiedHowpovinnéstringPovinné. Jak byl klient identifikován. Hodnoty: inPerson, remote, bankIdentity, other.
kyc.document.identifiedAtpovinnéstringPovinné. Kdy byl klient identifikován, ISO 8601 s posunem časového pásma.
kyc.pepStatuspovinnéstringPovinné. Zda je klient politicky exponovaná osoba podle vašeho posouzení. Hodnoty: no, yes.
kyc.sanctionsScreeningpovinnéSubaccountSanctionsScreeningBodyPovinné. Výsledek vaší kontroly sankčních seznamů.
kyc.sanctionsScreening.resultpovinnéstringPovinné. Výsledek vaší kontroly; hit nechá subúčet k posouzení. Hodnoty: clear, hit.
kyc.sanctionsScreening.checkedAtpovinnéstringPovinné. Kdy jste klienta prověřili, ISO 8601 s posunem časového pásma.
kyc.taxResidenciespovinnépole SubaccountTaxResidencyBodyPovinné. Daňové rezidence klienta, aspoň jedna, každý stát nejvýše jednou.
kyc.taxResidencies[].countrypovinnéstringPovinné. Stát daňové rezidence, kód ISO 3166-1 alpha-2.
kyc.taxResidencies[].tinvolitelnéstringNepovinné. Daňové identifikační číslo v daném státě, nejvýše 64 znaků.
kyc.riskProfilevolitelnéstringNepovinné. Rizikový profil klienta podle vašeho hodnocení; high nechá subúčet k posouzení. Hodnoty: low, medium, high.
kyc.purposeOfRelationshipvolitelnéstringNepovinné. Účel obchodního vztahu, nejvýše 500 znaků.
kyc.sourceOfFundsvolitelnéstringNepovinné. Zdroj prostředků, nejvýše 500 znaků.
consentsvolitelnépole SubaccountConsentBodyNepovinné, jen spolu s kyc a profile. Souhlasy klienta s dokumenty Coinera, aspoň jeden, každý dokument nejvýše jednou.
consents[].documentpovinnéstringPovinné. Dokument Coinera, se kterým klient souhlasil. Hodnoty: frameworkAgreement, priceList, executionPolicy, riskInformation, privacy.
consents[].versionpovinnéstringPovinné. Verze dokumentu, 1 až 32 znaků.
consents[].acceptedAtpovinnéstringPovinné. Kdy klient souhlasil, ISO 8601 s posunem časového pásma.
profilevolitelnéSubaccountProfileBodyNepovinné, jen spolu s kyc a consents. Krypto profil klienta.
profile.experiencepovinnéstringPovinné. Zkušenosti klienta s investováním do kryptoaktiv. Hodnoty: none, basic, experienced.
profile.expectedMonthlyVolumepovinnéstringPovinné. Očekávaný měsíční objem obchodů v korunách, nezáporné desetinné číslo jako řetězec, například "50000".
profile.shareOfInvestmentspovinnéstringPovinné. Podíl kryptoaktiv na investicích klienta. Hodnoty: upTo10Percent, from10To25Percent, from25To50Percent, over50Percent.

Odpověď

201 · application/json · SubaccountResponse

Bez 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.

PolePopis
externalClientRefstringIdentifikátor klienta ve vašem systému, jak byl uložen při založení.
statusstringStav subúčtu. Hodnoty: review, active, blocked, rejected, closed.
createdAtstringKdy subúčet vznikl, ISO 8601, UTC.
createdAtMsinteger (int64)Stejný okamžik jako Unix timestamp v milisekundách.
activatedAtstring nebo nullKdy byl subúčet naposledy aktivován, ISO 8601, UTC; null, pokud nikdy. Pole je v odpovědi vždy.
activatedAtMsinteger nebo nullStejný okamžik jako Unix timestamp v milisekundách. Případně null.
closedAtstring nebo nullKdy byl subúčet ukončen, ISO 8601, UTC; null, dokud ukončený není. Pole je v odpovědi vždy.
closedAtMsinteger nebo nullStejný okamžik jako Unix timestamp v milisekundách. Případně null.
updatedAtstringKdy 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.
limitsSubaccountLimitsResponseLimity pokynů vašeho partnerského účtu, které platí pro subúčet.
limits.minOrderAmountApiMoneyNejmenší 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.currencystringKód měny částky, například BTC nebo CZK.
limits.maxOrderAmountApiMoney nebo nullNejvě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.currencystringKód měny částky, například BTC nebo CZK.
limits.dailyLimitApiMoneyDenní 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.currencystringKód měny částky, například BTC nebo CZK.
limits.dailyLimitRemainingApiMoneyZbý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.currencystringKód měny částky, například BTC nebo CZK.
allowedMarketspole stringTrhy, na kterých subúčet smí obchodovat: kryptoměny, které partner nabízí, proti jeho měně vypořádání, například BTCCZK.
contactSubaccountContactResponseKontakt klienta, jak jste ho poslali.
contact.emailstring nebo nullKontaktní e-mail klienta, nebo null. Pole je v odpovědi vždy.
contact.phonestring nebo nullKontaktní 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í.

PublicGenderVýznam
malemuž
femaležena
otherjiné
PublicIdentityDocumentTypeVýznam
identityCardobčanský průkaz
passportcestovní pas
drivingLicenceřidičský průkaz
otherjiný doklad
PublicIdentificationMethodVýznam
inPersonza fyzické přítomnosti klienta
remotena dálku
bankIdentitybankovní identitou, například Bank iD
otherjiným způsobem
PublicPepStatusVýznam
noklient není politicky exponovaná osoba
yesklient je politicky exponovaná osoba; subúčet zůstane k posouzení
PublicSanctionsScreeningResultVýznam
clearkontrola shodu nenašla
hitkontrola našla shodu; subúčet zůstane k posouzení
PublicPartnerRiskProfileVýznam
lownízké riziko
mediumstřední riziko
highvysoké riziko; subúčet zůstane k posouzení
PublicConsentDocumentVýznam
frameworkAgreementrámcová smlouva
priceListceník
executionPolicyzásady provádění pokynů
riskInformationinformace o rizicích
privacyinformace o zpracování osobních údajů
PublicInvestmentExperienceVýznam
nonebez zkušeností
basiczákladní zkušenosti
experiencedzkušený investor
PublicShareOfInvestmentsVýznam
upTo10Percentdo 10 %
from10To25Percent10 až 25 %
from25To50Percent25 až 50 %
over50Percentnad 50 %
PublicSubaccountStatusVýznam
reviewsubúčet čeká na posouzení Coinerem a zatím nemůže obchodovat
activesubúčet může obchodovat
blockedCoinero subúčet zablokovalo a ten nemůže obchodovat; důvod se nesděluje
rejectedaktivace 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í
closedsubúč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.

StavKódyŘešení
400INVALID_PARAMETEROpravte parametry uvedené v poli detail podle dokumentace. Opakovaný parametr se bere jako chybný.
401MISSING_API_KEY, INVALID_API_KEY, SIGNATURE_REQUIRED, INVALID_SIGNATURE, TIMESTAMP_OUT_OF_WINDOWDoplň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.
403INSUFFICIENT_PERMISSION, IP_NOT_ALLOWEDPole 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.
405METHOD_NOT_ALLOWEDPoužijte metodu z hlavičky Allow: GET a HEAD ke čtení, POST a DELETE jen u operací, které je mají v dokumentaci.
409PARTNER_SUSPENDED, CLIENT_CLOSED, CLIENT_REF_CONFLICTSpoluprá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.
429RATE_LIMIT_EXCEEDEDPřed dalším pokusem vyčkejte počet sekund z Retry-After.
503PARTNER_BUSY, SERVICE_MAINTENANCEStejný 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.