Beheer-API voor werkruimten

Met de Beheer-API voor werkruimten kunnen server-naar-serverintegraties één EVCharge-werkruimte beheren. Deze documentatie is bedoeld voor werkruimtebeheerders en externe API-integratoren. De API gebruikt intrekbare, aan werkruimten gebonden toegangstokens en fijnmazige scopes; inlogtokens van klanten en browsersessies worden niet geaccepteerd.

Deze map is de gezaghebbende ontwikkelaarsreferentie voor de /v2/admin-API die door app-api is geïmplementeerd. De map documenteert geen klant-/mobiele routes of de eigen HTTP-routes van het beheerportaal.

• Eindpuntverzoeken en -antwoorden bevat alle 87 geregistreerde eindpunten, scopes, parameters, verzoekbodies en succesbodies.
• Schema's en voorbeelden definieert herbruikbare verzoek-/antwoordtypen en representatieve JSON-bodies.
• Antwoord- en foutcontract definieert elke gedeelde en eindpuntspecifieke body bij mislukking.

Basis-URL en resourcegrens

Alle routes zijn relatief aan de oorsprong van de geïmplementeerde app-api:

https://api.evcharge.mobi/v2/admin/...

De werkruimte-ID wordt niet geaccepteerd in de URL, querystring of verzoekbody. Elk toegangstoken is aan precies één werkruimte gebonden en de API leidt cpoId af van de geauthenticeerde tokenidentiteit. Als een geneste locatie, lader, gebruiker, tarief, profiel, toewijzing of transactie niet bij die werkruimte hoort, retourneert de API hetzelfde 404 RESOURCE_NOT_FOUND-antwoord dat het bestaan van resources niet onthult.

Een toegangstoken verkrijgen

Een beheerder van de werkruimte maakt tokens aan in Werkruimte-instellingen onder API-toegang. Tokenbeheer is bewust niet beschikbaar voor werkruimtetokens.

• API-toegang is inbegrepen in elk abonnement, ook Free. De beheerder moet rechten hebben om de werkruimte te bewerken.
• De aanbieder van de werkruimte moet de beheer-API inschakelen via adminApiEnabled; anders ontvangt een geldig token een 404 van app-api zonder dat het bestaan van resources wordt onthuld.
• De beheerder kan alleen scopes toekennen die zijn toegestaan op basis van de eigen huidige rechten en de functierechten van de werkruimte.
• Nieuwe tokens kunnen onbeperkt geldig zijn (de standaard in Werkruimte-instellingen) of een door de beheerder gekozen geldigheidsduur van 1 tot 365 hele dagen hebben; de server berekent eindige absolute vervaltijden. Tokens zonder vervaldatum blijven geldig totdat ze worden ingetrokken.
• Een werkruimte kan maximaal 50 actieve tokens hebben.
• De referentie in leesbare vorm wordt één keer getoond. Sla deze direct op in een geheimenbeheerder.
• Naam, scopes en vervaldatum zijn onveranderlijk. Maak voor rotatie een vervanger aan, neem deze in gebruik, controleer deze en trek het oude token in.
• Intrekking gaat direct in; ingetrokken records blijven zichtbaar als onveranderlijke, afgeschermde werkruimtegeschiedenis. Er is geen eindpunt voor bearer-tokenintrospectie of definitief verwijderen.

app-api heeft geen eindpunt dat deze referenties uitgeeft, vernieuwt, opsomt of intrekt. Het verkrijgen van het token is daarom een voorwaarde die via het menselijke beheerportaal wordt uitgevoerd, niet via een ander eindpunt in deze referentie.

Plaats het token nooit in versiebeheer, URL's, querystrings, cookies, logboeken, analytics of foutrapporten.

Authenticatie

Stuur bij elk verzoek precies één header volgens RFC 6750:

Authorization: Bearer evc_ws_<selector>.<secret>

De exacte ondoorzichtige referentie bestaat uit evc_ws_, gevolgd door een canonieke base64url-selector van 16 tekens, . en een canoniek base64url-geheim van 43 tekens. Verstuur de volledige referentie ongewijzigd; codeer deze niet opnieuw met base64.

De API weigert dubbele autorisatieheaders, met komma's samengevoegde waarden, andere schema's, lege bearer-waarden, klant-JWT's en referenties die ergens anders dan in deze header worden aangeleverd.

Onjuist gevormde, onbekende, verlopen, ingetrokken of anderszins ongeldige tokens krijgen allemaal hetzelfde antwoord:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer
Cache-Control: no-store
Content-Type: application/json

{
  "error": "Unauthorized",
  "code": "INVALID_WORKSPACE_TOKEN"
}

De dienst controleert bij elk verzoek de tokenstatus en de huidige werkruimtefunctierechten. Het verwijderen van een functierecht kan de betrokken scopes dus uitschakelen voordat het token verloopt.

Werkruimtetokens zijn ondoorzichtige referenties, geen JWT's. Ze hebben geen refreshtoken en er is geen vernieuwingseindpunt. Een tijdelijk token stopt met authenticeren op zijn absolute expiresAt; een token zonder vervaldatum blijft geldig totdat het wordt ingetrokken. Rotatie betekent een vervangende referentie in het portaal aanmaken, deze in de client in gebruik nemen en de oude referentie intrekken.

Verzoekconventies

• Gebruik Content-Type: application/json voor verzoeken met een JSON-body.
• Spaties aan het begin en einde van optionele X-Request-Id-verzoekwaarden worden verwijderd. De waarden worden alleen geaccepteerd als ze 1–128 tekens uit A-Z, a-z, 0-9, ., _, : of - bevatten; anders genereert de server een UUID. Elk antwoord retourneert de gekozen waarde als X-Request-Id.
• Optioneel X-Error-Format: envelope zet elk JSON-foutantwoord om naar het gestructureerde omhulsel dat wordt beschreven in Antwoord- en foutcontract. Elke andere waarde behoudt de standaardcompatibiliteitsbody.
• ID's in padparameters zijn positieve gehele getallen. Toegangstoken-ID's die het portaal retourneert zijn decimale tekenreeksen, omdat het databasewaarden van 64 bits zonder teken zijn.
• Datum-tijdwaarden zijn RFC 3339-tekenreeksen met een expliciete tijdzone-offset, bijvoorbeeld 2026-08-13T12:30:00Z.
• Geslaagde verwijderacties retourneren normaal gesproken 204 No Content.
• Aanmaakbewerkingen retourneren normaal gesproken 201 Created.
• OCPP-werk dat alleen in de wachtrij is geplaatst, kan 202 Accepted retourneren; beschouw dit niet als bevestiging van de lader, tenzij het antwoord dat expliciet vermeldt.
• Geauthenticeerde antwoorden gebruiken Cache-Control: no-store. Eindpunten voor QR en rapportexport retourneren binaire bodies met expliciete inhoudsheaders.
• Toegestane browseroorsprongen kunnen via CORS X-Request-Id, Idempotency-Replayed, Retry-After en Content-Disposition lezen. Hiermee kunnen browserclients verzoeken aan elkaar koppelen, idempotente herhalingen herkennen, de wachttijd voor nieuwe pogingen naleven en door de server gekozen downloadbestandsnamen behouden.

Idempotentie

Alle POST-, PUT-, PATCH- en DELETE-beheerverzoeken moeten één Idempotency-Key-header bevatten. Sleutels bevatten 1–255 zichtbare tekens en zijn gebonden aan het token, de methode en het pad.

Idempotency-Key: provisioning-2026-08-13-site-42

Hergebruik van een voltooide sleutel met dezelfde URL en body herhaalt het opgeslagen antwoord en voegt toe:

Idempotency-Replayed: true

Hergebruik van een sleutel met een ander verzoek retourneert 409 IDEMPOTENCY_CONFLICT. Een verzoek dat nog wordt verwerkt retourneert 409 IDEMPOTENT_REQUEST_PROCESSING met Retry-After: 5.

Voltooide antwoorden en definitieve resultaten worden zeven dagen na hun laatste update bewaard voor herhaling of afstemming. Na die bewaartermijn kan dezelfde sleutel als een nieuwe opdracht worden behandeld. Clients moeten daarom wereldwijd unieke sleutels gebruiken en mogen deze niet bewust hergebruiken.

Als de verwerkingsreservering verloopt, de verbinding na het starten van de uitvoering sluit of de bewerking een serverfout retourneert, kan de API niet veilig vaststellen of een extern effect is opgetreden. Tijdens de bewaartermijn van zeven dagen blijft de sleutel definitief onbepaald en retourneert deze 409 IDEMPOTENCY_OUTCOME_UNKNOWN; de sleutel wordt niet opnieuw geclaimd en de bewerking wordt niet automatisch opnieuw uitgevoerd. Controleer de effecten van de bewerking voordat u handmatig herstel uitvoert en dien dezelfde bewerking niet onder een nieuwe sleutel in voordat die afstemming is afgerond.

Alle muterende beheereindpunten, waaronder POST /reports/send, vereisen Idempotency-Key.

Verzoeklimieten

Limieten gelden zowel voor het afzonderlijke token als voor de werkruimte. De vastgelegde standaardwaarden zijn:

Een begrensd verzoek retourneert 429 Too Many Requests en een Retry-After-header. Deze waarden kunnen per implementatie worden overschreven.

Fouten

JSON-fouten gebruiken een stabiele code wanneer de aanroepende toepassing een vervolgstap moet kiezen:

{
  "error": "Insufficient workspace-token scope",
  "code": "INSUFFICIENT_SCOPE"
}

Validatiefouten gebruiken veldarrays:

{
  "validationErrors": {
    "name": ["String must contain at least 1 character(s)"]
  }
}

Veelvoorkomende statussen zijn:

Scopecatalogus

De volgende scopecatalogus wordt gebruikt wanneer een beheerder een token aanmaakt. Een schrijf- of impactvolle scope kan de bijbehorende leesscope impliceren, maar leesscopes geven nooit schrijfrechten. Beschikbare scopes hangen af van de rechten van de beheerder en de ingeschakelde werkruimtefuncties.

API-toegang zelf is inbegrepen in elk abonnement en wordt geregeld door de instelling adminApiEnabled van de aanbieder. De aanvullende functierechten hierboven blijven gelden; API-toegang geeft geen toegang tot functies buiten het abonnement van de werkruimte.

Eindpuntreferentie

De onderstaande tabellen bevatten alle 87 beheerroutes voor werkruimten. Als een cel meerdere scopes bevat, zijn ze allemaal vereist.

Werkruimte

Patchvelden voor werkruimten: name, email, website, addressLine1, addressLine2, postalCode, city, state en countryId. Minstens één veld is vereist. Lege tekenreeksen die null mogen zijn, worden genormaliseerd naar null.

Locaties en vermogensbeheer

Bodies voor het aanmaken en patchen van locaties gebruiken:

{
  "name": "Main depot",
  "description": null,
  "addressLine1": "1 Example Street",
  "addressLine2": null,
  "postalCode": "LV-1001",
  "city": "Riga",
  "state": null,
  "countryId": 1,
  "timezoneId": 1,
  "latitude": 56.9496,
  "longitude": 24.1052
}

Geocodering van locaties accepteert de optionele queryvelden street, city, state, country en de tweeletterige countryCode, plus de verzoekheader Accept-Language. De gecombineerde zoekopdracht voor straat/plaats/provincie moet ten minste twee tekens bevatten. Antwoorden bevatten alleen placeId, displayName, latitude en longitude; providerreferenties en providerspecifieke metagegevens worden niet getoond. De server gebruikt de gedeelde providerwachtrij van één verzoek per seconde, een time-out van acht seconden, een begrensde cache van 24 uur en globale verzoeklimieten voor werkruimtetokens.

Vermogensbeheer accepteert { "pools": [...] }. Een laadgroep heeft id, name, limit, optioneel meterSources en recursieve children. Een onderliggende lader heeft chargepointId en priority. De API begrenst de boomstructuur en het aantal meters en voert bij vervanging van de geïnstalleerde toestand een tweefasige OCPP-wisactie en hercontrole uit. Een geweigerde, verlopen of door gelijktijdige wijzigingen ingehaalde wijziging retourneert 409 POWER_MANAGEMENT_CONFLICT en behoudt de vorige configuratie.

Laders

Queryparameters voor laderlogboeken zijn cursor, limit (standaard 50, maximaal 200), from, to, action, direction en levelId. Sessieparameters zijn page, limit (standaard 25, maximaal 100), from, to en customerId (een positieve ID of unknown). De geschiedenis van samengestelde schema's gebruikt cursor, limit (standaard 20, maximaal 50) en optioneel connectorId.

Rapporten

Filters voor rapportgegevens en export zijn from, to, siteId, chargerId, userId, anonymous en active. from/to gebruiken standaard de laatste 90 dagen en mogen niet meer dan 90 dagen omvatten. userId kan niet met anonymous=true worden gecombineerd.

• Gegevenspaginering: ondoorzichtige cursor, standaard limit=50, maximaal 100.
• Metingen: vereist transactionLogId, ondoorzichtige cursor, standaard limit=500, maximaal 1.000.
• Export: format=csv|pdf, standaard csv, harde limiet van 2.000 rijen.
• Exportantwoorden gebruiken Content-Disposition: attachment, Cache-Control: private, no-store en X-Content-Type-Options: nosniff.

Schemabody:

{
  "enabled": true,
  "recipientEmail": "reports@example.com",
  "format": "csv",
  "sendDay": 5,
  "sendTime": "08:30"
}

sendDay is 1–28 en sendTime wordt in UTC geïnterpreteerd. De planner haalt een gemiste geplande minuut in tijdens de huidige bezorgmaand. Mislukte opbouwpogingen vóór de overdracht worden na 5 en 10 minuten herhaald; een onderbroken building-claim kan na 30 minuten opnieuw worden geclaimd en automatische bezorging stopt na drie pogingen. De planner slaat indeterminate direct vóór overdracht aan SMTP op; zowel indeterminate als de oude status sending zijn definitief, omdat automatisch herhalen van beide een dubbele bijlage kan versturen. Exploitanten moeten deze resultaten handmatig afstemmen voordat ze de schemastatus wijzigen. Elke cyclus selecteert maximaal tien schema's, stopt na een budget van 45 seconden met het starten van nieuw werk en gebruikt begrensde SMTP-time-outs. De taak is standaard uitgeschakeld en moet expliciet worden ingeschakeld na validatie van SMTP en capaciteit. Het API-schema is eigendom van de werkruimte en leent niet de identiteit van de persoon die het token heeft aangemaakt.

Tarieven

Een tariefbody bevat name, precies één van currencyId, currencyCode of currency, optioneel biddingZoneId en tax. Een toewijzingsbody is:

{ "tariffId": 17, "connectorId": 0 }

Bij het aanmaken van een toewijzing geldt het tarief voor alle fysieke connectoren als connectorId wordt weggelaten of expliciet op 0 wordt ingesteld. Een toewijzingsupdate richt zich op één opgeslagen toewijzing en vereist daarom een expliciete positieve fysieke connectorId; 0 wordt geweigerd.

Een component bevat de verplichte velden typeId, seasonId en price; priority en geldigheidsgrenzen voor maanden, weekdagen en uren zijn optioneel.

Laadprofielen

Metagegevensvelden van een profiel zijn label, locationId, stackLevel, purposeId, kindId, optioneel recurrencyKindId, validFrom, validTo, startSchedule, rateUnitId en optioneel minChargingRate. Een schemaperiode bevat startPeriod, limit en optioneel numberOfPhases. Een toewijzingsbody bevat profileId en connectorId (standaard 0).

Profielen verwijderen en vermogensbeheer vervangen kan wachten op bevestiging van de lader. Een weigering, time-out of gelijktijdige statuswijziging retourneert een conflict en behoudt de databaseconfiguratie, in plaats van ten onrechte te melden dat de lader is gewist.

Gebruikers, uitnodigingen, RFID, toegang en limieten

Voertuigpaginering en status=members-gebruikerspaginering gebruiken een positieve numerieke cursor. Uitnodigingspagina's gebruiken een ondoorzichtige i2.*-cursor, terwijl status=all na de eerste pagina een ondoorzichtige samengestelde a2.*-cursor gebruikt (een numerieke cursor blijft alleen geldig als voortzetting van de oude ledenstroom). De gebruikerszoekopdracht wordt in de X-Admin-User-Search-verzoekheader aangeleverd zodat e-mailadressen niet in URL's of toegangslogboeken komen. limit is standaard 50 en maximaal 100; gebruikerslijsten ondersteunen status=all|members|invitations. Behandel alle geretourneerde cursors als ondoorzichtig en stuur ze ongewijzigd terug.

Rechtstreeks een gebruiker aanmaken maakt geen wachtwoord, inlogidentiteit of sessie aan. Het koppelt alleen een al geregistreerde klant. Gebruik het uitnodigingseindpunt voor een onbekend e-mailadres. De beschermde Tagless-systeemgebruiker kan niet via deze routes worden gewijzigd.

Voorbeelden

Stel waarden in uw shell in zonder het token af te drukken:

export ADMIN_API_BASE_URL="https://api.example.com"
export WORKSPACE_TOKEN="<read from secret manager>"

Geef locaties weer:

curl --fail-with-body \
  -H "Authorization: Bearer ${WORKSPACE_TOKEN}" \
  "${ADMIN_API_BASE_URL}/v2/admin/sites"

Maak veilig een locatie aan:

curl --fail-with-body \
  -X POST \
  -H "Authorization: Bearer ${WORKSPACE_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: site-main-depot-v1" \
  --data '{
    "name":"Main depot",
    "description":null,
    "addressLine1":"1 Example Street",
    "addressLine2":null,
    "postalCode":"LV-1001",
    "city":"Riga",
    "state":null,
    "countryId":1,
    "timezoneId":1,
    "latitude":56.9496,
    "longitude":24.1052
  }' \
  "${ADMIN_API_BASE_URL}/v2/admin/sites"

Download een CSV-rapport voor een expliciet UTC-bereik:

curl --fail-with-body \
  -H "Authorization: Bearer ${WORKSPACE_TOKEN}" \
  -o report.csv \
  "${ADMIN_API_BASE_URL}/v2/admin/reports/export?format=csv&from=2026-07-01T00%3A00%3A00Z&to=2026-08-01T00%3A00%3A00Z"

Bewust uitgesloten mogelijkheden

De werkruimtetoken-API biedt geen bewerkingen die een menselijke identiteit of bredere bevoegdheid vereisen. Hieronder vallen:

• tokens aanmaken, tonen, roteren of intrekken met een ander token;
• inloggen, wachtwoordherstel, sessies, delegatie van menselijke rollen of bevoegdheden en wijzigingen in werkruimte-eigendom;
• werkruimten aanmaken/verwijderen en lidmaatschap van facturatieaccounts;
• betalingsinstellingen, Stripe-onboarding, abonnementen, facturen en facturatie van de aanbieder;
• ondersteuningsbewerkingen voor de hele aanbieder en providerwebhooks;
• meldingen aan personen, navigatiedoorverwijzingen, merkmateriaal en ontwikkel-/testroutes.