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

Denní report

Report vypíše pokyny a platby za jeden pražský den, abyste je porovnali se svou evidencí, a výsledek porovnání odešlete zpět.

Endpointy

EndpointCo dělá
GET /v1/reports/dailyReport za pražský den v JSON, s hlavičkou Accept: text/csv v CSV.
POST /v1/reports/daily/{date}/resultVýsledek vaší kontroly: match, nebo mismatch se seznamem rozdílů.

Vyžadují partnerský klíč s oprávněním subaccounts a podpis.

Postup každý den

  1. Počkejte na uzávěrku

    Report dne D je konečný od uzávěrky dne D, ve výchozím nastavení ve 3:00 pražského času dne D+1 (pole final a closesAt; přesný okamžik uzávěrky čtěte vždy z closesAt). Dřív ho číst můžete, ale ještě se může měnit.

    Hned po uzávěrce Coinero pošle událost webhooku report.daily.ready s počtem pokynů a plateb dne, a to i za den bez nich. Cíl, který jste nastavili před jejím zavedením, ji nemá ve výběru událostí; o doplnění požádejte Coinero. Bez webhooků se řiďte polem closesAt.

  2. Stáhněte report

    GET /v1/reports/daily?date=YYYY-MM-DD vrací JSON, s hlavičkou Accept: text/csv totéž jako CSV. Hodnotu date převezměte z pole data.date události.

  3. Porovnejte se svou evidencí

    Porovnejte pokyny z reportu s pokyny ve svém systému a platby s bankovním výpisem. Sedět musí každý pokyn, každá platba a jejich součty.

  4. Odešlete výsledek

    POST /v1/reports/daily/{date}/result s match, nebo s mismatch a seznamem rozdílů, nejpozději do 8:00 pražského času. Výsledek je povinná součást procesu: potvrzuje Coineru, že jste den zkontrolovali.

Který den kam patří

  • Den je kalendářní den v pražském čase.
  • Pokyn patří do dne, kdy se jeho obchod dokončil (completedAt), i do dne, kdy byl vypořádán s vámi (settledAt). Pokyn dokončený a vypořádaný v různé dny je v obou reportech.
  • Platba (vaše příchozí platba i výplata, kterou jste od Coinera dostali) patří do dne připsání podle banky (bookingDate), tedy do dne, který vidíte na svém výpisu. Platbu, kterou Coinero zaeviduje až po uzávěrce dne připsání, najdete v reportu dne zaevidování s odkazem na původní pokyn (orderNumber). Uzavřený den se tak nemění.
  • Řazení je deterministické: pokyny podle okamžiku, kterým do dne patří, a čísla pokynu, platby podle času zaevidování, směru a identifikátoru.

Po uzávěrce se report nemění.

Údaje, které se vyvíjejí později (vypořádání pokynu settledAt a settlementSource, vazba na platbu, přiřazení platby allocation, stav výpisu), jsou ve stavu k uzávěrce. Stav obchodu (status, plnění, spent a received) je po dokončení neměnný.

Report v JSON

Odpověď má tvar { date, partner, final, closesAt, closesAtMs, orders, payments, statement }. Částky jsou objekty { amount, currency }, časy ISO 8601 v UTC a v milisekundách. Bez parametru date vrací report předchozího pražského dne. Budoucí den, den před 1. lednem 2020 nebo jiný tvar než YYYY-MM-DD vrací HTTP 400 INVALID_PARAMETER; den před vznikem vašeho účtu vrací prázdné seznamy.

Pokyny (orders)

PolePopis
orderIdIdentifikátor pokynu, stejný jako orderId objektu pokynu.
orderNumberČíslo pokynu, například ABCD-0000001234; jeho číselná část je variabilní symbol platby.
externalClientRefVáš identifikátor klienta subúčtu.
symbolSymbol trhu, například BTCCZK.
sideStrana pokynu.
statusStav pokynu, stejný jako v objektu pokynu. Obchod pokynu v reportu je dokončený.
filledQuantityProvedené množství v základní měně, nebo null. Pole je v odpovědi vždy.
averagePricePrůměrná cena plnění v kotovací měně, nebo null. Pole je v odpovědi vždy.
feeVáš partnerský poplatek za pokyn.
spentCo subúčet utratil.
receivedCo subúčet dostal.
settlementAmountČástka vypořádání mezi vámi a Coinerem: u nákupu kolik platíte, u prodeje čistý výtěžek, který Coinero vyplácí. U pokynu bez plnění null. Pole je v odpovědi vždy.
settlementDirectionSměr settlementAmount, nebo null. Pole je v odpovědi vždy.
completedAtKdy se obchod pokynu dokončil, ISO 8601 v UTC, nebo null. Pole je v odpovědi vždy.
filledAtKdy se pokyn provedl celý, ISO 8601 v UTC, nebo null. Pole je v odpovědi vždy.
settledAtKdy se pokyn s vámi vypořádal, pokud do uzávěrky dne; jinak null. Pole je v odpovědi vždy.
settlementSourceČím se pokyn vypořádal, nebo null, když se do uzávěrky dne nevypořádal. Pole je v odpovědi vždy.
paymentIdPlatba nebo výplata, která pokyn vypořádala (paymentId v payments), nebo null. Pole je v odpovědi vždy.
variableSymbolVariabilní symbol té platby, nebo null. Pole je v odpovědi vždy.
statementNumberČíslo denního výpisu, který pokyn vypořádal, nebo null. Pole je v odpovědi vždy.

Platby (payments)

PolePopis
paymentIdIdentifikátor platby nebo výplaty.
directionSměr platby.
allocationK čemu platba k uzávěrce dne patří.
amountČástka platby.
variableSymbolVariabilní symbol platby, nebo null. Pole je v odpovědi vždy.
bookingDateDatum připsání podle banky, YYYY-MM-DD.
bookedAtKdy Coinero platbu zaevidovalo, ISO 8601 v UTC. Platba zaevidovaná po uzávěrce dne připsání patří do reportu dne zaevidování.
orderNumberPokyn, ke kterému platba patří, i pokyn dřívějšího dne, nebo null. Pole je v odpovědi vždy.
statementNumberDenní výpis, ke kterému platba patří, nebo null. Pole je v odpovědi vždy.

Pole statement je denní výpis, když váš účet vypořádává denním netto, jinak null. Jeho pole jsou v referenci.

settlementSourceVýznam
paymentvaší příchozí platbou
payoutvýplatou vám
statementdenním výpisem
masterCreditz kreditu vašeho účtu
belowMinorUnitbez platby, částka pod jeden haléř

Report v CSV

S hlavičkou Accept: text/csv dostanete táž data jako jeden soubor: kódování UTF-8 s BOM, oddělovač středník, konce řádků CRLF. Soubor má oddíly report, orders, payments a statement; každý začíná řádkem section;<název>, pak následuje hlavička sloupců a řádky, oddíly odděluje prázdný řádek. Hodnoty odpovídají JSON: částky mají desetinnou tečku a sloupec měny, časy jsou ISO 8601 v UTC, hodnoty výčtů v camelCase.

  • Text s oddělovačem nebo uvozovkou je v uvozovkách.
  • Buňka začínající znakem =, +, - nebo @ má na začátku ochranný apostrof, aby ji tabulkový procesor nevyhodnotil jako vzorec. Při strojovém čtení ho odstraňte.
  • Název souboru nese hlavička Content-Disposition: coinero-report-{kód partnera}-{den}.csv.

Výsledek kontroly

POST /v1/reports/daily/{date}/result přijímá tělo { status, differences }.

  • status je match (vše sedí, differences je prázdné nebo chybí), nebo mismatch s 1 až 100 rozdíly.
  • Rozdíl nese orderNumber nebo variableSymbol, druh kind (missingPayment, missingOrder, amountMismatch, duplicatePayment, other), popis description o délce 1 až 300 znaků a volitelně amount. Popis nesmí obsahovat řídicí ani neviditelné formátovací znaky. Osobní údaje do popisu nepište.
  • Celé podepsané tělo má nejvýš 64 KiB. Sto rozdílů s plným popisem v ASCII se vejde, s vícebajtovými znaky nemusí.
  • Výsledek za den D jde poslat až od uzávěrky dne D (closesAt reportu, ve výchozím nastavení 3:00 pražského času dne D+1) a nejvýš 90 dní zpět, jinak HTTP 400 INVALID_PARAMETER s názvem date. Vadné tělo vrací 400 s názvem body, status nebo differences.

Idempotence a přepis

  • Výsledek je jeden na den. Nové odeslání za stejný den předchozí výsledek přepíše (v odpovědi replaced: true).
  • Totožné opakování (stejný stav a stejná množina rozdílů, na pořadí nezáleží) je čistě idempotentní: nic nezmění a nikoho znovu neupozorní. Po výpadku spojení ho proto můžete bezpečně opakovat.
  • Ze dvou současných odeslání za týž den skončí jedno chybou HTTP 409 CONCURRENT_UPDATE; to zopakujte.

Co se stane při rozdílu

mismatch založí u Coinera případ k prověření a upozorní kontakty pro rekonciliaci na obou stranách. match se jen uloží, nikoho neupozorní. Kontakty na vaší straně (nejvýš 5 e-mailových adres) nastavuje Coinero na vaši žádost. Text vašich popisů rozdílů se do e-mailu nedostane. Pozdější match za stejný den případ uzavře, nebo ho jen doplní, pokud ho už Coinero řeší. Při změně obsahu výsledku (jiný stav nebo jiné rozdíly) vznikne případ nebo upozornění znovu.

Chyby

KódStavKdy
INVALID_PARAMETER400Parametr chybí, má nesprávný formát nebo je mimo povolený rozsah.
CONCURRENT_UPDATE409Pokyn nebo zůstatek účtu ve stejnou chvíli změnil jiný požadavek.
SERVICE_MAINTENANCE503API nebo jeho část je dočasně nedostupná kvůli údržbě nebo vypnutí.

Výsledek smí odeslat i pozastavený partner: vypořádání otevřených pokynů běží dál. Při vypnuté partnerské části vrací odeslání výsledku HTTP 503 SERVICE_MAINTENANCE, čtení reportu běží dál.