Pedidos e respostas dos endpoints da Admin API do espaço de trabalho

Esta é a referência de pedidos/respostas de todos os endpoints /v2/admin. A autenticação, idempotência, limites de pedidos, criação de tokens e semântica de âmbitos estão documentados na Admin API do espaço de trabalho. Os tipos reutilizáveis ao nível dos campos e exemplos encontram-se em Esquemas e exemplos. Leia cada linha de endpoint em conjunto com o Contrato de respostas e erros, que lista todos os corpos de insucesso comuns e específicos possíveis.

Contrato comum

Cada caminho começa pela origem app-api implementada. O espaço de trabalho deriva exclusivamente do token autenticado; os clientes não podem enviar cpoId. Todos os valores :...Id documentados nos caminhos de recursos são inteiros decimais positivos. Cada pedido exige exatamente um:

Authorization: Bearer <workspace-access-token>

Os pedidos apresentados com corpo JSON exigem Content-Type: application/json. Todas as alterações exigem Idempotency-Key (POST, PUT, PATCH e DELETE), incluindo POST /v2/admin/reports/send; salvo indicação em contrário, o tipo de conteúdo de sucesso é application/json, as datas JSON são cadeias RFC 3339 e os números são números JSON.

Cada pedido pode incluir X-Request-Id e X-Error-Format: envelope; consulte o Contrato de respostas e erros. Estes cabeçalhos não alteram os esquemas de sucesso.

Notação usada abaixo:

• none significa sem corpo de pedido. Um DELETE que documenta um corpo JSON continua a exigir esse corpo.
• ? assinala uma propriedade ou parâmetro de consulta opcional.
• T | null significa que a propriedade está presente e permite null.
• 204 empty significa sem corpo de resposta.
• CursorPage<T> significa { items: T[], nextCursor: number|string|null }, exceto quando a linha indica explicitamente um objeto page ou pagination.
• Todos os recursos aninhados em falta, incluindo IDs de outro espaço de trabalho, usam 404 { "error": "Workspace resource not found", "code": "RESOURCE_NOT_FOUND" }, salvo se uma função documentar um conflito mais específico.

Esquemas de pedido partilhados

Entradas de espaços de trabalho e locais

WorkspacePatch = {
  name?: string(1..100), email?: email|null, website?: string|null,
  addressLine1?: string|null, addressLine2?: string|null,
  postalCode?: string|null, city?: string|null, state?: string|null,
  countryId?: positive integer
} // at least one property

SiteInput = {
  name: string(1..255), description?: string|null = null,
  addressLine1?: string|null = null, addressLine2?: string|null = null,
  postalCode?: string|null = null, city?: string|null = null, state?: string|null = null,
  countryId: positive integer, timezoneId: positive integer,
  latitude?: number[-90,90]|null = null, longitude?: number[-180,180]|null = null
}

Entrada de gestão de potência

PowerConfigurationInput = { pools: PowerPoolInput[0..200] }
PowerPoolInput = {
  id?: positive integer|null, name?: string(0..255),
  limit: integer[0,100000000], meterSources?: ExternalMeterInput[0..16],
  children?: (PowerPoolInput | ChargerPoolChild)[0..1000]
}
ChargerPoolChild = { chargepointId: positive integer, priority?: integer[-1000000,1000000] }
ExternalMeterInput = {
  id?: positive integer|null, sourceId?: positive integer|null,
  provider?: "perific", name?: string(0..255), externalId: string(1..80),
  measurementMode?: "available_headroom"|"external_non_ev_load_only"|"total_site_load_including_ev",
  valueMode?: "perific_relative"|"perific_direct"|"perific_meter",
  reserveA?: integer[0,100000], offlineSafeA?: integer[0,100000],
  ttlSeconds?: integer[30,86400], enabled?: boolean
}

Entradas dos carregadores

ChargerCreate = { name: string(1..40), identifier: string(1..40), password?: string(0..40) = "", siteId: positive integer }
ChargerPatch = {
  name?: string(1..40), siteId?: positive integer, invertedRfid?: boolean,
  smartMode?: integer[0,3], automationDisabled?: boolean
} // at least one
ConnectorPatch = {
  connectorFormatId: positive integer, connectorTypeId: positive integer,
  powerTypeId: positive integer, maxVoltage: integer[1,10000],
  maxAmperage: integer[1,10000], maxElectricPower: integer[1,100000000]
}

Entradas dos relatórios

ReportFilters = {
  from?: RFC3339, to?: RFC3339, siteId?: positive integer,
  chargerId?: positive integer, userId?: positive integer,
  anonymous?: true|false|1|0, active?: true|false|1|0
}
ReportScheduleInput = {
  enabled: boolean, recipientEmail: email(max 255; may be empty only when disabled), format: "csv"|"pdf",
  sendDay: integer[1,28], sendTime: UTC "HH:mm"
}

Os intervalos dos relatórios têm de cumprir from < to e não podem exceder 90 dias. Quando omitidos, são usados os últimos 90 dias. userId e anonymous=true são mutuamente exclusivos. As exportações agendadas recuperam um minuto UTC perdido e usam tentativas limitadas (espera de 5/10 minutos, concessão de reserva obsoleta de 30 minutos, três tentativas).

Entradas das tarifas

TariffInput = {
  name: string(1..64),
  exactly one of currencyId: positive integer, currencyCode: 3 letters, currency: 3 letters,
  biddingZoneId?: positive integer|null, tax?: finite number
}
TariffComponentInput = {
  typeId: positive integer, seasonId: positive integer, priority?: finite number,
  price: finite number, validFromMonth?: finite number, validToMonth?: finite number,
  validFromWeekDay?: finite number, validToWeekDay?: finite number,
  validFromHour?: finite number, validToHour?: finite number
}
TariffAssignmentCreateInput = { tariffId: positive integer, connectorId?: nonnegative integer }
TariffAssignmentUpdateInput = { tariffId: positive integer, connectorId: positive integer }

Entradas dos perfis de carregamento

ChargingProfileInput = {
  label: string(1..40), locationId: positive integer, stackLevel: nonnegative number,
  purposeId: positive integer, kindId: positive integer,
  recurrencyKindId?: positive integer|null, validFrom?: RFC3339|null,
  validTo?: RFC3339|null, startSchedule?: RFC3339|null,
  rateUnitId: positive integer, minChargingRate?: nonnegative number|null
}
ChargingProfileCreate = ChargingProfileInput & { schedule?: SchedulePeriod[0..256] }
SchedulePeriod = { startPeriod: nonnegative number, limit: nonnegative number, numberOfPhases?: positive integer|null }
ChargingScheduleInput = { rateUnitId: positive integer, periods: SchedulePeriod[1..256] }
ProfileAssignmentInput = { profileId: positive integer, connectorId?: nonnegative integer }

Entradas de utilizadores

UserCreate = { email: email(max 255), name: string(1..255) }
InvitationInput = {
  email: email, name?: string|null, rfid?: string|null,
  allChargers?: boolean, chargerIds?: unique positive integer[0..500]
} // chargerIds must be non-empty unless allChargers=true
AccessInput = { allChargers?: boolean, chargerIds?: unique positive integer[0..500] }
LimitCreate = { limitTypeId: positive integer, energyValue?: nonnegative integer = 0, timeValue?: nonnegative integer = 0 }
LimitPatch = { limitTypeId?: positive integer, energyValue?: nonnegative integer, timeValue?: nonnegative integer }

Pelo menos um de energyValue ou timeValue tem de ser superior a zero ao criar um limite. Os emails perdem os espaços nas extremidades e são convertidos para minúsculas. Os UIDs RFID só são aceites em escritas e são mascarados nas respostas de leitura.

Resumo dos DTOs de resposta

As tabelas de endpoints mostram todos os envelopes de resposta de nível superior. Estes são os principais DTOs reutilizáveis dentro desses envelopes:

As rotas de lista/detalhe devolvem objetos de referência para permitir descobrir IDs válidos. Considere campos adicionados desconhecidos como compatíveis com versões futuras e distinga casos apenas por campos estáveis e códigos de erro documentados.

Endpoints do espaço de trabalho

Endpoints de locais e gestão de potência

Endpoints dos carregadores

Endpoints dos relatórios

Endpoints das tarifas

TariffAssignment contém id, chargerId, connectorId, um resumo seguro de tarifa/moeda, createdAt e updatedAt.

Endpoints dos perfis de carregamento

ProfileAssignment contém o ID da atribuição, IDs de carregador/conector e um resumo seguro do perfil. Os objetos de resultado OCPP expõem informações estáveis de pedido/estado e nunca credenciais.

Endpoints de utilizadores, RFID, acesso, limites e utilizadores locais

O utilizador de sistema Tagless está protegido contra estas operações. Falhas nos emails de convite devolvem um estado de entrega seguro sem revelar detalhes SMTP; os clientes podem repetir quando emailRetryReady é true.

Respostas binárias

Duas famílias de endpoints não devolvem JSON em caso de sucesso:

Os erros dos endpoints binários continuam a ser JSON.