Demandas do Equipamento

Listar Demandas

Endpoint que lista as demandas de um equipamento por período.

Method URI Headers Authorization
GET /api/v4/demands/day Content-Type:application/json Authorization: Bearer {token}

Parameters

measurement_id: 1 (integer, required) - "ID da medição do equipamento."
start_date: "2024-01-15" (string, required) - "Data inicial no formato Y-m-d."
end_date: "2024-01-20" (string, optional) - "Data final no formato Y-m-d. Se não fornecido, usa start_date."

Regras de Negócio

  • O parâmetro end_date é opcional. Quando não fornecido, o sistema usa automaticamente o start_date como data final, retornando apenas os dados daquele dia específico.
  • O end_date deve ser maior ou igual ao start_date.
  • O usuário deve ter permissão de acesso ao equipamento (exceto Super Admin).
  • Requer permissão list-dashboard para acessar a rota.

Permissões

  • Super Admin: Pode acessar qualquer equipamento sem restrições de permissão.
  • Account Admin: Deve ter permissão explícita para acessar o equipamento através da entidade AccountsEntity.

Response

{success} Response 200 (application/json)

Retorna as demandas do equipamento no período especificado.

{
  "items": [
    {
      "measurement_id": 1,
      "timestamp": 1705305600,
      "active": 9.999999,
      "reactive": 19.999999
    },
    {
      "measurement_id": 1,
      "timestamp": 1705309200,
      "active": 10.5,
      "reactive": 20.8
    }
  ]
}

{primary} Response 204

Quando não há demandas no período especificado, o corpo da resposta é vazio.

{danger} Response 403 (application/json)

Quando o usuário não possui a permissão list-dashboard.

[
  "Permissões insuficientes!"
]

{warning} Response 422 (application/json)

Erros de validação dos parâmetros.

{
    "measurement_id": [
        "O campo measurement id é obrigatório.",
        "O campo measurement id deve ser um número inteiro.",
        "O campo measurement id selecionado é inválido.",
        "Permissões insuficientes para esse grupo econômico"
    ],
    "start_date": [
        "O campo start date é obrigatório.",
        "O campo start date não corresponde ao formato Y-m-d."
    ],
    "end_date": [
        "O campo end date não corresponde ao formato Y-m-d.",
        "O campo end date deve ser uma data posterior ou igual a start date."
    ]
}

{warning} Response 400 (application/json)

Quando ocorre algum erro interno ao processar a requisição.

[
  "Ocorreu um erro ao processar sua solicitação"
]

Exemplos de Uso

Exemplo 1: Buscar demandas de um único dia

GET /api/v4/demands/day?measurement_id=1&start_date=2024-01-15

Retorna apenas as demandas do dia 2024-01-15 (end_date é automaticamente igual ao start_date).

Exemplo 2: Buscar demandas de um período

GET /api/v4/demands/day?measurement_id=1&start_date=2024-01-15&end_date=2024-01-20

Retorna todas as demandas entre 2024-01-15 00:00:00 e 2024-01-20 23:59:59.

Exemplo 3: Filtrar por equipamento específico

GET /api/v4/demands/day?measurement_id=5&start_date=2024-01-15&end_date=2024-01-15

Retorna apenas as demandas do equipamento com ID 5 no dia 2024-01-15.

Estrutura dos Dados Retornados

Campo Tipo Descrição
measurement_id integer ID do equipamento/medição
timestamp integer Timestamp Unix da demanda
active float Demanda ativa (kW). Retorna ativo_original se disponível, caso contrário demanda_ativa
reactive float Demanda reativa (kVAr). Retorna reativo_original se disponível, caso contrário demanda_reativa