Overview

Pregled

Backend is Firebase Cloud Functions (v2). There are two transport styles:

Backend su Firebase Cloud Functions (v2). Postoje dva tipa transporta:

• HTTP onRequest: Plain REST (e.g. IoT gatewayPing) — custom headers, JSON body, HTTP status codes. Običan REST (npr. IoT gatewayPing) — custom headeri, JSON body, HTTP status kodovi.
• HTTPS Callable onCall: Firebase Auth ID token automatically attached by the client SDK. Payload wrapped as { "data": { ... } }; response under result. Firebase Auth ID token automatski šalje client SDK. Payload u { "data": { ... } }; odgovor u result.

Base URL pattern for HTTP functions:

Osnovni URL obrazac za HTTP funkcije:

https://us-central1-yosh-digitalchip.cloudfunctions.net/<functionName>

API Catalog

Katalog API-ja

IoT Device Gateway Ping deprecated

Pingovanje IoT uređaja (Gateway) deprecated

The physical controller on-site reports its telemetry. Controllers that are not on the Digi channel can still fetch pending relay commands here.

Fizički kontroler na lokaciji prijavljuje telemetriju. Kontroleri koji nisu na Digi kanalu i dalje mogu ovdje preuzeti komande za releje.

Required Headers

Obavezni headeri

curl -X POST https://us-central1-yosh-digitalchip.cloudfunctions.net/gatewayPing \
  -H "Content-Type: application/json" \
  -H "X-Device-Api-Key: dc_dev_wash_01_api_key_demo_2026" \
  -d '{
    "deviceId": "dev_wash_01",
    "status": "ONLINE",
    "subDevices": [
      { "id": "bay_1", "status": "ACTIVE" },
      { "id": "bay_2", "status": "INACTIVE" }
    ]
  }'

Request Payload

Tijelo zahtjeva (Request Payload)

{
  "deviceId": "dev_wash_01",
  "status": "ONLINE",
  "subDevices": [
    { "id": "bay_1", "status": "ACTIVE" },
    { "id": "bay_2", "status": "INACTIVE" }
  ]
}

Gateway Response

Odgovor mrežnog prolaza

{
  "timestamp": "2026-07-14T10:52:45.312Z",
  "commands": [
    {
      "id": "cmd_8xL92kPz1",
      "action": "START_SERVICE",
      "subDeviceId": "bay_1",
      "value": 50
    }
  ]
}

{
  "timestamp": "2026-07-14T10:52:48.125Z",
  "commands": []
}

IoT Command Stream (gatewayStream) deprecated

IoT stream komandi (gatewayStream) deprecated

Outbound Server-Sent Events (SSE) stream. The controller opens a long-lived connection to the cloud (works behind NAT / without a static IP). When a wash is activated, pending commands are pushed immediately using the same JSON shape as gatewayPing. Keep gatewayPing for telemetry / online status (and as command fallback).

Outbound Server-Sent Events (SSE) stream. Kontroler otvara dugotrajnu konekciju ka cloudu (radi iza NAT-a / bez statične IP). Kad se aktivira pranje, PENDING komande se šalju odmah u istom JSON formatu kao gatewayPing. Zadržite gatewayPing za telemetriju / online status (i kao fallback za komande).

Also accepts POST with JSON body {"deviceId":"..."}. Response Content-Type: text/event-stream. Prihvata i POST sa JSON tijelom {"deviceId":"..."}. Odgovor Content-Type: text/event-stream.

Required Headers

Obavezni headeri

curl -N "https://us-central1-yosh-digitalchip.cloudfunctions.net/gatewayStream?deviceId=dev_wash_01" \
  -H "X-Device-Api-Key: dc_dev_wash_01_api_key_demo_2026" \
  -H "Accept: text/event-stream"

SSE event format

Format SSE događaja

Each command push is one SSE data: line whose JSON matches the gatewayPing response body exactly:

Svaki push komandi je jedna SSE data: linija čiji JSON je identičan tijelu odgovora gatewayPing:

data: {"timestamp":"2026-07-30T04:52:45.312Z","commands":[{"id":"cmd_8xL92kPz1","action":"START_SERVICE","subDeviceId":"bay_1","value":50}]}

: keepalive 2026-07-30T04:53:00.000Z

• commands — same fields as ping (id, action, subDeviceId, value). Marked SENT when pushed.
• commands — ista polja kao ping (id, action, subDeviceId, value). Označene kao SENT kad se pushaju.
• Comment lines (: keepalive …) every ~15s — ignore them; use to detect a live connection.
• Komentar linije (: keepalive …) svakih ~15s — ignorišite ih; služe za detekciju žive veze.
• After ~55 minutes the server may send {"type":"reconnect",…} and close — reconnect immediately.
• Nakon ~55 minuta server može poslati {"type":"reconnect",…} i zatvoriti vezu — odmah se ponovo povežite.

Recommended firmware pattern

Preporučeni pattern u firmveru

1. Open gatewayStream and keep it open; on disconnect, reconnect with backoff. Otvorite gatewayStream i držite otvorenim; na disconnect reconnect sa backoff-om.
2. On each data: JSON with a non-empty commands array, execute commands exactly as for gatewayPing. Na svaki data: JSON sa nepraznim commands, izvršite komande isto kao za gatewayPing.
3. Continue gatewayPing for bay status / Live Tracking (every 3s still OK; with stream you may slow ping to 30–60s if desired). Nastavite gatewayPing za status boksova / Live Tracking (3s i dalje OK; uz stream možete usporiti ping na 30–60s).

EMQX command MQTT deprecated

EMQX MQTT komandi deprecated

For larger fleets (tens to hundreds of controllers), prefer MQTT over polling every 3s or long-lived SSE. The device opens an outbound MQTT connection to a managed broker (e.g. EMQX Cloud). DigitalChip publishes commands when a wash is activated — same JSON as gatewayPing. Keep a slower gatewayPing for bay telemetry / Live Tracking.

Za veće flote (desetine do stotine kontrolera) preferirajte MQTT umjesto pinga svake 3s ili dugog SSE. Uređaj otvara outbound MQTT konekciju ka managed brokeru (npr. EMQX Cloud). DigitalChip publish-uje komande kad se aktivira pranje — isti JSON kao gatewayPing. Zadržite sporiji gatewayPing za telemetriju boksova / Live Tracking.

1. Broker setup (EMQX Cloud)

1. Podešavanje brokera (EMQX Cloud)

1. Create an EMQX Cloud deployment (Serverless is fine to start). Note the mqtts://…:8883 endpoint. Kreirajte EMQX Cloud deployment (Serverless je OK za početak). Zabilježite mqtts://…:8883 endpoint.
2. Create a publisher user (e.g. digitalchip_publisher) with ACL allowing publish to digitalchip/+/commands. Kreirajte publisher korisnika (npr. digitalchip_publisher) sa ACL-om koji dozvoljava publish na digitalchip/+/commands.
3. Add an HTTP authentication authenticator pointing at mqttAuth (below) so devices log in with deviceId + apiKey. Dodajte HTTP authentication authenticator ka mqttAuth (ispod) da se uređaji prijave sa deviceId + apiKey.
4. Device ACL (in EMQX): each client may subscribe only to digitalchip/${username}/commands (and usually not publish). ACL uređaja (u EMQX): klijent smije samo subscribe na digitalchip/${username}/commands (obično bez publish-a).

2. DigitalChip Cloud params

2. DigitalChip Cloud parametri

Set environment params for Cloud Functions (file functions/.env.yosh-digitalchip or Google Cloud Console → Cloud Functions / Cloud Run env):

Postavite env parametre za Cloud Functions (fajl functions/.env.yosh-digitalchip ili Google Cloud Console → Cloud Functions / Cloud Run env):

MQTT_URL=mqtts://xxxxx.emqxsl.com:8883
MQTT_USERNAME=digitalchip_publisher
MQTT_PASSWORD=your_publisher_password

If MQTT_URL is empty, MQTT publish is skipped (no error) — ping/stream keep working.

Ako je MQTT_URL prazan, MQTT publish se preskače (bez greške) — ping/stream i dalje rade.

3. HTTP auth endpoint for EMQX

3. HTTP auth endpoint za EMQX

EMQX sends device credentials. DigitalChip checks devices/{username}.apiKey.

EMQX šalje kredencijale uređaja. DigitalChip provjerava devices/{username}.apiKey.

{
  "username": "dev_wash_01",
  "password": "dc_…",
  "clientid": "dev_wash_01-fw"
}

{
  "result": "allow",
  "is_superuser": false,
  "acl": [
    { "permission": "allow", "action": "subscribe", "topic": "digitalchip/dev_wash_01/commands" },
    { "permission": "deny", "action": "all", "topic": "#" }
  ]
}

Deny / unknown device → {"result":"deny"} (HTTP 200 — EMQX convention).

Deny / nepoznat uređaj → {"result":"deny"} (HTTP 200 — EMQX konvencija).

4. Device MQTT client

4. MQTT klijent na uređaju

5. Message payload (same as gatewayPing)

5. Payload poruke (isti kao gatewayPing)

UTF-8 JSON body on the topic (not wrapped in SSE). Process exactly like a ping response:

UTF-8 JSON na topicu (nije SSE). Obrada identična odgovoru na ping:

{
  "timestamp": "2026-07-30T05:52:45.312Z",
  "commands": [
    {
      "id": "cmd_8xL92kPz1",
      "action": "START_SERVICE",
      "subDeviceId": "bay_1",
      "value": 50
    }
  ]
}

• On successful MQTT delivery the command is marked SENT with deliveredVia: "mqtt".
• Na uspješan MQTT delivery komanda ide u SENT sa deliveredVia: "mqtt".
• Deduplicate by commands[].id (ping/stream/MQTT must not double-fire the same relay).
• Deduplikujte po commands[].id (ping/stream/MQTT ne smiju dvaput okiniti isti relej).
• Reconnect with backoff if the broker drops; keep gatewayPing at 30–60s for online + bay status.
• Reconnect sa backoff-om ako broker padne; držite gatewayPing na 30–60s za online + status boksova.

6. Cloud Functions involved

6. Uključene Cloud Functions

Firmware Integration Flow deprecated

Tok integracije na kontroleru deprecated

Previous stack, only if the controller is still on the gateway channel: EMQX MQTT for commands plus gatewayPing every 30–60s for telemetry. gatewayStream and a 3s ping are older fallbacks, also deprecated.

Prethodni stack, samo ako je kontroler još na gateway kanalu: EMQX MQTT za komande plus gatewayPing svakih 30–60s za telemetriju. gatewayStream i ping na 3s su stariji fallback, takođe deprecated.

1. Boot & Connect Pokretanje i mrežna veza: Connect to network (Wi-Fi/LTE), load the provisioned deviceId + apiKey from secure storage, and sync time. Povežite se na mrežu (Wi-Fi/LTE), učitajte dodijeljeni deviceId + apiKey iz sigurnog skladišta i sinhronizujte sat ako je moguće.
2. MQTT (recommended) MQTT (preporučeno): Connect to the broker with username=deviceId, password=apiKey. Subscribe to digitalchip/{deviceId}/commands. On message, parse JSON and run commands like a ping response. See MQTT section. Konektujte se na broker sa username=deviceId, password=apiKey. Subscribe na digitalchip/{deviceId}/commands. Na poruku parsirajte JSON i izvršite commands kao kod ping odgovora. Vidi MQTT sekciju.
3. Command stream SSE (optional fallback) SSE stream (opcioni fallback): Open gatewayStream if MQTT is unavailable. Process pushed commands the same way. Otvorite gatewayStream ako MQTT nije dostupan. Obradjujte pushane commands isto.
4. Poll Loop (required for telemetry) Petlja pinga (obavezna za telemetriju): deprecated for Digi. Old gateway controllers POST gatewayPing with X-Device-Api-Key. That stamps lastPing. Live Tracking counts those devices online only when that ping is younger than about 3 minutes. Digi devices ignore this ping. deprecated za Digi. Stari gateway kontroleri šalju POST gatewayPing sa X-Device-Api-Key. To upisuje lastPing. Live Tracking te uređaje broji online samo kad je taj ping mlađi od oko 3 minute. Digi uređaji ignorišu ovaj ping.
5. Command Processing Obrada zapovijedi:
   • If `commands` is not empty (from MQTT, ping, or stream), loop through all received command items.
   • Ako niz `commands` nije prazan (iz MQTT, pinga ili streama), prođite kroz sve zapovijedi u petlji.
   • For each command, map the `subDeviceId` to the physical relay port and trigger the relay to generate value pulses (or run for `value` seconds).
   • Za svaku zapovijed, povežite `subDeviceId` sa odgovarajućim fizičkim portom releja i aktivirajte ga tako da generiše value impulsa (ili radi `value` sekundi).
   • Do NOT trigger multiple overlapping activations on the same relay; queue them internally or ignore if busy. Deduplicate by command id.
   • NEMOJTE pokretati više preklapajućih aktivacija na istom releju istovremeno; skladištite ih u internom redu ili ignorišite ako je relej zauzet. Deduplikujte po id zapovijedi.
6. Completion Završetak: There is no callback needed to confirm execution. The server marks commands as SENT when delivering them via MQTT, ping, or stream. Nema potrebe za povratnom potvrdom. Server označava zapovijedi kao SENT kad ih isporuči preko MQTT, pinga ili streama.

Native external app contract

Ugovor za eksternu native aplikaciju

Android, iOS and other clients use the Firebase project yosh-digitalchip, region us-central1. They never open MQTT. Every wash goes through the callables below. Direct Firestore writes to wallets, QR sessions, vehicles and commands are denied.

Android, iOS i ostali klijenti koriste Firebase projekat yosh-digitalchip, region us-central1. Ne otvaraju MQTT. Svako pranje ide kroz callable funkcije ispod. Direktan Firestore upis u novčanike, QR sesije, vozila i komande je zabranjen.

Sign-in

Prijava

QR

QR

The printed code is unchanged: deviceId:subDeviceId. Parse those two ids and send them to the callables. Do not invent a second hardware id.

Odštampani kod se ne mijenja: deviceId:subDeviceId. Raspakujte ta dva id-a i pošaljite ih u callable. Ne uvodite drugi hardverski id.

Wash sequence

Redoslijed pranja

1. createQrSession with deviceId and subDeviceId. On a Digi controller this call asks the machine if that bay is ready before it returns sessionId (300 seconds). Wait for it (about 5 seconds). failed-precondition means the bay is not ACTIVE. deadline-exceeded or unavailable means status did not arrive; do not continue to pay.
2. createQrSession sa deviceId i subDeviceId. Na Digi kontroleru ovaj poziv pita mašinu da li je taj automat spreman prije nego vrati sessionId (300 sekundi). Sačekajte (oko 5 sekundi). failed-precondition znači da automat nije ACTIVE. deadline-exceeded ili unavailable znači da status nije stigao; ne nastavljajte na uplatu.
3. activateService with userId equal to the signed-in uid, tokensToSpend, qrSessionId, optional vehicleId, and usePersonalWallet: true when a B2B employee pays from a personal wallet.
4. activateService sa userId jednakim uid-u prijave, tokensToSpend, qrSessionId, opciono vehicleId, i usePersonalWallet: true kad B2B zaposleni plaća iz ličnog novčanika.
5. On Digi controllers wait for the callable to finish (about 5 seconds). success: true means the machine confirmed and tokens were deducted. remainingBalance is the new balance.
6. Na Digi kontrolerima sačekajte kraj callable-a (oko 5 sekundi). success: true znači da je mašina potvrdila i da su tokeni skinuti. remainingBalance je novo stanje.
7. On deadline-exceeded or unavailable, show the message and retry the same qrSessionId. The wallet was not charged.
8. Na deadline-exceeded ili unavailable prikažite poruku i ponovite isti qrSessionId. Novčanik nije naplaćen.
9. cancelQrSession with { "data": { "sessionId" } } if the user leaves before paying.
10. cancelQrSession sa { "data": { "sessionId" } } ako korisnik ode prije plaćanja.

Reads the app may do itself

Čitanja koja aplikacija smije sama

• users/{uid} — profile. Prefer getUserProfile, updateUserProfile, changeUserPassword, deleteMyProfile.
• users/{uid} — profil. Prednost imaju getUserProfile, updateUserProfile, changeUserPassword, deleteMyProfile.
• wallets/{uid} field balance, and wallets/{uid}/transactions for history. There is no separate wallet callable. Company employees read wallets/{b2bCompanyId} only when rules allow.
• wallets/{uid} polje balance, i wallets/{uid}/transactions za istoriju. Nema posebnog wallet callable-a. Zaposleni čitaju wallets/{b2bCompanyId} samo kad pravila dozvole.
• Vehicles: call listVehicles, createVehicle, updateVehicle, deactivateVehicle, listWashHistory. Clients can read /vehicles but cannot write it.
• Vozila: zovite listVehicles, createVehicle, updateVehicle, deactivateVehicle, listWashHistory. Klijent može čitati /vehicles, ali ne može pisati.

Activation messages

Poruke aktivacije

failed-precondition message is one of: QR_SESSION_REQUIRED, QR_SESSION_INVALID, QR_SESSION_CONSUMED, QR_SESSION_EXPIRED, QR_SESSION_MISMATCH, GUEST_PURCHASE_REQUIRED, GUEST_MUST_SPEND_ALL, GUEST_PERSONAL_WALLET_ONLY, PERSONAL_WALLET_DISABLED, Insufficient tokens in wallet., or the machine error text. Map the codes in the app. Show unknown text as-is.

failed-precondition poruka je jedna od: QR_SESSION_REQUIRED, QR_SESSION_INVALID, QR_SESSION_CONSUMED, QR_SESSION_EXPIRED, QR_SESSION_MISMATCH, GUEST_PURCHASE_REQUIRED, GUEST_MUST_SPEND_ALL, GUEST_PERSONAL_WALLET_ONLY, PERSONAL_WALLET_DISABLED, Insufficient tokens in wallet., ili tekst greške mašine. Mapirajte kodove u aplikaciji. Nepoznat tekst prikažite kakav jeste.

Mobile apps and machine MQTT

Mobilne aplikacije i MQTT mašine

Native and web clients do not open an MQTT connection. The broker address, port and topics live only in Cloud Functions. The app keeps calling the same HTTPS Callable endpoints. On a Digi controller, createQrSession checks that the scanned bay is ready, and activateService checks again and then waits for the machine to confirm payment.

Native i web klijenti ne otvaraju MQTT vezu. Adresa, port i topic-i brokera žive samo u Cloud Functions. Aplikacija i dalje zove iste HTTPS Callable endpoint-e. Na Digi kontroleru createQrSession provjeri da je skenirani automat spreman, a activateService provjeri ponovo i zatim sačeka da mašina potvrdi uplatu.

Endpoints the app calls

Endpoint-i koje aplikacija zove

Base URL for every callable: https://us-central1-yosh-digitalchip.cloudfunctions.net/<name>. Auth and body shape are in Calling HTTPS Callable functions. activateService fields are in activateService.

Bazni URL svakog callable-a: https://us-central1-yosh-digitalchip.cloudfunctions.net/<name>. Auth i oblik tijela su u Pozivanje HTTPS Callable funkcija. Polja activateService su u activateService.

createQrSession

createQrSession

{
  "data": {
    "deviceId": "dev_wash_01",
    "subDeviceId": "bay_1"
  }
}

{
  "result": {
    "success": true,
    "sessionId": "sess_abc123",
    "deviceId": "dev_wash_01",
    "subDeviceId": "bay_1",
    "tenantId": "tenant_wash_central",
    "expiresAt": 1710000000000,
    "expiresInSec": 300
  }
}

Digi result the app must handle

Digi rezultat koji aplikacija mora obraditi

The request and the success body of activateService stay the same. On a Digi controller the call blocks until the machine answers. Success means the machine accepted the payment and tokens were deducted. Failure means nothing was charged and the same qrSessionId can be sent again.

Zahtjev i uspješan odgovor activateService ostaju isti. Na Digi kontroleru poziv traje dok mašina ne odgovori. Uspjeh znači da je mašina prihvatila uplatu i da su tokeni skinuti. Neuspjeh znači da ništa nije naplaćeno i da se isti qrSessionId može poslati ponovo.

const functions = getFunctions();
const session = await httpsCallable(functions, "createQrSession")({
  deviceId, subDeviceId
});
const started = await httpsCallable(functions, "activateService")({
  userId: auth.currentUser.uid,
  deviceId,
  subDeviceId,
  tokensToSpend,
  qrSessionId: session.data.sessionId
});
// started.data.success === true, remainingBalance updated

Device status

Status uređaja

Digi controllers report bay readiness through Cloud Functions. There is no status endpoint for the mobile app and no broker credentials in this document. Super-admin sees every controller. A tenant admin sees only controllers assigned to that tenant.

Digi kontroleri javljaju spremnost automata kroz Cloud Functions. Nema status endpoint-a za mobilnu aplikaciju i nema kredencijala brokera u ovom dokumentu. Super-admin vidi svaki kontroler. Tenant admin vidi samo kontrolere dodijeljene tom tenantu.

Mobile Service Activation

Aktivacija usluge sa mobilne aplikacije

Triggered by the mobile client app to deduct wallet balance and start the machine. On a Digi controller the Cloud Function confirms with the machine before charging (see Mobile MQTT via API). Other controllers still queue a command. Supports corporate B2B rules (time schedules, allowed days, and daily user limits).

Pokreće se iz mobilne aplikacije radi skidanja tokena i pokretanja mašine. Na Digi kontroleru Cloud Function prvo dobije potvrdu mašine, pa tek onda naplati (vidi Mobilni MQTT preko API-ja). Ostali kontroleri i dalje stavljaju komandu u red. Podržava B2B kontrolu limita (dozvoljeni dani, vrijeme rada, dnevni limiti po zaposlenom).

Request Structure (Wrapped in a "data" property)

Struktura zahtjeva (Umotana u "data" objekat)

{
  "data": {
    "userId": "UserUID_12345",
    "deviceId": "dev_wash_01",
    "subDeviceId": "bay_1",
    "tokensToSpend": 5,
    "qrSessionId": "sess_abc123",
    "vehicleId": "veh_xyz"
  }
}

Response Structure (Returned under a "result" property)

Struktura odgovora (Vraća se unutar "result" objekta)

{
  "result": {
    "success": true,
    "message": "Service activated successfully.",
    "commandId": "cmd_act_912384x",
    "value": 50,
    "remainingBalance": 45
  }
}

Calling HTTPS Callable functions

Pozivanje HTTPS Callable funkcija

All onCall functions require a valid Firebase Auth session. Native apps use the Firebase SDK (Android/iOS/Flutter). Raw HTTP clients must send:

Sve onCall funkcije zahtijevaju Firebase Auth sesiju. Native app koristi Firebase SDK. Raw HTTP klijenti šalju:

• Authorization: Bearer <ID_TOKEN>
• Content-Type: application/json
• Body: { "data": { ...params } }

import { getFunctions, httpsCallable } from "firebase/functions";
const fn = httpsCallable(getFunctions(), "getUserProfile");
const { data } = await fn({});

getUserProfile

getUserProfile

Returns the authenticated user's profile. No request fields required.

Vraća profil ulogovanog korisnika. Nema obaveznih polja u zahtjevu.

{
  "success": true,
  "profile": {
    "userId": "abc123",
    "name": "Marko Marković",
    "email": "marko@alphacorp.com",
    "phone": "+38761111222",
    "role": "USER",
    "b2bCompanyId": "comp_alpha",
    "tenantId": null,
    "isGuest": false,
    "emailVerified": false,
    "providers": ["password"]
  }
}

updateUserProfile

updateUserProfile

Updates own name and phone. Cannot change role, email, or org links.

Ažurira vlastito name i phone. Ne mijenja ulogu, email ni org veze.

{
  "data": {
    "name": "Petar Petrović",
    "phone": "+38761123456"
  }
}

changeUserPassword

changeUserPassword

{
  "data": {
    "currentPassword": "oldSecret",
    "newPassword": "newSecret123"
  }
}

onboardEmployee

onboardEmployee

B2B_ADMIN (own company) or SUPER_ADMIN. Creates Auth + Firestore user + wallet if needed, links to company as USER.

B2B_ADMIN (svoja kompanija) ili SUPER_ADMIN. Kreira Auth + Firestore + novčanik ako treba, veže na kompaniju kao USER.

{
  "data": {
    "companyId": "comp_alpha",
    "email": "ana@alphacorp.com",
    "name": "Ana Anić",
    "phone": "+38761123456",
    "password": "Password123!"
  }
}

{
  "success": true,
  "userId": "uid_...",
  "created": true,
  "alreadyLinked": false,
  "email": "ana@alphacorp.com"
}

dispenseTokens

dispenseTokens

Moves tokens from corporate wallet to employee wallet (atomic). B2B_ADMIN of that company or SUPER_ADMIN.

Prenosi tokene s korporativnog na zaposlenički novčanik (atomski). B2B_ADMIN te kompanije ili SUPER_ADMIN.

{
  "data": {
    "fromCompanyId": "comp_alpha",
    "toUserId": "employeeUid",
    "amount": 50
  }
}

{
  "success": true,
  "newBalance": 450,
  "employeeBalance": 50
}

getCompanySpendingReport

getCompanySpendingReport

Lists corporate-wallet DEBIT transactions (who / when / where) plus per-user totals.

Lista DEBIT transakcija korporativnog novčanika (ko / kada / gdje) i totali po korisniku.

{
  "data": { "companyId": "comp_alpha", "limit": 100 }
}

{
  "success": true,
  "companyId": "comp_alpha",
  "companyName": "Alpha Corp",
  "totals": { "gross": 120, "transactionCount": 8 },
  "users": [
    { "userId": "...", "name": "...", "email": "...", "gross": 40, "transactionCount": 3 }
  ],
  "transactions": [
    {
      "id": "...",
      "userId": "...",
      "userName": "...",
      "amount": 5,
      "tenantId": "tenant_wash_central",
      "tenantName": "...",
      "deviceId": "dev_wash_01",
      "subDeviceId": "bay_1",
      "subDeviceName": "Bay 1",
      "timestamp": "2026-07-15T12:00:00.000Z"
    }
  ]
}

createTenantWithAdmin

createTenantWithAdmin

SUPER_ADMIN only. Creates tenant, TENANT_ADMIN Auth user, wallets (tenant balance starts at 0 — tenants sell services).

Samo SUPER_ADMIN. Kreira tenant, TENANT_ADMIN Auth nalog, novčanike (tenant balance počinje na 0 — tenant prodaje usluge).

{
  "data": {
    "tenantId": "tenant_eco_wash",
    "tenantName": "Eco Wash Center",
    "industryType": "CAR_WASH",
    "adminName": "Petar Petrović",
    "adminEmail": "admin@ecowash.com",
    "adminPassword": "Password123!",
    "currency": "BAM",
    "address": "Ulica 1, Sarajevo",
    "jib": "4200123450001",
    "platformFeePercent": 12.5
  }
}

updateTenantFeeTerms

updateTenantFeeTerms

SUPER_ADMIN only. Sets tenants/{tenantId}.platformFeePercent (0–100). Used by getEarningsReport. Clients cannot write this field (Firestore rules).

Samo SUPER_ADMIN. Postavlja tenants/{tenantId}.platformFeePercent (0–100). Koristi getEarningsReport. Klijent ne može pisati ovo polje (Firestore rules).

// Request
{ "data": { "tenantId": "tenant_eco_wash", "platformFeePercent": 10 } }

// Response
{ "success": true, "tenantId": "tenant_eco_wash", "platformFeePercent": 10 }

rotateDeviceApiKey

rotateDeviceApiKey

SUPER_ADMIN or owning TENANT_ADMIN. Issues a new apiKey for devices/{deviceId}. Old key stops working on gatewayPing.

SUPER_ADMIN ili vlasnički TENANT_ADMIN. Izdaje novi apiKey za devices/{deviceId}. Stari ključ prestaje raditi na gatewayPing.

// Request
{ "data": { "deviceId": "dev_wash_01" } }

// Response
{ "success": true, "deviceId": "dev_wash_01", "apiKey": "dc_a1b2c3..." }

getEarningsReport

getEarningsReport

Aggregates DEBIT spend by tenant → device → sub-device. Fee = each tenant’s platformFeePercent (default 15% if missing). Totals sum per-tenant fee math. SUPER_ADMIN (optional tenantId filter) or TENANT_ADMIN (own tenant only).

Agregira DEBIT potrošnju tenant → uređaj → poduređaj. Fee = platformFeePercent po tenantu (podrazumevano 15% ako nedostaje). Totals su zbir po tenantima. SUPER_ADMIN (opcionalni filter tenantId) ili TENANT_ADMIN (samo svoj tenant).

{
  "data": { "tenantId": "tenant_wash_central" }
}

{
  "success": true,
  "platformFeePercent": 12.5,
  "defaultPlatformFeePercent": 15,
  "transactionCount": 42,
  "totals": { "gross": 1000, "platformFee": 125, "net": 875, "transactionCount": 42 },
  "tenants": [
    {
      "tenantId": "tenant_wash_central",
      "tenantName": "Wash Central",
      "platformFeePercent": 12.5,
      "gross": 1000,
      "platformFee": 125,
      "net": 875,
      "transactionCount": 42,
      "devices": [
        {
          "deviceId": "dev_wash_01",
          "gross": 1000,
          "platformFee": 125,
          "net": 875,
          "platformFeePercent": 12.5,
          "subDevices": [
            { "subDeviceId": "bay_1", "name": "Bay 1", "gross": 600, "platformFee": 75, "net": 525, "platformFeePercent": 12.5 }
          ]
        }
      ]
    }
  ]
}

Vehicles API (mobile-ready)

API vozila (za mobilnu app)

Collection /vehicles/{vehicleId}. Client writes denied — all mutations via callables. Wash ledger stores vehicleId + vehiclePlate on DEBIT txs.

Kolekcija /vehicles/{vehicleId}. Client write zabranjen — mutacije preko callable. Ledger čuva vehicleId + vehiclePlate na DEBIT tx.

listVehicles

{ "companyId": "comp_alpha" }  // omit → personal vehicles
// includeInactive?: boolean
// Auth: personal owner; company members; SUPER_ADMIN

createVehicle

{ "plate": "A12-B-345", "label": "Van 1", "companyId": "comp_alpha" }
// omit companyId → personal vehicle for caller
// companyId → B2B_ADMIN of company or SUPER_ADMIN

updateVehicle / deactivateVehicle

{ "vehicleId": "...", "plate": "...", "label": "...", "active": true }
{ "vehicleId": "..." }  // deactivateVehicle → active:false

getVehicleWashStats

{ "companyId": "comp_alpha" }
// B2B_ADMIN / SUPER → per-vehicle washCount, tokensSpent, lastWashAt

listWashHistory

{ "vehicleId": "optional", "limit": 50 }
// Caller DEBITs (personal wallet or company wallet where userId=caller)
// Filter by vehicleId when set

Admin / B2B / Device Mutations

Admin / B2B / Device mutacije

All platform writes used by the PWA (and native apps) go through these callables — not direct Firestore client writes.

Sve platformerske mutacije koje koristi PWA (i native appovi) idu preko ovih callable funkcija — ne direktnim Firestore write-ovima sa klijenta.

createB2bCompany

{
  "companyId": "comp_alpha",
  "name": "Alpha Corp",
  "adminEmail": "admin@alphacorp.com",
  "initialBalance": 500,
  "dailyLimit": 50,
  "currency": "BAM",
  "address": "Ulica 1",
  "jib": "4200123450001"
}

updateSpendingRules

{
  "companyId": "comp_alpha",
  "rules": {
    "startTime": "08:00",
    "endTime": "20:00",
    "dailyLimit": 50,
    "allowedDays": [1, 2, 3, 4, 5]
  }
}

registerDevice

{
  "deviceId": "dev_wash_02",
  "tenantId": "tenant_wash_central",
  "firmwareVersion": "1.0.0",
  "status": "OFFLINE"
}
/* Response includes server-generated apiKey */

registerSubDevice

{
  "deviceId": "dev_wash_02",
  "subDeviceId": "bay_3",
  "name": "Bay 3",
  "qrCodePayload": "bay_3",
  "pulsePerToken": 10
}

adminUpdateUser / creditUserWallet / creditOwnWallet

/* adminUpdateUser — SUPER_ADMIN */
{ "userId": "...", "role": "B2B_ADMIN", "b2bCompanyId": "comp_alpha", "tenantId": null }

/* creditUserWallet — SUPER_ADMIN */
{ "userId": "...", "amount": 100 }

/* creditOwnWallet — any signed-in user */
{ "amount": 10, "replace": false }

Other mutation IDs

Ostali mutacijski ID-jevi

deleteB2bCompany · assignCompanyAdmin · removeCompanyEmployee · deleteDevice · deleteSubDevice · linkDeviceToTenant · deleteUserAccount · deleteTenantCascade · updateTenantFeeTerms

Error Handling & Status Codes

Rukovanje greškama i statusni kodovi

HTTP gatewayPing / gatewayStream

HTTP gatewayPing / gatewayStream

• 200 OK — Ping OK; inspect commands.Ping OK; pregledaj commands.
• 400 — Invalid payload.Neispravan payload.
• 401 — Missing/invalid X-Device-Api-Key.Nedostaje/neispravan X-Device-Api-Key.
• 404 — Unknown device (devices are not auto-created from ping).Nepoznat uređaj (ping ne kreira uređaj automatski).
• 405 — Method not POST.Metoda nije POST.
• 500 — Server error — retry with backoff.Serverska greška — ponovi sa backoff-om.

HTTPS Callable (onCall)

HTTPS Callable (onCall)

Errors throw Firebase HttpsError. Client SDKs expose code and message.

Greške bacaju Firebase HttpsError. Client SDK vraća code i message.