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
| Endpoint | Co dělá |
|---|---|
| GET /v1/reports/daily | Report za pražský den v JSON, s hlavičkou Accept: text/csv v CSV. |
| POST /v1/reports/daily/{date}/result | Vý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
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
finalaclosesAt; přesný okamžik uzávěrky čtěte vždy zclosesAt). 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.readys 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 polemclosesAt.Stáhněte report
GET /v1/reports/daily?date=YYYY-MM-DD vrací JSON, s hlavičkou
Accept: text/csvtotéž jako CSV. Hodnotudatepřevezměte z poledata.dateudálosti.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.
Odešlete výsledek
POST /v1/reports/daily/{date}/result s
match, nebo smismatcha 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í.
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)
| Pole | Popis |
|---|---|
orderId | Identifikátor pokynu, stejný jako orderId objektu pokynu. |
orderNumber | Číslo pokynu, například ABCD-0000001234; jeho číselná část je variabilní symbol platby. |
externalClientRef | Váš identifikátor klienta subúčtu. |
symbol | Symbol trhu, například BTCCZK. |
side | Strana pokynu. |
status | Stav pokynu, stejný jako v objektu pokynu. Obchod pokynu v reportu je dokončený. |
filledQuantity | Provedené množství v základní měně, nebo null. Pole je v odpovědi vždy. |
averagePrice | Průměrná cena plnění v kotovací měně, nebo null. Pole je v odpovědi vždy. |
fee | Váš partnerský poplatek za pokyn. |
spent | Co subúčet utratil. |
received | Co 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. |
settlementDirection | Směr settlementAmount, nebo null. Pole je v odpovědi vždy. |
completedAt | Kdy se obchod pokynu dokončil, ISO 8601 v UTC, nebo null. Pole je v odpovědi vždy. |
filledAt | Kdy se pokyn provedl celý, ISO 8601 v UTC, nebo null. Pole je v odpovědi vždy. |
settledAt | Kdy 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. |
paymentId | Platba nebo výplata, která pokyn vypořádala (paymentId v payments), nebo null. Pole je v odpovědi vždy. |
variableSymbol | Variabilní 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)
| Pole | Popis |
|---|---|
paymentId | Identifikátor platby nebo výplaty. |
direction | Směr platby. |
allocation | K čemu platba k uzávěrce dne patří. |
amount | Částka platby. |
variableSymbol | Variabilní symbol platby, nebo null. Pole je v odpovědi vždy. |
bookingDate | Datum připsání podle banky, YYYY-MM-DD. |
bookedAt | Kdy Coinero platbu zaevidovalo, ISO 8601 v UTC. Platba zaevidovaná po uzávěrce dne připsání patří do reportu dne zaevidování. |
orderNumber | Pokyn, ke kterému platba patří, i pokyn dřívějšího dne, nebo null. Pole je v odpovědi vždy. |
statementNumber | Denní 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.
| settlementSource | Význam |
|---|---|
payment | vaší příchozí platbou |
payout | výplatou vám |
statement | denním výpisem |
masterCredit | z kreditu vašeho účtu |
belowMinorUnit | bez 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 }.
statusjematch(vše sedí,differencesje prázdné nebo chybí), nebomismatchs 1 až 100 rozdíly.- Rozdíl nese
orderNumbernebovariableSymbol, druhkind(missingPayment,missingOrder,amountMismatch,duplicatePayment,other), popisdescriptiono 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 (
closesAtreportu, ve výchozím nastavení 3:00 pražského času dne D+1) a nejvýš 90 dní zpět, jinak HTTP 400INVALID_PARAMETERs názvemdate. Vadné tělo vrací 400 s názvembody,statusnebodifferences.
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ód | Stav | Kdy |
|---|---|---|
INVALID_PARAMETER | 400 | Parametr chybí, má nesprávný formát nebo je mimo povolený rozsah. |
CONCURRENT_UPDATE | 409 | Pokyn nebo zůstatek účtu ve stejnou chvíli změnil jiný požadavek. |
SERVICE_MAINTENANCE | 503 | API 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.