Admin API do espaço de trabalho

A Admin API do espaço de trabalho permite a integrações entre servidores administrar um espaço EVCharge. Esta documentação destina-se a administradores de espaços de trabalho e integradores externos da API. Usa tokens de acesso revogáveis, vinculados ao espaço de trabalho e com âmbitos detalhados; não aceita tokens de início de sessão de clientes nem sessões de navegador.

Este diretório é a referência canónica para programadores da API /v2/admin implementada por app-api. Não documenta rotas de clientes/móveis nem as rotas HTTP próprias do portal de administração.

• Pedidos e respostas dos endpoints lista todos os 87 endpoints registados, âmbitos, parâmetros, corpos de pedido e corpos de sucesso.
• Esquemas e exemplos define os tipos reutilizáveis de pedido/resposta e conteúdos JSON representativos.
• Contrato de respostas e erros define todos os corpos de insucesso comuns e específicos de endpoints.

URL base e limite dos recursos

Todas as rotas são relativas à origem app-api implementada:

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

O ID do espaço de trabalho não é aceite no URL, na cadeia de consulta nem no corpo do pedido. Cada token de acesso está vinculado a exatamente um espaço de trabalho, e a API obtém cpoId da identidade autenticada do token. Se um local, carregador, utilizador, tarifa, perfil, atribuição ou transação aninhado não pertencer a esse espaço, a API devolve a mesma resposta 404 RESOURCE_NOT_FOUND, sem permitir descobrir a existência de recursos.

Obter um token de acesso

Um administrador do espaço de trabalho cria tokens nas Definições do espaço de trabalho, em Acesso à API. A gestão de tokens não é intencionalmente disponibilizada aos tokens do espaço de trabalho.

• O acesso à API está incluído em todos os planos, incluindo o Free. O administrador tem de ter permissão para editar o espaço de trabalho.
• O anfitrião do espaço de trabalho tem de ativar a Admin API através de adminApiEnabled; caso contrário, um token válido recebe uma resposta 404 que não revela a existência de recursos a partir de app-api.
• O administrador só pode conceder âmbitos permitidos pelas suas permissões atuais e pelos direitos do espaço de trabalho.
• Os novos tokens podem não expirar (predefinição das Definições do espaço de trabalho) ou ter uma duração de 1 a 365 dias inteiros selecionada pelo administrador; o servidor calcula as datas de expiração absolutas finitas. Os tokens sem expiração mantêm-se válidos até serem revogados.
• Um espaço de trabalho pode ter, no máximo, 50 tokens ativos.
• A credencial em texto simples é mostrada uma vez. Guarde-a imediatamente num gestor de segredos.
• O nome, os âmbitos e a validade são imutáveis. Para rodar o token, crie um substituto, implemente-o, verifique-o e revogue o antigo.
• A revogação é imediata; as linhas revogadas continuam visíveis como histórico imutável do espaço de trabalho com dados sensíveis ocultos, e não existe endpoint de introspeção do bearer token nem de eliminação definitiva.

app-api não tem um endpoint para emitir, renovar, listar ou revogar estas credenciais. Obter o token é, por isso, um pré-requisito realizado através do portal de administração humano, não outro endpoint desta referência.

Nunca coloque o token no controlo de versões, URLs, cadeias de consulta, cookies, registos, análises ou relatórios de erros.

Autenticação

Envie exatamente um cabeçalho no estilo RFC 6750 em cada pedido:

Authorization: Bearer evc_ws_<selector>.<secret>

A credencial opaca exata é evc_ws_, seguida de um seletor base64url canónico de 16 caracteres, . e um segredo base64url canónico de 43 caracteres. Envie a credencial completa sem alterações; não volte a codificá-la em base64.

A API rejeita cabeçalhos de autorização duplicados, valores unidos por vírgulas, outros esquemas, valores bearer vazios, JWTs de clientes e credenciais fornecidas fora deste cabeçalho.

Tokens malformados, desconhecidos, expirados, revogados ou inválidos por outro motivo recebem a mesma resposta:

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

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

O serviço verifica o estado do token e os direitos atuais do espaço de trabalho em cada pedido. Remover um direito pode, assim, desativar os âmbitos afetados antes da expiração do token.

Os tokens de espaço de trabalho são credenciais opacas, não JWTs. Não têm token de renovação e não existe endpoint de renovação. Um token finito deixa de autenticar no seu expiresAt absoluto; um token sem expiração mantém-se válido até ser revogado. A rotação consiste em criar uma credencial de substituição no portal, implementá-la no cliente e revogar a antiga.

Convenções dos pedidos

• Use Content-Type: application/json nos pedidos com corpo JSON.
• Os valores opcionais X-Request-Id do pedido são aparados e aceites apenas se contiverem entre 1 e 128 caracteres de A-Z, a-z, 0-9, ., _, : ou -; caso contrário, o servidor gera um UUID. Todas as respostas devolvem o valor selecionado como X-Request-Id.
• O X-Error-Format: envelope opcional converte todas as respostas de erro JSON para o envelope estruturado documentado no Contrato de respostas e erros. Qualquer outro valor preserva o corpo de compatibilidade predefinido.
• Os IDs nos parâmetros de caminho são inteiros positivos. Os IDs de tokens de acesso devolvidos pelo portal são cadeias decimais, pois são valores de base de dados de 64 bits sem sinal.
• Os valores de data e hora são cadeias RFC 3339 com desvio explícito, por exemplo 2026-08-13T12:30:00Z.
• As eliminações bem-sucedidas normalmente devolvem 204 No Content.
• As operações de criação normalmente devolvem 201 Created.
• O trabalho OCPP apenas colocado em fila pode devolver 202 Accepted; não o interprete como confirmação do carregador, salvo indicação explícita da resposta.
• As respostas autenticadas usam Cache-Control: no-store. Os endpoints de QR e exportação de relatórios devolvem corpos binários com cabeçalhos de conteúdo explícitos.
• As origens de navegador permitidas podem ler X-Request-Id, Idempotency-Replayed, Retry-After e Content-Disposition através de CORS. Isto permite correlacionar pedidos, detetar repetições idempotentes, respeitar os tempos de nova tentativa e manter os nomes de ficheiro de transferência escolhidos pelo servidor.

Idempotência

Todos os pedidos administrativos POST, PUT, PATCH e DELETE têm de incluir um cabeçalho Idempotency-Key. As chaves contêm entre 1 e 255 caracteres visíveis e são limitadas ao token, método e caminho.

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

Reutilizar uma chave concluída com o mesmo URL e corpo repete a resposta guardada e acrescenta:

Idempotency-Replayed: true

Reutilizar uma chave com um pedido diferente devolve 409 IDEMPOTENCY_CONFLICT. Um pedido ainda em processamento devolve 409 IDEMPOTENT_REQUEST_PROCESSING com Retry-After: 5.

As respostas concluídas e os resultados terminais são mantidos para repetição ou reconciliação durante sete dias após a última atualização. Depois desse período, a mesma chave pode ser tratada como um novo comando, pelo que os clientes têm de usar chaves globalmente únicas e não as devem reutilizar intencionalmente.

Se a concessão de processamento expirar, a ligação fechar após o início da execução ou a operação devolver um erro de servidor, a API não consegue provar com segurança se ocorreu um efeito externo. Durante os sete dias de retenção, a chave fica definitivamente indeterminada e devolve 409 IDEMPOTENCY_OUTCOME_UNKNOWN; não é recuperada nem executada automaticamente de novo. Verifique os efeitos antes de recuperar manualmente e não envie a mesma operação com uma nova chave até concluir a reconciliação.

Todos os endpoints administrativos que alteram dados, incluindo POST /reports/send, exigem Idempotency-Key.

Limites de pedidos

Os limites aplicam-se ao token individual e ao respetivo espaço de trabalho. As predefinições no repositório são:

Um pedido limitado devolve 429 Too Many Requests e um cabeçalho Retry-After. As implementações podem substituir estes valores.

Erros

Os erros JSON usam um code estável quando o cliente precisa de distinguir casos:

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

Os erros de validação usam arrays de campos:

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

Os estados comuns são:

Catálogo de âmbitos

O catálogo de âmbitos seguinte é usado quando um administrador cria um token. Um âmbito de escrita ou de elevado impacto pode implicar o âmbito de leitura correspondente, mas âmbitos de leitura nunca concedem escrita. Os âmbitos disponíveis dependem das permissões do administrador e das funções ativadas no espaço de trabalho.

O próprio acesso à API está incluído em todos os planos e é controlado pela definição adminApiEnabled do anfitrião. Os direitos de funções adicionais acima continuam a aplicar-se; o acesso à API não concede funções fora do plano do espaço de trabalho.

Referência de endpoints

As tabelas abaixo listam todas as 87 rotas de administração do espaço de trabalho. Todos os âmbitos de uma célula são obrigatórios.

Espaço de trabalho

Campos de atualização parcial do espaço de trabalho: name, email, website, addressLine1, addressLine2, postalCode, city, state e countryId. É obrigatório pelo menos um campo. As cadeias vazias que permitem null são normalizadas para null.

Locais e gestão de potência

Os corpos de criação e atualização parcial de locais usam:

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

A geocodificação de locais aceita os campos de consulta opcionais street, city, state, country e countryCode de duas letras, mais o cabeçalho Accept-Language. A pesquisa combinada de rua/cidade/estado tem de conter pelo menos dois caracteres. As respostas contêm apenas placeId, displayName, latitude e longitude; não são expostas credenciais nem metadados específicos do fornecedor. O servidor aplica a fila partilhada de um pedido por segundo, tempo limite de oito segundos, cache limitada de 24 horas e limites globais de pedidos dos tokens do espaço de trabalho.

A gestão de potência aceita { "pools": [...] }. Um grupo tem id, name, limit, meterSources opcional e children recursivos. Um carregador subordinado tem chargepointId e priority. A API limita a árvore e o número de contadores e executa limpeza OCPP e revalidação em duas fases ao substituir o estado instalado. Uma alteração recusada, com tempo esgotado ou em conflito concorrente devolve 409 POWER_MANAGEMENT_CONFLICT, preservando a configuração anterior.

Carregadores

Os parâmetros de consulta dos registos do carregador são cursor, limit (predefinição 50, máximo 200), from, to, action, direction e levelId. Os parâmetros de sessões são page, limit (predefinição 25, máximo 100), from, to e customerId (um ID positivo ou unknown). O histórico de agendamentos compostos usa cursor, limit (predefinição 20, máximo 50) e connectorId opcional.

Relatórios

Os filtros dos dados e da exportação de relatórios são from, to, siteId, chargerId, userId, anonymous e active. from/to usam, por predefinição, os últimos 90 dias e não podem abranger mais de 90 dias. userId não pode ser combinado com anonymous=true.

• Paginação dos dados: cursor opaco, predefinição limit=50, máximo 100.
• Medições: transactionLogId obrigatório, cursor opaco, predefinição limit=500, máximo 1 000.
• Exportação: format=csv|pdf, predefinição csv, limite rígido de 2 000 linhas.
• As respostas de exportação usam Content-Disposition: attachment, Cache-Control: private, no-store e X-Content-Type-Options: nosniff.

Corpo do agendamento:

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

sendDay é de 1 a 28 e sendTime é interpretado em UTC. O agendador recupera um minuto agendado perdido durante o mês de entrega atual. As preparações que falham antes da entrega repetem após 5 e 10 minutos, uma reserva building interrompida pode ser recuperada após 30 minutos e o envio automático para após três tentativas. O agendador persiste indeterminate imediatamente antes da entrega SMTP; tanto indeterminate como o estado antigo sending são terminais, pois repetir automaticamente qualquer um pode enviar um anexo duplicado. Os operadores têm de reconciliar estes resultados manualmente antes de alterar o estado do agendamento. Cada ciclo seleciona, no máximo, dez agendamentos, deixa de iniciar trabalho após um orçamento de 45 segundos e usa tempos limite SMTP limitados. A tarefa está desativada por predefinição e tem de ser ativada explicitamente após validar SMTP e capacidade. O agendamento da API pertence ao espaço de trabalho, não usando a identidade da pessoa que criou o token.

Tarifas

O corpo de uma tarifa contém name, exatamente um de currencyId, currencyCode ou currency, biddingZoneId opcional e tax. O corpo de uma atribuição é:

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

Ao criar uma atribuição, a tarifa aplica-se a todos os conectores físicos se connectorId for omitido ou definido explicitamente como 0. As atualizações visam uma atribuição persistida e, por isso, exigem um connectorId físico positivo explícito; 0 é rejeitado.

Um componente contém typeId, seasonId, price, priority opcional e limites de validade opcionais por mês, dia da semana e hora.

Perfis de carregamento

Os campos de metadados do perfil são label, locationId, stackLevel, purposeId, kindId, recurrencyKindId opcional, validFrom, validTo, startSchedule, rateUnitId e minChargingRate opcional. Um período do agendamento contém startPeriod, limit e numberOfPhases opcional. Um corpo de atribuição contém profileId e connectorId (predefinição 0).

As eliminações de perfis e a substituição da gestão de potência podem aguardar a confirmação do carregador. Uma rejeição, tempo esgotado ou alteração concorrente de estado devolve um conflito e mantém a configuração na base de dados, em vez de fingir que o carregador foi limpo.

Utilizadores, convites, RFID, acesso e limites

A paginação de veículos e de utilizadores status=members usa um cursor numérico positivo. As páginas de convites usam um cursor i2.* opaco, enquanto status=all usa um cursor composto a2.* opaco após a primeira página (um cursor numérico só continua válido como continuação do fluxo de membros antigo). A pesquisa de utilizadores é enviada no cabeçalho X-Admin-User-Search para evitar colocar emails nos URLs ou registos de acesso. limit tem predefinição 50 e máximo 100; a lista de utilizadores suporta status=all|members|invitations. Trate todos os cursores devolvidos como opacos e devolva-os inalterados.

A criação direta de utilizadores não cria uma palavra-passe, identidade de início de sessão ou sessão. Apenas associa um cliente já registado. Para um email desconhecido, use o endpoint de convite. O utilizador de sistema Tagless protegido não pode ser alterado através destas rotas.

Exemplos

Defina valores na shell sem imprimir o token:

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

Listar locais:

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

Crie um local em segurança:

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"

Descarregue um relatório CSV para um intervalo UTC explícito:

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"

Exclusões deliberadas

A API com tokens de espaço de trabalho não expõe operações que exigem uma identidade humana ou autoridade mais ampla. Estas incluem:

• criar, revelar, rodar ou revogar tokens com outro token;
• início de sessão, reposição de palavra-passe, sessões, delegação de funções ou privilégios humanos e alterações de propriedade do espaço de trabalho;
• criação/eliminação de espaços de trabalho e associação a contas de faturação;
• definições de pagamento, adesão Stripe, planos, faturas e faturação do anfitrião;
• operações de suporte ao nível do anfitrião e webhooks de fornecedores;
• notificações para pessoas, redirecionamentos de navegação, recursos de marca e rotas de desenvolvimento/teste.