Aktivace subúčtu
Subúčet vzniká jedním požadavkem. Pošlete-li s ním identifikaci klienta, kterou jste provedli, Coinero ji převezme a subúčet se aktivuje hned.
Endpointy
| Endpoint | Co dělá |
|---|---|
| POST /v1/subaccounts | Založení subúčtu, volitelně s převzatou identifikací. Idempotentní podle externalClientRef. |
| GET /v1/subaccounts | Subúčty podle času poslední změny, kurzorově, včetně zamítnutých. Slouží ke sladění stavů. |
| GET /v1/subaccounts/{externalClientRef} | Detail subúčtu: stav, limity se zbývajícím denním limitem, povolené trhy a kontakt. |
| PUT /v1/subaccounts/{externalClientRef} | Změna kontaktu, adresy trvalého pobytu a daňových rezidencí. |
| DELETE /v1/subaccounts/{externalClientRef} | Ukončení subúčtu bez pozic a otevřených pokynů. Konečný stav, idempotentní. |
Vyžadují partnerský klíč s oprávněním subaccounts a podpis.
Identifikátor klienta
externalClientRef je identifikátor klienta ve vašem systému: 1 až 64 znaků, jen písmena bez diakritiky, číslice, pomlčka a podtržítko. V cestě ho používáte přesně tak, jak jste ho poslali při založení, včetně velikosti písmen. Je jedinečný ve vašem partnerském účtu. Osobní údaje klienta nikdy nepatří do cesty ani do hlaviček, jen do těla požadavku.
- Identifikátor, který se od existujícího liší jen velikostí písmen, založení odmítne: HTTP 409
CLIENT_REF_CONFLICT. - Hodnota
orders(v jakékoli velikosti písmen) je vyhrazená, protože/v1/subaccounts/ordersje seznam pokynů všech subúčtů. Založení ji odmítne chybou 400, čtení vrací 404.
Založení
POST /v1/subaccounts přijímá povinné externalClientRef, firstName, lastName, contactEmail a contactPhone, volitelně relatedPersonUserId (vazba na osobu, která už má účet u Coinera) a balíček identifikace.
| Požadavek | Výsledek |
|---|---|
| Bez balíčku identifikace | HTTP 201, subúčet je ve stavu review. Obchodovat může až po aktivaci, kterou provede Coinero. |
S balíčkem (kyc, consents, profile) | HTTP 201. Coinero ve stejném požadavku provede vlastní kontrolu sankčních seznamů, politicky exponovaných osob a rizikového profilu. Subúčet je hned active, nebo zůstane review k posouzení. Důvod posouzení se partnerovi nesděluje. |
Opakování se stejným externalClientRef | HTTP 200 s existujícím subúčtem v jeho aktuálním stavu, nic se nezakládá. Balíček identifikace jde poslat jen v požadavku, který subúčet zakládá. |
| Neúplný balíček (jen některé ze tří bloků) | HTTP 400 INVALID_PARAMETER s názvy chybějících bloků. |
Osobní údaje jen v těle.
Převzatá identifikace
Blok kyc nese údaje o klientovi a o tom, jak jste ho identifikovali, blok consents jeho souhlasy s dokumenty Coinera a blok profile krypto profil. Úplný seznam polí s popisem je v referenci. Povinné jsou:
- rodné číslo (
nationalId), nebodateOfBirthspolu sgender; nationalitya úplnáaddress;documents polemtype,number,identifiedBy,identifiedHowaidentifiedAt;pepStatusasanctionsScreening(výsledek vaší kontroly a čas);- aspoň jedna daňová rezidence (
tinje nepovinné), neprázdnéconsents(každý dokument nejvýš jednou) a celý blokprofile.
Ostatní pole jsou nepovinná. Data mají tvar YYYY-MM-DD, časy ISO 8601 s posunem, profile.expectedMonthlyVolume je desetinný řetězec v Kč. Neznámá pole API ignoruje. Hodnoty uzavřených množin jsou níže; jiná hodnota vrací HTTP 400 INVALID_PARAMETER.
| Pole | Hodnoty |
|---|---|
kyc.gender | male (muž); female (žena); other (jiné) |
kyc.pepStatus | no (klient není politicky exponovaná osoba); yes (klient je politicky exponovaná osoba; subúčet zůstane k posouzení) |
kyc.sanctionsScreening.result | clear (kontrola shodu nenašla); hit (kontrola našla shodu; subúčet zůstane k posouzení) |
kyc.document.type | identityCard (občanský průkaz); passport (cestovní pas); drivingLicence (řidičský průkaz); other (jiný doklad) |
kyc.document.identifiedHow | inPerson (za fyzické přítomnosti klienta); remote (na dálku); bankIdentity (bankovní identitou, například Bank iD); other (jiným způsobem) |
kyc.riskProfile | low (nízké riziko); medium (střední riziko); high (vysoké riziko; subúčet zůstane k posouzení) |
consents[].document | 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ů) |
profile.experience | none (bez zkušeností); basic (základní zkušenosti); experienced (zkušený investor) |
profile.shareOfInvestments | upTo10Percent (do 10 %); from10To25Percent (10 až 25 %); from25To50Percent (25 až 50 %); over50Percent (nad 50 %) |
Stavy subúčtu
| Stav | 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 |
- Čtení zůstatků, obchodů a pokynů funguje v každém stavu kromě
rejected(i u ukončeného subúčtu), kde čtení vrací 404CLIENT_NOT_FOUND. Zamítnutý subúčet uvidíte v seznamu subúčtů. - Zápisy, tedy zadání a potvrzení pokynu, jsou možné jen ve stavu
active. Ve stavureviewvracejí HTTP 409CLIENT_RESTRICTED, ublocked409CLIENT_BLOCKED, uclosed409CLIENT_CLOSED. Zamítnutý subúčet vrací při čtení a u pokynů 404CLIENT_NOT_FOUND, změna údajů 409CLIENT_RESTRICTED(viz Aktualizace). - Zablokování a zamítnutí provádí jen Coinero. Důvod se v API nevrací, vidíte jen stav.
- Ukončit subúčet můžete vy (viz Ukončení subúčtu), nebo Coinero. Stav
closedje konečný.
Jak se dozvíte výsledek
Odpověď na založení
Pole
statusv odpovědi říká, zda je subúčet hnedactive, nebo čeká vreview.Webhook
Při změně stavu pošle Coinero na váš cíl událost
subaccount.activated,subaccount.rejected,subaccount.blockednebosubaccount.closed. Tělem události je objekt subúčtu, týž jako v odpovědi na dotaz. Viz Webhooky.Dotaz
GET /v1/subaccounts/{externalClientRef} vrací stav, limity se zbývajícím denním limitem, povolené trhy a kontakt. Pozice subúčtu v kryptoměnách vrací GET …/positions.
Sladění stavů
Po výpadku vašeho cíle webhooků nebo při dohledání aktivací načtete stavy všech subúčtů přes GET /v1/subaccounts. Seznam řadí subúčty podle času poslední změny od nejnovější, stránkuje kurzorem (nextCursor pošlete v parametru cursor) a vrací tentýž objekt subúčtu jako detail, včetně zamítnutých. Filtr status vybere jeden stav, updatedAfter jen subúčty změněné po zadaném okamžiku.
Čas poslední změny nese pole updatedAt a posune se při změně stavu a kontaktu subúčtu. Změny mladší než 5 sekund seznam ještě nevrací. Další sladění začněte s updatedAfter nastaveným na nejnovější updatedAt z položek, které jste přečetli (stejně jako u seznamu pokynů), ne podle hodin svého systému. Dotaz vrátí všechny pozdější změny včetně subúčtů, které se změnily během předchozího čtení; subúčet načtený dvakrát je stejný objekt.
Aktualizace
PUT /v1/subaccounts/{externalClientRef} změní kontakt, adresu trvalého pobytu a daňové rezidence. Chybějící pole zůstávají beze změny, taxResidencies nahradí celý seznam. Adresu a daňové rezidence lze měnit jen u subúčtu založeného s balíčkem identifikace (jinak 409 CLIENT_STATE_INVALID) a jen ve stavech review a active: zablokovaný subúčet vrací CLIENT_BLOCKED, zamítnutý CLIENT_RESTRICTED. Změna státu adresy nebo daňové rezidence u aktivního subúčtu vyvolá u Coinera nové posouzení.
Ukončení subúčtu
Když klient službu ukončí, ukončete jeho subúčet požadavkem DELETE /v1/subaccounts/{externalClientRef} bez těla. Odpověď 200 nese objekt subúčtu ve stavu closed s časem ukončení closedAt a Coinero pošle událost subaccount.closed. Opakovaný požadavek vrátí totéž, nic nezmění a událost znovu nepošle.
- Ukončit jde subúčet ve stavu
active,reviewiblocked. Zamítnutý subúčet vrací 409CLIENT_RESTRICTED. - Subúčet nesmí mít pokyn čekající na potvrzení, financovaný ani v exekuci, ani dokončený pokyn, který ještě není vypořádaný; jinak 409
CLIENT_HAS_OPEN_ORDERS. - Subúčet nesmí držet kryptoměnu (ani blokovanou pro pokyn) ani fiat zůstatek; jinak 409
CLIENT_HAS_POSITIONS. Pozice nejdřív prodejte, fiat po prodeji se vrací na váš partnerský účet automaticky. - Po ukončení vracejí zadání a potvrzení pokynu i změna údajů 409
CLIENT_CLOSED. Subúčet se znovu neotevírá: založení se stejnýmexternalClientRef, i lišícím se jen velikostí písmen, vrací 409CLIENT_CLOSED. Pro vracejícího se klienta použijte nový identifikátor. - Čtení funguje dál: detail, pozice, zůstatky, historie obchodů a pokynů i denní reporty minulých dnů zůstávají beze změny.
Chyby
| Kód | Stav | Kdy |
|---|---|---|
CLIENT_REF_CONFLICT | 409 | Partner už má subúčet s identifikátorem lišícím se jen velikostí písmen. |
CLIENT_NOT_FOUND | 404 | Subúčet s tímto identifikátorem klienta partner nemá. |
CLIENT_RESTRICTED | 409 | Subúčet v tomto stavu nejde měnit ani s ním obchodovat. |
CLIENT_BLOCKED | 409 | Subúčet je zablokovaný, nejde měnit ani s ním obchodovat. |
CLIENT_CLOSED | 409 | Subúčet je ukončený, nejde měnit, obchodovat s ním ani ho znovu založit. |
CLIENT_STATE_INVALID | 409 | Subúčet tuto změnu nepovoluje. |
CLIENT_HAS_OPEN_ORDERS | 409 | Subúčet nejde ukončit, má otevřený nebo nevypořádaný pokyn. |
CLIENT_HAS_POSITIONS | 409 | Subúčet nejde ukončit, drží kryptoměnu nebo fiat zůstatek. |
PARTNER_SUSPENDED | 409 | Partnerský účet je pozastavený nebo ukončený. |
PARTNER_BUSY | 503 | Coinero právě zpracovává jiné požadavky vašeho partnerského účtu. |
Při vypnuté partnerské části API vrací založení, změna i ukončení subúčtu HTTP 503 SERVICE_MAINTENANCE s Retry-After, viz Stav služby.