Získat API klíč
Subúčty (partneři)

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

EndpointCo dělá
POST /v1/subaccountsZaložení subúčtu, volitelně s převzatou identifikací. Idempotentní podle externalClientRef.
GET /v1/subaccountsSubúč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/orders je 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žadavekVýsledek
Bez balíčku identifikaceHTTP 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 externalClientRefHTTP 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.

Odpovědi ani chybové texty osobní údaje klienta nevracejí a chyba validace jmenuje jen pole, nikdy hodnotu. API tělo požadavku neloguje.

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), nebo dateOfBirth spolu s gender;
  • nationality a úplná address;
  • document s polem type, number, identifiedBy, identifiedHow a identifiedAt;
  • pepStatus a sanctionsScreening (výsledek vaší kontroly a čas);
  • aspoň jedna daňová rezidence (tin je nepovinné), neprázdné consents (každý dokument nejvýš jednou) a celý blok profile.

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.

PoleHodnoty
kyc.gendermale (muž); female (žena); other (jiné)
kyc.pepStatusno (klient není politicky exponovaná osoba); yes (klient je politicky exponovaná osoba; subúčet zůstane k posouzení)
kyc.sanctionsScreening.resultclear (kontrola shodu nenašla); hit (kontrola našla shodu; subúčet zůstane k posouzení)
kyc.document.typeidentityCard (občanský průkaz); passport (cestovní pas); drivingLicence (řidičský průkaz); other (jiný doklad)
kyc.document.identifiedHowinPerson (za fyzické přítomnosti klienta); remote (na dálku); bankIdentity (bankovní identitou, například Bank iD); other (jiným způsobem)
kyc.riskProfilelow (nízké riziko); medium (střední riziko); high (vysoké riziko; subúčet zůstane k posouzení)
consents[].documentframeworkAgreement (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.experiencenone (bez zkušeností); basic (základní zkušenosti); experienced (zkušený investor)
profile.shareOfInvestmentsupTo10Percent (do 10 %); from10To25Percent (10 až 25 %); from25To50Percent (25 až 50 %); over50Percent (nad 50 %)

Stavy subúčtu

StavVý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
  • Čtení zůstatků, obchodů a pokynů funguje v každém stavu kromě rejected (i u ukončeného subúčtu), kde čtení vrací 404 CLIENT_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 stavu review vracejí HTTP 409 CLIENT_RESTRICTED, u blocked 409 CLIENT_BLOCKED, u closed 409 CLIENT_CLOSED. Zamítnutý subúčet vrací při čtení a u pokynů 404 CLIENT_NOT_FOUND, změna údajů 409 CLIENT_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 closed je konečný.

Jak se dozvíte výsledek

  1. Odpověď na založení

    Pole status v odpovědi říká, zda je subúčet hned active, nebo čeká v review.

  2. Webhook

    Při změně stavu pošle Coinero na váš cíl událost subaccount.activated, subaccount.rejected, subaccount.blocked nebo subaccount.closed. Tělem události je objekt subúčtu, týž jako v odpovědi na dotaz. Viz Webhooky.

  3. 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, review i blocked. Zamítnutý subúčet vrací 409 CLIENT_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ým externalClientRef, i lišícím se jen velikostí písmen, vrací 409 CLIENT_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ódStavKdy
CLIENT_REF_CONFLICT409Partner už má subúčet s identifikátorem lišícím se jen velikostí písmen.
CLIENT_NOT_FOUND404Subúčet s tímto identifikátorem klienta partner nemá.
CLIENT_RESTRICTED409Subúčet v tomto stavu nejde měnit ani s ním obchodovat.
CLIENT_BLOCKED409Subúčet je zablokovaný, nejde měnit ani s ním obchodovat.
CLIENT_CLOSED409Subúčet je ukončený, nejde měnit, obchodovat s ním ani ho znovu založit.
CLIENT_STATE_INVALID409Subúčet tuto změnu nepovoluje.
CLIENT_HAS_OPEN_ORDERS409Subúčet nejde ukončit, má otevřený nebo nevypořádaný pokyn.
CLIENT_HAS_POSITIONS409Subúčet nejde ukončit, drží kryptoměnu nebo fiat zůstatek.
PARTNER_SUSPENDED409Partnerský účet je pozastavený nebo ukončený.
PARTNER_BUSY503Coinero 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.