Arbetsytans Admin API

Workspace Admin API låter server-till-server-integrationer administrera en EVCharge-arbetsyta. Dokumentationen är för arbetsyteadministratörer och externa API-integratörer. Den använder återkallbara åtkomsttoken bundna till arbetsytan och detaljerade behörighetsområden; kunders inloggningstoken och webbläsarsessioner accepteras inte.

Den här katalogen är den auktoritativa utvecklarreferensen för API:et /v2/admin som implementeras av app-api. Den dokumenterar inte kund-/mobilrutter eller adminportalens egna HTTP-rutter.

• Endpointanrop och svar listar alla 87 registrerade endpoints, behörighetsområden, parametrar, anropskroppar och lyckade svarskroppar.
• Scheman och exempel definierar återanvändbara anrops- och svarstyper samt representativa JSON-data.
• Kontrakt för svar och fel definierar varje gemensam och endpointspecifik svarskropp vid fel.

Bas-URL och resursgräns

Alla rutter är relativa till den driftsatta app-api-serverns ursprung:

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

Arbetsyte-ID accepteras inte i URL, frågesträng eller anropskropp. Varje åtkomsttoken är bunden till exakt en arbetsyta och API:et härleder cpoId från den autentiserade tokenidentiteten. Om en underordnad plats, laddare, användare, tariff, profil, tilldelning eller transaktion inte tillhör arbetsytan returnerar API:et samma 404 RESOURCE_NOT_FOUND-svar utan att avslöja resursens existens.

Hämta en åtkomsttoken

En administratör för arbetsytan skapar token under API-åtkomst i arbetsytans inställningar. Tokenhantering är avsiktligt inte tillgänglig för arbetsytans token.

• API-åtkomst ingår i alla planer, även Free. Administratören måste ha behörighet att redigera arbetsytan.
• Arbetsytans värd måste aktivera Admin API via adminApiEnabled; annars får en giltig token ett 404-svar från app-api som inte avslöjar resursens existens.
• Administratören får bara tilldela behörighetsområden som tillåts av de egna aktuella behörigheterna och arbetsytans rättigheter.
• Nya token kan vara utan utgångstid, vilket är standard i arbetsytans inställningar, eller ha en livslängd på 1 till 365 hela dagar vald av administratören; servern beräknar begränsade absoluta utgångstider. Token utan utgångstid gäller tills de återkallas.
• En arbetsyta får ha högst 50 aktiva token.
• Autentiseringsuppgiften visas i klartext en enda gång. Spara den omedelbart i en hemlighetshanterare.
• Namn, behörighetsområden och utgångstid är oföränderliga. För att byta token skapar du en ersättare, tar den i drift, verifierar den och återkallar den gamla.
• Återkallelse sker omedelbart; återkallade rader förblir synliga som oföränderlig arbetsytehistorik med känsliga uppgifter dolda. Det finns ingen endpoint för inspektion av bearer-token eller permanent borttagning.

app-api har ingen endpoint som utfärdar, förnyar, listar eller återkallar dessa autentiseringsuppgifter. Att hämta token är därför ett förkrav som görs av en person i adminportalen, inte en annan endpoint i den här referensen.

Lägg aldrig token i versionshantering, URL:er, frågesträngar, cookies, loggar, analysdata eller felrapporter.

Autentisering

Skicka exakt en header enligt RFC 6750 med varje anrop:

Authorization: Bearer evc_ws_<selector>.<secret>

Den exakta ogenomskinliga autentiseringsuppgiften består av evc_ws_ följt av en kanonisk base64url-selektor på 16 tecken, . och en kanonisk base64url-hemlighet på 43 tecken. Skicka hela uppgiften oförändrad; base64-koda den inte igen.

API:et avvisar dubbla auktoriseringsheadrar, kommaseparerade värden, andra scheman, tomma bearer-värden, kund-JWT:er och inloggningsuppgifter som anges någon annanstans än i denna header.

Felaktigt formaterade, okända, utgångna, återkallade eller på annat sätt ogiltiga token får alla samma svar:

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

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

Tjänsten kontrollerar tokenstatus och arbetsytans aktuella rättigheter vid varje anrop. Om en rättighet tas bort kan berörda behörighetsområden därför inaktiveras innan token löper ut.

Arbetsytetoken är ogenomskinliga autentiseringsuppgifter, inte JWT:er. De har ingen förnyelsetoken och det finns ingen förnyelseendpoint. En tidsbegränsad token slutar autentisera vid sitt absoluta expiresAt; en token utan utgångstid gäller tills den återkallas. Rotation innebär att skapa en ersättningsuppgift i portalen, driftsätta den i klienten och återkalla den gamla.

Anropskonventioner

• Använd Content-Type: application/json för anrop med JSON-kropp.
• Inledande och avslutande blanksteg tas bort från valfria X-Request-Id-värden, som bara accepteras om de innehåller 1–128 tecken från A-Z, a-z, 0-9, ., _, : eller -; annars skapar servern ett UUID. Varje svar returnerar det valda värdet som X-Request-Id.
• Valfria X-Error-Format: envelope omvandlar varje JSON-felsvar till den strukturerade omslutning som dokumenteras i Kontrakt för svar och fel. Alla andra värden behåller standardkroppen för kompatibilitet.
• ID:n i sökvägsparametrar är positiva heltal. Åtkomsttoken-ID:n som portalen returnerar är decimalsträngar eftersom de är osignerade 64-bitars databasvärden.
• Datum- och tidsvärden är RFC 3339-strängar med uttrycklig tidszonsförskjutning, till exempel 2026-08-13T12:30:00Z.
• Lyckade borttagningar returnerar normalt 204 No Content.
• Skapande åtgärder returnerar normalt 201 Created.
• OCPP-arbete som bara har köats kan returnera 202 Accepted; tolka det inte som en bekräftelse från laddaren om inte svaret uttryckligen säger det.
• Autentiserade svar använder Cache-Control: no-store. Endpoints för QR och rapportexport returnerar binära kroppar med uttryckliga innehållsheadrar.
• Tillåtna webbläsarursprung kan läsa X-Request-Id, Idempotency-Replayed, Retry-After och Content-Disposition via CORS. Det gör att webbläsarklienter kan koppla ihop anrop, upptäcka idempotenta upprepningar, följa väntetider för nya försök och behålla serverns valda filnamn vid nedladdning.

Idempotens

Alla adminanrop med POST, PUT, PATCH och DELETE måste innehålla en Idempotency-Key-header. Nycklar innehåller 1–255 synliga tecken och avgränsas till token, metod och sökväg.

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

Om en slutförd nyckel återanvänds med identisk URL och kropp spelas det sparade svaret upp igen och följande läggs till:

Idempotency-Replayed: true

Om en nyckel återanvänds med ett annat anrop returneras 409 IDEMPOTENCY_CONFLICT. Ett anrop som fortfarande behandlas returnerar 409 IDEMPOTENT_REQUEST_PROCESSING med Retry-After: 5.

Slutförda svar och slutliga utfall sparas för upprepning eller avstämning i sju dagar efter den senaste uppdateringen. Därefter kan samma nyckel behandlas som ett nytt kommando. Klienter måste därför använda globalt unika nycklar och får inte avsiktligt återanvända dem.

Om en behandlingsreservation löper ut, anslutningen stängs efter att körningen har börjat eller åtgärden returnerar ett serverfel kan API:et inte säkert avgöra om en extern effekt har inträffat. Under lagringsperioden på sju dagar förblir nyckelns utfall slutgiltigt obestämt och returnerar 409 IDEMPOTENCY_OUTCOME_UNKNOWN; den återtas inte och körs inte automatiskt igen. Kontrollera åtgärdens effekter före manuell återställning och skicka inte samma åtgärd med en ny nyckel förrän avstämningen är klar.

Alla administratörsendpoints som ändrar data, inklusive POST /reports/send, kräver Idempotency-Key.

Anropsgränser

Gränser tillämpas både på den enskilda token och på dess arbetsyta. Standardvärdena i källkoden är:

Ett begränsat anrop returnerar 429 Too Many Requests och en Retry-After-header. Installationer kan åsidosätta dessa värden.

Fel

JSON-fel använder en stabil code där klienten behöver skilja mellan olika fall:

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

Valideringsfel använder fältarrayer:

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

Vanliga statusar är:

Katalog över behörighetsområden

Följande katalog över behörighetsområden används när en administratör skapar en token. Ett skrivområde eller område med stor påverkan kan innebära motsvarande läsområde, men läsområden ger aldrig skrivrättigheter. Tillgängliga områden beror på administratörens behörigheter och arbetsytans aktiverade funktioner.

Själva API-åtkomsten ingår i alla planer och styrs av värdens inställning adminApiEnabled. De ytterligare funktionsrättigheterna ovan gäller fortfarande; API-åtkomst ger inte funktioner utanför arbetsytans plan.

Endpointreferens

Tabellerna nedan listar alla 87 administratörsrutter för arbetsytan. Om flera behörighetsområden anges i en cell krävs samtliga.

Arbetsyta

Fält för arbetsyteuppdatering: name, email, website, addressLine1, addressLine2, postalCode, city, state och countryId. Minst ett fält krävs. Tomma strängar som får vara null normaliseras till null.

Platser och effektstyrning

Kroppar för att skapa och uppdatera platser använder:

{
  "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
}

Platsgeokodning accepterar de valfria frågefälten street, city, state, country och countryCode med två bokstäver samt anropsheadern Accept-Language. Den kombinerade sökningen efter gata/stad/region måste innehålla minst två tecken. Svar innehåller bara placeId, displayName, latitude och longitude; leverantörsuppgifter och leverantörsspecifika metadata lämnas inte ut. Servern tillämpar den gemensamma leverantörskön med ett anrop per sekund, åtta sekunders timeout, begränsad 24-timmarscache och globala anropsgränser för arbetsytetoken.

Effektstyrning accepterar { "pools": [...] }. En grupp har id, name, limit, valfria meterSources och rekursiva children. En underordnad laddare har chargepointId och priority. API:et begränsar trädets storlek och antalet mätare och genomför OCPP-rensning och omvalidering i två faser när installerat tillstånd ersätts. En nekad ändring, timeout eller samtidighetskonflikt returnerar 409 POWER_MANAGEMENT_CONFLICT och behåller föregående konfiguration.

Laddare

Frågeparametrarna för laddarloggar är cursor, limit (standard 50, högst 200), from, to, action, direction och levelId. Sessionsparametrarna är page, limit (standard 25, högst 100), from, to och customerId (ett positivt ID eller unknown). Historik för sammansatta scheman använder cursor, limit (standard 20, högst 50) och valfria connectorId.

Rapporter

Filtren för rapportdata och export är from, to, siteId, chargerId, userId, anonymous och active. from/to använder som standard de senaste 90 dagarna och får inte omfatta mer än 90 dagar. userId kan inte kombineras med anonymous=true.

• Sidindelning av data: ogenomskinlig cursor, standard limit=50, högst 100.
• Mätningar: obligatorisk transactionLogId, ogenomskinlig cursor, standard limit=500, högst 1 000.
• Export: format=csv|pdf, standard csv, fast gräns på 2 000 rader.
• Exportsvar använder Content-Disposition: attachment, Cache-Control: private, no-store och X-Content-Type-Options: nosniff.

Schemakropp:

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

sendDay är 1–28 och sendTime tolkas i UTC. Schemaläggaren kör i efterhand efter en missad schemalagd minut under den aktuella leveransmånaden. Misslyckad uppbyggnad före överlämning försöks igen efter 5 och 10 minuter; en avbruten building-reservation kan tas över efter 30 minuter och automatisk leverans stoppas efter tre försök. Schemaläggaren sparar indeterminate omedelbart före SMTP-överlämningen; både indeterminate och den äldre statusen sending är slutliga eftersom ett automatiskt nytt försök i båda fallen kan skicka en duplicerad bilaga. Operatörer måste stämma av dessa utfall manuellt innan schemats tillstånd ändras. Varje körning väljer högst tio scheman, slutar starta arbete efter en tidsbudget på 45 sekunder och använder begränsade SMTP-timeouter. Jobbet är avstängt som standard och måste aktiveras uttryckligen efter validering av SMTP och kapacitet. API-schemat ägs av arbetsytan i stället för att låna identiteten från personen som skapade token.

Tariffer

En tariffkropp innehåller name, exakt ett av currencyId, currencyCode eller currency, valfria biddingZoneId och tax. En tilldelningskropp är:

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

När en tilldelning skapas tillämpas tariffen på alla fysiska kontakter om connectorId utelämnas eller uttryckligen sätts till 0. Uppdateringar gäller en sparad tilldelning och kräver därför ett uttryckligt positivt fysiskt connectorId; 0 avvisas.

En komponent innehåller typeId, seasonId och price. Den kan även ha priority samt giltighetsgränser för månad, veckodag och timme.

Laddprofiler

Profilens metadatafält är label, locationId, stackLevel, purposeId, kindId, valfria recurrencyKindId, validFrom, validTo, startSchedule, rateUnitId och valfria minChargingRate. En schemaperiod innehåller startPeriod, limit och valfria numberOfPhases. En tilldelningskropp innehåller profileId och connectorId (standard 0).

Borttagning av profiler och ersättning av effektstyrning kan invänta laddarens bekräftelse. Ett avslag, en timeout eller en samtidig tillståndsändring returnerar en konflikt och behåller databaskonfigurationen i stället för att anta att laddaren rensats.

Användare, inbjudningar, RFID, åtkomst och gränser

Sidindelning av fordon och användare med status=members använder en positiv numerisk cursor. Inbjudningssidor använder en ogenomskinlig i2.*-markör, medan status=all använder en ogenomskinlig sammansatt a2.*-markör efter första sidan; en numerisk markör är bara fortsatt giltig som fortsättning på den äldre medlemsströmmen. Användarsökning anges i anropsheadern X-Admin-User-Search så att e-postadresser inte hamnar i URL:er eller åtkomstloggar. limit är som standard 50 och begränsad till 100; användarlistning stöder status=all|members|invitations. Behandla alla returnerade markörer som ogenomskinliga och skicka tillbaka dem oförändrade.

Direkt användarskapande skapar inte lösenord, inloggningsidentitet eller session. Det kopplar bara en redan registrerad kund. Använd inbjudningsendpointen för en okänd e-postadress. Den skyddade Tagless-systemanvändaren kan inte ändras via dessa rutter.

Exempel

Ange värden i skalet utan att skriva ut token:

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

Lista platser:

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

Skapa en plats säkert:

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"

Ladda ned en CSV-rapport för ett uttryckligt UTC-intervall:

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"

Avsiktliga undantag

API:et för arbetsytetoken exponerar inte åtgärder som kräver en mänsklig identitet eller vidare befogenheter. Dessa omfattar:

• skapa, visa, byta eller återkalla token med en annan token;
• inloggning, lösenordsåterställning, sessioner, delegering av mänskliga roller eller privilegier samt ändringar av arbetsytans ägare;
• skapande/borttagning av arbetsyta och medlemskap i faktureringskonto;
• betalningsinställningar, Stripe-registrering, planer, fakturor och värdfakturering;
• värdövergripande supportåtgärder och leverantörswebhooks;
• meddelanden till personer, navigeringsomdirigeringar, varumärkesresurser och utvecklings-/testrutter.