Adresace sites pomocí EAN (CZ)

Přehled

Každý Voke site může nést až dva identifikátory odběrných/výrobních míst českého trhu:

• eanCons — odběrný EAN (consumption EAN), kde elektřina přitéká ze sítě.
• eanProd — výrobní EAN (production EAN), kde elektřina odtéká do sítě.

Oba mají přesně 18 číslic (např. 859182400123456789). Pokud váš systém modeluje zákazníky podle EAN — například z exportu sdílení EDC — můžete adresovat Voke sites přímo pomocí EAN, bez udržování jakékoli mapovací tabulky EAN → site.

Stav měřidla jedním voláním — GET /vcp/meter-state?ean=

Nejrychlejší cesta od „mám EAN" k „co měřidlo právě teď ukazuje":

curl -H "X-API-Key: <your-key>" \
  "https://api.voke.turena.cz/api/v1/vcp/meter-state?ean=859182400123456789"

{
  "siteId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "eanCons": "859182400123456789",
  "eanProd": "859182400987654321",
  "reading": {
    "readingAt": "2026-06-13T15:49:50.355Z",
    "meters": [
      {
        "deviceId": "GRID",
        "role": "GRID",
        "importRegisterKwh": 34897.145,
        "productionRegisterKwh": 109018.273
      }
    ],
    "dataQuality": "GOOD"
  }
}

Chování:

• EAN odpovídá buď eanCons, nebo eanProd některého site ve vaší organizaci.
• Registry jsou absolutní, monotónně rostoucí kWh čítače — rozdíly (deltas) odvodíte odečtením předchozího odečtu.
• reading je null, když není dostatečně čerstvá telemetrie (site offline nebo zatím žádné signály označené registrem).
• Neznámý EAN (nebo EAN patřící jiné organizaci) vrací 404 SITE_NOT_FOUND.
• Chybně tvarovaný EAN (ne přesně 18 číslic) vrací 400 VALIDATION_ERROR.

Vyžaduje scope vcp:read — tentýž klíč, který používáte pro všechna čtení /vcp/sites/*.

Vyhledání v katalogu — GET /vcp/sites?ean=

Pro rozřešení EAN na kompletní záznam site (sub-devices, podporované příkazy, status):

curl -H "X-API-Key: <your-key>" \
  "https://api.voke.turena.cz/api/v1/vcp/sites?ean=859182400123456789"

Odpovědí je standardní výpis elektráren filtrovaný na odpovídající site. Každý site v nefiltrovaném katalogu rovněž nese své eanCons / eanProd, takže jediné nefiltrované GET /vcp/sites při startu vám dá kompletní mapu EAN ↔ siteId.

Neznámý EAN vrací prázdné pole plants (jde o filtr, nikoli o vyhledání — žádné 404).

EANy v AMQP streamu měřidel

1minutový MeterReadingPayload na routing key {slug}.event.telemetry.meter.{siteId} nese eanCons / eanProd daného site přímo v payloadu:

{
  "version": "1.1",
  "siteId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "payload": {
    "readingAt": "2026-06-12T09:00:00.000Z",
    "eanCons": "859182400123456789",
    "eanProd": "859182400987654321",
    "meters": [{ "deviceId": "GRID", "role": "GRID", "importRegisterKwh": 124530.487 }],
    "dataQuality": "GOOD"
  }
}

Konzumenti mohou směrovat odečty do modelu klíčovaného podle EAN bez jediného volání navíc. Pole jsou null u sites, které nemají nakonfigurovaný EAN.

Mohu odebírat stream jednoho EAN?

Ne přímo podle EAN — ale můžete odebírat per site, což vám dá stejný výsledek. Routing key telemetrie nyní končí site UUID (…telemetry.realtime.{siteId} / …telemetry.meter.{siteId}) a exchange vcp je topic exchange, takže můžete navázat (bind) dedikovanou frontu na siteId jedné PLC namísto konzumace sdíleného firehose. Příklad navázání viz Subscribe to one PLC.

EAN není v routing key (je nullable, může se změnit se smlouvou odběrného/výrobního místa a u realtime chybí). Mapování je jeden stabilní krok při startu:

1. Zavolejte jednou GET /vcp/sites a sestavte si mapu EAN → siteId (každý site nese eanCons / eanProd).
2. Navažte frontu na siteId, které vás zajímají — nebo si ponechte výchozí firehose frontu a směrujte v procesu.

Ať zvolíte cokoli, klíčujte svou business logiku podle toho, co je v každé zprávě:

• envelope.siteId — UUID elektrárny, přítomné v každé zprávě (stabilní, nikdy se nemění).
• payload.eanCons / payload.eanProd — přítomné u odečtů měřidel, pro vaše účetnictví klíčované podle EAN.

Tahák identifikátorů