Conradh freagraí agus earráidí API riaracháin

Comhlánaíonn an comhad seo an conradh freagraí do gach críochphointe in Tagairt críochphointí. Léigh ró an chríochphointe dá chorp ratha agus na táblaí thíos do gach corp neamh-ratha comhroinnte nó sonrach. De réir réamhshocraithe, úsáideann earráidí roinnt struchtúr comhoiriúnachta; is féidir le glaoiteoirí clúdach uilíoch amháin a roghnú.

Clúdach roghnach struchtúrtha earráide

Seol an ceanntásc iarratais seo chuig aon chríochphointe:

X-Error-Format: envelope

Baintear spásanna imeallacha den luach le haghaidh comparáide agus ní dhéantar idirdhealú idir litreacha móra agus beaga. Leis an luach cruinn sin, tiontaítear gach freagra JSON a bhfuil stádas 400 nó níos airde aige go:

ErrorEnvelope = {
  error: {
    code: string,
    message: string,
    details: Record<string, unknown>,
    requestId: string
  }
}

Tiontú samplach ar chorp bailíochtaithe réamhshocraithe:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Invalid request",
    "details": {
      "fields": {
        "name": ["String must contain at least 1 character(s)"]
      }
    },
    "requestId": "integration-42"
  }
}

Tá na rialacha tiontaithe beacht:

• Déantar details.fields de validationErrors, agus VALIDATION_FAILED de code, fiú nuair a bhí cód fearainn sa chorp réamhshocraithe freisin.
• Coinnítear code réamhshocraithe barrleibhéil nuair nach bhfuil réimsí bailíochtaithe ann.
• Bogtar airíonna barrleibhéil eile seachas error, message, validationErrors agus code isteach in details; mar shampla, déantar details.limit de limit easpórtála tuairisce.
• Déantar message de error barrleibhéil den chineál teaghráin. Mura bhfuil a leithéid ann, úsáidtear an stádas cúltaca.
• Is iad na cóid chúltaca AUTH_REQUIRED (401), PERMISSION_DENIED (403), RESOURCE_NOT_FOUND (404), CONFLICT (409), VALIDATION_FAILED (422 agus 4xx neamhaicmithe eile), RATE_LIMITED (429), EXTERNAL_PROVIDER_FAILED (502) agus INTERNAL_ERROR (5xx eile, 503 san áireamh).
• Is é requestId an ceanntásc freagra cruinn X-Request-Id. Ní úsáidtear ID iarratais arna sholáthar ag glaoiteoir ach má mheaitseálann sé [A-Za-z0-9._:-]{1,128} tar éis spásanna imeallacha a bhaint; murach sin gineann an freastalaí UUID.

Ní athraíonn an tiontú seo an stádas ná ceanntásca nach mbaineann leis an gcorp. Baineann sé freisin le hathsheinmneacha idempotent de réir cheanntásc X-Error-Format an iarratais athsheinm. Fanann freagraí ratha dénártha ina ndénártha; cuirtear a n-earráidí JSON i gclúdach. Taispeánann na táblaí eile na coirp réamhshocraithe; tugann cur i bhfeidhm na rialacha thuas an corp freagra eile atá indéanta do gach ró.

Nodaireacht freagraí

ValidationError = {
  validationErrors: Record<string, string[]>,
  code?: string
}

CodedError = {
  error: string,
  code: string,
  // a route may add fields explicitly listed below
}

PlainError = { error: string }

Is tuairisciúil iad error agus téacs teachtaireachtaí bailíochtaithe, seachas idirdhealaitheoir cobhsaí ríomhchláraithe. Brainseáil ar code nuair atá sé ann. Tugann bailíochtú iarratais 422 ValidationError ar ais; féadfaidh bailíochtú réada iomláin { "validationErrors": {} } a tháirgeadh nuair nach n-aithnítear réimse aonair. Tugann JSON neamhbhailí agus teipeanna gan choinne an 500 PlainError domhanda a thaispeántar thíos ar ais.

Léiríonn gach sampla JSON struchtúr beacht an choirp. Is í an teachtaireacht bhailíochtaithe nó oibríochta a thugtar ar ais an téacs a thaispeántar mar <message>; is teaghrán JSON í, seachas luach litriúil idir lúibíní uilleacha.

Ord próiseála iarratas

Próiseáiltear iarratais san ord seo:

1. cumraíocht agus fíordheimhniú comharthaí spáis oibre;
2. beartas óstaigh agus teorainneacha ráta comhartha/spáis oibre;
3. scagadh teidlíochta reatha;
4. do gach athrú, bailíochtú/éileamh idempotency;
5. seiceálacha scóipe críochphointe, bailíochtú iarratais agus an oibríocht iarrtha.

Dá bhrí sin, tá Idempotency-Key de dhíth fós ar athrú le comhartha bailí nach bhfuil dóthain scóipe aige. Is féidir freagra athraithe críochnaithe 403, 404, 409 nó 422 a athsheinm don eochair/iarratas céanna.

Freagraí fíordheimhnithe, beartais agus teorannaithe ráta

Féadfaidh na freagraí seo tarlú ar gach críochphointe cláraithe /v2/admin roimh phróiseáil shonrach an chríochphointe.

Tá rochtain API i ngach plean. Má dhíchumasaítear socrú adminApiEnabled óstach an spáis oibre, tugtar 404 ar ais; má chailltear teidlíocht ghné bhreise, ní bhaintear ach na scóip lena mbaineann. Úsáideann an diúltú scóipe sin an freagra thíos, seachas sreabhadh athnuachana comhartha.

Teipeanna scóipe, idempotency, parsála, úinéireachta agus gan choinne

Ní mór d'IDanna cosáin acmhainne a bheith ina n-uimhreacha dearfacha. Tugann :siteId, :chargerId, :portId, :tariffId, :profileId, :assignmentId, :userId, :rfidId, :accessId, :limitId nó :localUserId neamh-dhearfach nó neamhuimhriúil 422 ValidationError ar ais, seachas 400.

Earráidí láithreáin agus bainistithe cumhachta

Earráidí luchtairí

Úsáidtear mapChargerErrors() do chruthú/nuashonrú luchtairí, dintiúir, socruithe nascóra, liostú poiblí, réiteach ábhair QR, athrú/athlódáil cumraíochta, tosú dochtearraí, na ceithre ordú bhunúsacha agus iarratas sceidil ilchodaigh.

Ní thugann oibríochtaí simplí léite ach na freagraí comhroinnte 401/403/404/429/500/503 agus bailíochtú ceiste/cosáin 422 ar ais. Féadfaidh scriosadh luchtaire an 500 PlainError comhroinnte a thabhairt ar ais má theipeann ar an scriosadh gan freagra earráide níos sonraí.

Earráidí tuairiscí

Is dénártha an t-easpórtáil rathúil; fanann gach earráid easpórtála ina JSON.

Earráidí taraifí

Earráidí próifílí luchtaithe

Earráidí fearainn úsáideora

Úsáideann earráidí bailíochtaithe úsáideora a aithníonn réimse ValidationError agus code; úsáideann earráidí eile úsáideora CodedError. Úsáideann gach cás acmhainne ar iarraidh an freagra comhroinnte RESOURCE_NOT_FOUND nach nochtann acmhainní.

Féadfaidh POST /users/invitations an 403 INSUFFICIENT_SCOPE comhroinnte a thabhairt ar ais freisin tar éis parsáil coirp má tá users:access ar iarraidh, nó má soláthraíodh RFID agus má tá users:rfid ar iarraidh. Liostaíonn críochphointí úsáideora áitiúil gach scóip riachtanach in Tagairt críochphointí.

Baineann cóid earráide úsáideora mar seo a leanas:

Úsáideann gach toradh úinéireachta agus acmhainne ar iarraidh sna grúpaí sin, lena n-áirítear ríomhphost neamhchláraithe ar POST /users, an corp comhroinnte 404 RESOURCE_NOT_FOUND.

Freagraí gan chorp agus athsheinm

Níl corp i bhfreagra rathúil 204. Baineann sé seo le gach scriosadh doiciméadaithe a liostaíonn 204 empty. Socraíonn athsheinm idempotent críochnaithe Idempotency-Replayed: true agus úsáideann sé an stádas/chorp stóráilte; i gcás 204, fanann an freagra HTTP gan chorp. Ní thugann an API réad ratha JSON ar ais riamh d'oibríocht dhoiciméadaithe 204.