Partner API — Přehled (CZ)
Jak se ESM partner připojí k Voke — dva transporty, sedm rodin zpráv, HTTP reverzní kanál, kterým Voke volá zpět k vám, a kam jít pro jednotlivé detaily.
Přehled Partner API
Tato stránka je mapa. Pojmenovává oblasti, které partnerský integrátor potřebuje znát — dva transporty, rodiny zpráv proudící každým směrem a HTTP kanál, kterým Voke volá zpět do vaší platformy. Každá sekce končí odkazy na dedikovanou stránku, kde najdete detaily na úrovni wire formátu.
Spustitelné příklady na GitHubu: lefteq/voke-partner-examples
obsahuje ověřené Java (Spring Boot) a TypeScript klienty pokrývající vše na těchto stránkách —
AMQPS telemetrii, REST čtení i HMAC-podepsané příkazy. Stačí naklonovat a spustit.
Jste ESM
ESM (energy system management) partner je externí platforma, která posílá optimalizační příkazy energetickým aktivům — solárním střídačům, bateriovým systémům, EV nabíječkám — a konzumuje telemetrii, alarmy a výsledky příkazů, které tato aktiva produkují. Voke sedí mezi vámi a hardwarem.
Hranice rozsahu je pevná: Voke se stará o broker, perzistenci a doručení na poslední míli k plantám. Nikdy se nepřipojujete k Mosquitto. S Voke komunikujete ve wire formátu Voke (VCP); jeden credential bundle vám dá oba transporty.
Kde začít. Pokud vám admin vaší organizace vyprovisioval API key, bundle, který vám předal
(AMQPS URI + raw key + signing key), je vše, co potřebujete — přejděte na
Quick start. Pokud ne, požádejte ho, aby prošel
/orgs/<orgId>/settings/connections?tab=api-keys → Connect partner.
Připojujete se přes AMQPS + REST
Produkční partneři používají dva transporty proti stejné sadě veřejných hostname.
| Transport | Endpoint | Přenáší |
|---|---|---|
| AMQPS | amqp.voke.turena.cz:5671 | Veškerou realtime výměnu zpráv — příkazy, které publikujete, a události, které Voke publikuje zpět |
| REST | https://api.voke.turena.cz/api/v1/vcp/sites | Historickou telemetrii, konfiguraci site, odečty měřičů, schedules, historii příkazů |
Admin vaší organizace vytvoří jediný API key pro vaši integraci přes wizard Connect partner. Reveal obrazovka vrátí bundle obsahující AMQPS URI (org slug jako username, key jako password, per-key vhost partner-{keyId} jako path — vše předem zakódované), raw API key a — pro organizace s write scopes — HMAC signing key. Bundle se zobrazí přesně jednou.
→ Detaily autentizace: API keys & auth · REST authentication · AMQP authentication
Co posíláte do Voke
Tři rodiny zpráv putují směrem partner → Voke přes AMQPS. Každá rodina má vlastní dedikovanou frontu a rodinu routing-key s prefixem org slug.
| Rodina | Fronta | Příklady routing keys |
|---|---|---|
| Command | vcp.{slug}.command | {slug}.command.site-setpoint, {slug}.command.device, {slug}.command.emergency |
| Config | vcp.{slug}.config | {slug}.config.constraints, {slug}.config.topology, {slug}.config.fallback |
| Schedule | vcp.{slug}.schedule | {slug}.schedule.create, {slug}.schedule.cancel |
Site setpointy jsou autentizovány samotnou AMQP credential dvojicí a scope vcp:write:setpoint. Rizikovější routy (command.device, command.mode, schedule.*) navíc vyžadují HMAC podpis.
→ Commands · VCP data model · VCP message integrity
Co přijímáte od Voke
Čtyři rodiny zpráv putují směrem Voke → partner na dedikovaných outbound frontách. Vy konzumujete; Voke publikuje.
| Rodina | Fronta | Příklady routing keys |
|---|---|---|
| Telemetry | vcp.{slug}.event.telemetry | {slug}.event.telemetry.realtime.{siteId}, {slug}.event.telemetry.meter.{siteId} |
| Status (ACK / NACK) | vcp.{slug}.event.status | {slug}.event.command.ack, {slug}.event.mode.*, {slug}.event.schedule.* |
| Alarm | vcp.{slug}.event.alarm | {slug}.event.alarm.* |
| Execution | vcp.{slug}.event.execution | {slug}.event.execution.* |
Telemetry pokrývá jak realtime vzorky, tak 1minutové odečty měřičů. Status nese lifecycle pro každý příkaz, který publikujete — ACK/NACK plus přechody stavů mode a schedule. Alarm pokrývá provozní alarmy, které Voke vyvolá proti site. Execution nese aktualizace průběhu pro odeslané příkazy.
→ Telemetry ingress · Alarms · Errors & retries
Co Voke stahuje od vás (HTTP reverzní kanál)
Kromě výměny zpráv přes AMQPS volá Voke periodicky HTTP API vašeho ESM, aby získalo konfiguraci site a time-block schedules. Jde o reverzní kanál — Voke je HTTP klient, vy jste server.
Vaše ESM musí vystavit čtyři endpointy pod libovolnou base URL, kterou Voke předáte při onboardingu:
| Metoda | Path | Účel |
|---|---|---|
POST | /trading/token | Token endpoint. Přijímá JSON { clientId, clientSecret }; vrací { accessToken, expiresIn }. Token je JWT, který Voke používá jako bearer credential na zbývajících třech endpointech. |
GET | /trading/plant/list | Vypíše planty, které vaše ESM spravuje pro tuto organizaci. |
GET | /trading/plant/config?plantId={externalId} | Vrací aktuální time-config bloky (např. povolená okna nabíjení/vybíjení + SOC limity) pro plant. |
POST | /trading/plant/config/update | Přijímá config-update požadavek a vrací result code (terminal / non-terminal). |
Admin vaší organizace zaregistruje ESM API URL, client ID a client secret na straně Voke jednou; od té chvíle Voke tyto endpointy volá podle rozvrhu.
Dále: Quick start
Quick start vás provede od nuly k živé telemetrii za zhruba 15 minut s využitím sandboxu Voke ESM zabudovaného v každém nasazení Voke — bez reálného partnerského hardwaru.