Admin API til arbejdsområder

Workspace Admin API lader server-til-server-integrationer administrere ét EVCharge-arbejdsområde. Denne dokumentation er til arbejdsområdeadministratorer og eksterne API-integratorer. API'et bruger tilbagekaldelige adgangstokens bundet til arbejdsområdet og detaljerede scopes; kundelogintokens og browsersessioner accepteres ikke.

Denne mappe er den autoritative udviklerreference for /v2/admin-API'et implementeret af app-api. Den dokumenterer ikke kunde-/mobilruter eller adminportalens egne HTTP-ruter.

• Endpointanmodninger og -svar viser alle 87 registrerede endpoints, scopes, parametre, anmodningstekster og svartekster ved succes.
• Skemaer og eksempler definerer genanvendelige anmodnings- og svartyper samt repræsentative JSON-data.
• Kontrakt for svar og fejl definerer alle fælles og endpointspecifikke svartekster ved manglende succes.

Basis-URL og ressourceafgrænsning

Alle ruter er relative til den installerede app-api-oprindelse:

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

Arbejdsområde-ID accepteres ikke i URL, forespørgselsstreng eller anmodningstekst. Hvert adgangstoken er bundet til præcis ét arbejdsområde, og API'et udleder cpoId fra det autentificerede tokens identitet. Hvis et underordnet sted, lader, bruger, tarif, profil, tildeling eller transaktion ikke tilhører arbejdsområdet, returnerer API'et det samme 404 RESOURCE_NOT_FOUND-svar, som ikke afslører ressourcens eksistens.

Sådan får du et adgangstoken

En administrator for arbejdsområdet opretter tokens under API-adgang i arbejdsområdets indstillinger. Tokenadministration er bevidst ikke tilgængelig for arbejdsområdets tokens.

• API-adgang er inkluderet i alle planer, også Free. Administratoren skal have tilladelse til at redigere arbejdsområdet.
• Arbejdsområdets vært skal aktivere Admin API via adminApiEnabled; ellers modtager et gyldigt token et 404-svar fra app-api, som ikke afslører ressourcens eksistens.
• Administratoren kan kun tildele scopes, som egne aktuelle tilladelser og arbejdsområdets rettigheder tillader.
• Nye tokens kan være uden udløb, hvilket er standard i arbejdsområdets indstillinger, eller have en levetid på 1 til 365 hele dage valgt af administratoren; serveren beregner endelige absolutte udløbstidspunkter. Tokens uden udløb er gyldige, indtil de tilbagekaldes.
• Et arbejdsområde kan højst have 50 aktive tokens.
• Legitimationsoplysningen vises kun én gang i klartekst. Gem den straks i en tjeneste til håndtering af hemmeligheder.
• Navn, scopes og udløb er uforanderlige. For at udskifte tokenet skal du oprette en erstatning, tage den i brug, verificere den og tilbagekalde det gamle token.
• Tilbagekaldelse er øjeblikkelig; tilbagekaldte rækker forbliver synlige som uforanderlig arbejdsområdehistorik med følsomme oplysninger skjult, og der er intet endpoint til introspektion af bearer-tokens eller permanent sletning.

app-api har intet endpoint, der udsteder, fornyer, viser eller tilbagekalder disse legitimationsoplysninger. At hente tokenet er derfor en forudsætning, der udføres via den menneskebetjente adminportal, ikke et andet endpoint i denne reference.

Anbring aldrig tokenet i versionsstyring, URL'er, forespørgselsstrenge, cookies, logs, analyser eller fejlrapporter.

Autentificering

Send præcis én header i RFC 6750-format med hver anmodning:

Authorization: Bearer evc_ws_<selector>.<secret>

Den nøjagtige uigennemsigtige legitimationsoplysning består af evc_ws_ efterfulgt af en kanonisk base64url-selektor på 16 tegn, . og en kanonisk base64url-hemmelighed på 43 tegn. Send hele legitimationsoplysningen uændret; base64-kod den ikke igen.

API'et afviser dublerede autorisationsheadere, kommaseparerede værdier, andre ordninger, tomme bearer-værdier, kunde-JWT'er og legitimationsoplysninger angivet andre steder end i denne header.

Forkert formaterede, ukendte, udløbne, tilbagekaldte eller på anden måde ugyldige tokens modtager alle samme svar:

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

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

Tjenesten kontrollerer tokenstatus og arbejdsområdets aktuelle rettigheder ved hver anmodning. Fjernelse af en rettighed kan derfor deaktivere berørte scopes, før tokenet udløber.

Arbejdsområdetokens er uigennemsigtige legitimationsoplysninger, ikke JWT'er. De har intet fornyelsestoken, og der findes intet fornyelses-endpoint. Et tidsbegrænset token holder op med at autentificere ved sit absolutte expiresAt; et token uden udløb er gyldigt, indtil det tilbagekaldes. Udskiftning betyder at oprette en ny legitimationsoplysning i portalen, tage den i brug hos klienten og tilbagekalde den gamle.

Konventioner for anmodninger

• Brug Content-Type: application/json til anmodninger med JSON-anmodningstekst.
• Indledende og afsluttende mellemrum fjernes fra valgfrie X-Request-Id-anmodningsværdier, som kun accepteres, når de indeholder 1-128 tegn fra A-Z, a-z, 0-9, ., _, : eller -; ellers genererer serveren en UUID. Hvert svar returnerer den valgte værdi som X-Request-Id.
• Valgfri X-Error-Format: envelope konverterer alle JSON-fejlsvar til den strukturerede omslutning beskrevet i Kontrakt for svar og fejl. Enhver anden værdi bevarer den almindelige kompatibilitetssvartekst.
• ID'er i stiparametre er positive heltal. Adgangstoken-ID'er returneret af portalen er decimalstrenge, fordi de er usignerede 64-bit databaseværdier.
• Dato- og tidsværdier er RFC 3339-strenge med eksplicit tidszoneforskydning, f.eks. 2026-08-13T12:30:00Z.
• Vellykkede sletninger returnerer normalt 204 No Content.
• Oprettelseshandlinger returnerer normalt 201 Created.
• OCPP-arbejde, der kun er sat i kø, kan returnere 202 Accepted; fortolk det ikke som en bekræftelse fra laderen, medmindre svaret udtrykkeligt siger det.
• Autentificerede svar bruger Cache-Control: no-store. Endpoints til QR og rapporteksport returnerer binære svartekster med eksplicitte indholdsheadere.
• Tilladte browseroprindelser kan læse X-Request-Id, Idempotency-Replayed, Retry-After og Content-Disposition via CORS. Det lader browserklienter sammenkæde anmodninger, registrere idempotente gentagelser, overholde ventetid før nye forsøg og bevare filnavne valgt af serveren ved download.

Idempotens

Alle admin-anmodninger med POST, PUT, PATCH og DELETE skal indeholde én Idempotency-Key-header. Nøgler indeholder 1-255 synlige tegn og afgrænses til token, metode og sti.

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

Genbrug af en fuldført nøgle med identisk URL og anmodningstekst gentager det gemte svar og tilføjer:

Idempotency-Replayed: true

Genbrug af en nøgle med en anden anmodning returnerer 409 IDEMPOTENCY_CONFLICT. En anmodning, der stadig behandles, returnerer 409 IDEMPOTENT_REQUEST_PROCESSING med Retry-After: 5.

Fuldførte svar og endelige resultater gemmes til gentagelse eller afstemning i syv dage efter deres seneste opdatering. Efter denne opbevaringsperiode kan samme nøgle blive behandlet som en ny kommando. Klienter skal derfor bruge globalt entydige nøgler og må ikke bevidst genbruge dem.

Hvis en behandlingslås udløber, forbindelsen lukkes efter udførelsens start, eller handlingen returnerer en serverfejl, kan API'et ikke sikkert fastslå, om en ekstern virkning har fundet sted. I den syv dage lange opbevaringsperiode forbliver nøglens udfald endeligt uafklaret, og den returnerer 409 IDEMPOTENCY_OUTCOME_UNKNOWN; den overtages ikke igen og udføres ikke automatisk på ny. Kontrollér handlingens virkninger, før du foretager manuel genopretning, og indsend ikke samme handling med en ny nøgle, før afstemningen er fuldført.

Alle admin-endpoints, der ændrer data, inklusive POST /reports/send, kræver Idempotency-Key.

Anmodningsgrænser

Grænser anvendes både på det enkelte token og på dets arbejdsområde. Standardværdierne i kildekoden er:

En begrænset anmodning returnerer 429 Too Many Requests og en Retry-After-header. Installationer kan tilsidesætte disse værdier.

Fejl

JSON-fejl bruger en stabil code, når klienten skal vælge en handling:

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

Valideringsfejl bruger feltarrays:

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

Almindelige statusser er:

Scopekatalog

Følgende scopekatalog bruges, når en administrator opretter et token. Et skrive- eller højrisikoscope kan indebære det tilsvarende læsescope, men læsescopes giver aldrig skriveadgang. Tilgængelige scopes afhænger af administratorens tilladelser og arbejdsområdets aktiverede funktioner.

Selve API-adgangen er inkluderet i alle planer og styres af værtens adminApiEnabled-indstilling. De ekstra funktionsrettigheder ovenfor gælder stadig; API-adgang giver ikke funktioner ud over arbejdsområdets plan.

Endpointreference

Tabellerne nedenfor viser alle 87 workspace-admin-ruter. Flere scopes i én celle er alle påkrævede.

Arbejdsområde

Felter til arbejdsområdeopdatering: name, email, website, addressLine1, addressLine2, postalCode, city, state og countryId. Mindst ét felt er påkrævet. Tomme strenge i nullable felter normaliseres til null.

Steder og strømstyring

Anmodningstekster til oprettelse og opdatering af steder bruger:

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

Geokodning af steder accepterer de valgfrie forespørgselsfelter street, city, state, country og countryCode med to bogstaver samt anmodningsheaderen Accept-Language. Den kombinerede søgning efter gade/by/delstat skal indeholde mindst to tegn. Svar indeholder kun placeId, displayName, latitude og longitude; leverandørens legitimationsoplysninger og leverandørspecifikke metadata udleveres ikke. Serveren anvender den fælles leverandørkø med én anmodning pr. sekund, timeout på otte sekunder, en afgrænset 24-timers cache og globale anmodningsgrænser for arbejdsområdetokens.

Strømstyring accepterer { "pools": [...] }. En pulje har id, name, limit, valgfri meterSources og rekursive children. En underordnet lader har chargepointId og priority. API'et begrænser træets størrelse og antallet af målere og udfører OCPP-rydning og ny validering i to faser ved erstatning af installeret tilstand. En afvist eller udløbet ændring eller en samtidighedskonflikt returnerer 409 POWER_MANAGEMENT_CONFLICT, mens den tidligere konfiguration bevares.

Ladere

Forespørgselsparametre til laderlogs er cursor, limit (standard 50, højst 200), from, to, action, direction og levelId. Sessionsparametre er page, limit (standard 25, højst 100), from, to og customerId (et positivt ID eller unknown). Historik for sammensatte tidsplaner bruger cursor, limit (standard 20, højst 50) og valgfri connectorId.

Rapporter

Rapportdata- og eksportfiltre er from, to, siteId, chargerId, userId, anonymous og active. from/to bruger som standard det seneste 90-dagesinterval og må ikke spænde over mere end 90 dage. userId kan ikke kombineres med anonymous=true.

• Sideinddeling af data: uigennemsigtig cursor, standard limit=50, højst 100.
• Målinger: påkrævet transactionLogId, uigennemsigtig cursor, standard limit=500, højst 1.000.
• Eksport: format=csv|pdf, standard csv, fast grænse på 2.000 rækker.
• Eksportsvar bruger Content-Disposition: attachment, Cache-Control: private, no-store og X-Content-Type-Options: nosniff.

Anmodningstekst for tidsplan:

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

sendDay er 1-28, og sendTime fortolkes i UTC. Planlæggeren indhenter et overskredet planlagt minut inden for den aktuelle leveringsmåned. Fejlslagne opbygninger før overdragelse prøves igen efter 5 og 10 minutter, en afbrudt building-reservation kan overtages efter 30 minutter, og automatisk levering stopper efter tre forsøg. Planlæggeren gemmer indeterminate umiddelbart før SMTP-overdragelse; både indeterminate og den ældre status sending er endelige, fordi automatisk gentagelse af begge kan sende en dubleret vedhæftning. Operatører skal afstemme disse resultater manuelt, før tidsplanens tilstand ændres. Hver kørsel vælger højst ti tidsplaner, stopper med at starte arbejde efter et budget på 45 sekunder og bruger afgrænsede SMTP-timeouts. Jobbet er deaktiveret som standard og skal aktiveres eksplicit efter validering af SMTP og kapacitet. API-tidsplanen ejes af arbejdsområdet i stedet for at låne identiteten fra den person, der oprettede tokenet.

Tariffer

En tarifs anmodning indeholder name, præcis én af currencyId, currencyCode eller currency, valgfri biddingZoneId og tax. En tildelingsanmodning er:

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

Ved oprettelse af en tildeling anvendes tariffen på alle fysiske stik, hvis connectorId udelades eller udtrykkeligt sættes til 0. Opdateringer af tildelinger retter sig mod én gemt tildeling og kræver derfor et eksplicit positivt fysisk connectorId; 0 afvises.

En komponent indeholder typeId, seasonId og price; kun priority og gyldighedsgrænserne for måned, ugedag og time er valgfrie.

Ladeprofiler

Profilens metadatafelter er label, locationId, stackLevel, purposeId, kindId, valgfri recurrencyKindId, validFrom, validTo, startSchedule, rateUnitId og valgfri minChargingRate. En tidsplanperiode indeholder startPeriod, limit og valgfri numberOfPhases. En tildelingsanmodning indeholder profileId og connectorId (standard 0).

Sletning af profiler og erstatning af strømstyring kan afvente laderens bekræftelse. En afvisning, timeout eller samtidig tilstandsændring returnerer en konflikt og bevarer databasekonfigurationen i stedet for at lade, som om laderen var ryddet.

Brugere, invitationer, RFID, adgang og grænser

Sideinddeling af køretøjer og brugere med status=members bruger en positiv numerisk cursor. Invitationssider bruger en uigennemsigtig i2.*-markør, mens status=all bruger en uigennemsigtig sammensat a2.*-markør efter første side; en numerisk markør forbliver kun gyldig som fortsættelse af den ældre medlemsstrøm. Brugersøgning angives i anmodningsheaderen X-Admin-User-Search, så e-mailadresser ikke placeres i URL'er eller adgangslogs. limit er som standard 50 og begrænset til 100; brugerlisten understøtter status=all|members|invitations. Behandl alle returnerede markører som uigennemsigtige, og send dem tilbage uændret.

Direkte brugeroprettelse opretter ikke en adgangskode, loginidentitet eller session. Den tilknytter kun en allerede registreret kunde. Brug invitations-endpointet til en ukendt e-mailadresse. Den beskyttede Tagless-systembruger kan ikke ændres via disse ruter.

Eksempler

Angiv værdier i din shell uden at udskrive tokenet:

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

Vis steder:

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

Opret et sted sikkert:

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 en CSV-rapport for et eksplicit UTC-interval:

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"

Bevidste udeladelser

API'et til arbejdsområdetokens tilbyder ikke handlinger, der kræver en menneskelig identitet eller mere omfattende beføjelser. Disse omfatter:

• oprette, vise, udskifte eller tilbagekalde tokens med et andet token;
• login, nulstilling af adgangskode, sessioner, delegering af menneskelige roller eller rettigheder samt ændring af arbejdsområdeejerskab;
• oprettelse/sletning af arbejdsområde og medlemskab af faktureringskonto;
• betalingsindstillinger, Stripe-tilmelding, planer, fakturaer og værtsfakturering;
• supporthandlinger på tværs af værten og leverandørwebhooks;
• meddelelser til personer, navigationsomdirigeringer, brandaktiver og udviklings-/testruter.