200+
Países cobertos
99%
das ofertas na Europa
3.700+
Comercializadores
23.000+
Ofertas

Porque é que um aparelho precisa de saber o preço da próxima hora?

Para integrar mais energia renovável na rede, é a procura que se deve adaptar à produção, e não o contrário. Esse papel cabe aos aparelhos comandáveis: termoacumulador ligado, carregador de veículo elétrico, bateria doméstica ou aquecimento gerido por uma aplicação.

O sinal que liga a oferta à procura é o preço, mas o aparelho tem de conseguir lê-lo. Um termoacumulador não sabe interpretar uma tarifa de eletricidade, e o seu fabricante não pode manter atualizadas as milhares de ofertas de um país, muito menos de quinze. É exatamente esse o vazio que esta API preenche: transforma uma oferta comercial, com as suas opções e particularidades locais, numa sucessão de períodos horários valorizados que uma máquina pode consumir.

Um termoacumulador que aquece durante as horas de vazio do seu proprietário, um carregador que atrasa uma hora a carga porque o kWh fica mais barato, ou uma bateria que se guarda para as horas de ponta: nos três casos, a decisão exige conhecer o preço futuro, e não o preço médio.

O que faz a API de planeamento da Selectra?

Qualifica o consumidor e apresenta em seguida o preço para os próximos períodos. São três pontos de entrada, chamados por esta ordem:

1
Qualificação
Código postal, comercializador, tarifa e opção
2
Deteção da tarifa
A tarifa e a opção são identificadas automaticamente
3
Planeamento do preço
Resposta JSON com períodos, preços e índices

A qualificação merece uma nota: é a própria API que constrói o questionário, mercado a mercado. Devolve a pergunta seguinte e as respostas admissíveis, e o integrador limita-se a mostrá-las. Ninguém, do lado do cliente, tem de manter a lista de comercializadores de um país nem a das suas opções, que mudam constantemente.

Que dados devolve a API?

A resposta é uma tabela JSON de períodos sucessivos. Cada um inclui uma data de início, uma data de fim, um preço do kWh, o nome do período tal como o comercializador o designa e a referência do índice correspondente no contador, o que permite relacionar um preço com um consumo realmente registado na sua fatura. A resposta indica ainda a moeda e a hora da próxima atualização.

{
  "prices": [
    {
      "name": "Ponta",
      "price": 0.2274,
      "start": "2026-09-09T10:30:00+01:00",
      "end": "2026-09-09T13:00:00+01:00",
      "distributor_reference": "1"
    },
    {
      "name": "Vazio",
      "price": 0.1120,
      "start": "2026-09-09T22:00:00+01:00",
      "end": "2026-09-10T08:00:00+01:00",
      "distributor_reference": "3"
    }
  ],
  "next_update": "2026-09-10T20:15:00+01:00",
  "currency": "EUR"
}
Extrato de resposta da API de planeamento de preços da Selectra, para uma tarifa tri-horária em ciclo diário, no verão. Os períodos contíguos com o mesmo preço e o mesmo nome são fundidos.

Que países estão cobertos?

A API de planeamento de preços de eletricidade da Selectra está agora disponível em mais de 200 países. Na Europa, cobre 99% de todas as ofertas publicadas — desde tarifas de preço fixo e por período horário até preços dinâmicos e de resposta à procura — e estende-se muito para além da Europa, até às Américas, à Ásia, à África, ao Médio Oriente e à Oceânia. Portugal está totalmente integrado.

À escala mundial, a API abrange mais de 3.700 comercializadores e mais de 23.000 ofertas, sendo acrescentados novos mercados regularmente. O mercado em questão é o residencial e as pequenas empresas — os únicos segmentos com preços publicados. As necessidades de maior potência têm, geralmente, preços personalizados.

Preço de compra e de venda

Em 38 mercados, Portugal incluído, a API devolve também o preço da energia injetada, ou seja, o que o cliente recebe ao vender os seus excedentes à rede. Uma casa em autoconsumo tem dois preços, não um só: otimizar sem o segundo é pilotar às cegas metade do problema. Em Portugal, esse preço é fixado por cada comercializador dentro da própria oferta, e não por uma tarifa nacional.

E em detalhe sobre Portugal?

Portugal não tem preços dinâmicos, mas tem um sistema de tarifas por período horário particularmente complexo. A API cobre as ofertas residenciais de 95% das casas em Portugal Continental, tanto no ciclo semanal como no ciclo diário, nas opções simples, bi-horária e tri-horária. O preço do kWh devolvido soma a componente de energia e as tarifas de rede reguladas, com impostos incluídos. A Madeira e os Açores têm um sistema elétrico distinto, com a mesma complexidade, e ainda não fazem parte da cobertura da API de planeamento. A API gere:

Atualmente, a API cobre em Portugal 31 comercializadores — dos grandes operadores às cooperativas e comercializadores regionais.
Ofertas de eletricidade cobertas pela API de planeamento, por comercializador
Comercializador Ofertas cobertas
Acciona 1
Alfa Energia 3
Audax 10
Axpo 1
Coopérnico 4
EDP 20
Elergone 1
Eletricidade dos Açores 1
Empresa de Eletricidade da Madeira 1
Endesa 13
EZU Energia 3
Galp 5
Goldenergy 7
Ibelectra 14
Iberdrola 4
JafPlus 2
Logica Energy 1
Luzboa 7
Luzigás 8
MEO Energia 3
Muon 4
Nabalia 3
Nossa Energia 1
Oeneo Energy 4
Plenitude 8
Portulogos 2
Repsol 1
SU Eletricidade 2
Usenergy 2
Yesenergy 2
Zug Power 1
Ofertas de eletricidade cobertas pela API de planeamento da Selectra, por comercializador. Fonte: Selectra (energy-core). Dados atualizados automaticamente.

A cobertura portuguesa completa, as tarifas e uma consola de teste estão na página de Portugal do catálogo.

E para ordenar todas as ofertas portuguesas? A API Comparador

A API de planeamento responde à pergunta «quanto vai custar a minha tarifa nas próximas horas?». A API Comparador da Selectra responde a outra: quanto custaria cada oferta do mercado a esta casa em concreto, da mais barata à mais cara? Alimenta páginas de comparação, ferramentas de mudança de comercializador e sistemas de faturação. Está ativa em oito mercados europeus e cobre em Portugal a eletricidade e o gás natural, em separado ou em conjunto, no Continente, na Madeira e nos Açores.

API de planeamento e API Comparador
API de planeamento API Comparador
Pergunta Quando é mais barata a eletricidade na minha tarifa? Que oferta é a mais barata para mim?
Dados de entrada O comercializador, a tarifa e a opção atuais da casa Um consumo anual, uma fatura ou o diagrama de carga do contador
Resposta Períodos com preço para as próximas horas Uma classificação de todas as ofertas, com o custo anual
Utilizadores típicos Fabricantes de aparelhos, HEMS, carregamento de veículos Comparadores, comercializadores, consultores de energia
Cobertura Mais de 200 países, eletricidade 8 mercados europeus, eletricidade e gás

Método 1: ordenar a partir do consumo anual ou de uma fatura

É disso que precisa uma página de comparação: o visitante conhece mais ou menos o seu consumo anual, não as horas a que consome. Uma única chamada GET recebe o consumo em kWh e a potência contratada, e devolve todas as ofertas ordenadas da mais barata à mais cara. Também pode tarifar uma só fatura, com o número de dias que ela cobre, em vez de um ano inteiro.

GET /v3/pt/compare?energy_type=electricity&client_type=domestic&car_base=3500&power=6.9

A potência não serve só para escolher a linha de preços: é também uma questão de impostos. Até 6,9 kVA, os primeiros 200 kWh de cada mês pagam IVA a 6% (300 kWh para famílias numerosas); acima, a fatura inteira paga a taxa normal. A API aplica ainda, se for o caso, a tarifa social, bem como a contribuição audiovisual e a taxa DGEG, iguais em todas as ofertas.

Método 2: ordenar a partir do diagrama de carga

É aqui que Portugal mais ganha com este método. Numa tarifa bi-horária ou tri-horária, o contador funciona num ciclo escolhido com o operador de rede, à parte da oferta: o ciclo diário repete os mesmos períodos todos os dias, o ciclo semanal dá horários próprios ao sábado e ao domingo. Mesmo comercializador, mesmos preços, horas diferentes: qual dos dois sai mais barato depende apenas de quando a casa consome. Envie as leituras do contador (até um ano completo, diretamente ou num ficheiro CSV) e a API tarifa a curva nos dois ciclos e devolve-os lado a lado. O IVA reduzido é calculado mês a mês, como na fatura real.

Eletricidade nacional, gás por município

Em Portugal, a eletricidade tem um preço nacional: uma tabela para o Continente e uma para cada arquipélago, sem morada a procurar. Só é preciso indicar se o contador está no Continente, na Madeira ou nos Açores, que mudam o IVA, e nos Açores também o relógio, uma hora atrás. O gás é diferente: a tarifa de rede é fixada por município, 58 dos 61 municípios com rede de gás publicam a sua, e a do Porto é cerca de metade da de Lisboa. Uma comparação de gás tem, por isso, de indicar o município.

O guia de integração português completo, parâmetro a parâmetro, está publicado em api.selectra.com/comparator/pt/guide, e a documentação técnica dos oito mercados em api.selectra.com/comparator/v3/reference.

Como aceder à API e quanto custa?

O acesso faz-se a partir do catálogo api.selectra.com, que disponibiliza a documentação, uma consola de teste e a subscrição. Um nível gratuito, sem cartão de crédito, abre os três pontos de entrada em todos os mercados cobertos: o suficiente para construir uma primeira integração e avaliar os dados antes de falar de contrato.

Depois, a faturação combina três elementos: uma mensalidade pelos mercados de que precisa (mercado a mercado ou em fórmula Europa), um preço por chamada que diminui com o volume, e custos de arranque que incluem o acompanhamento técnico até à entrada em produção. Os valores em vigor são apresentados em direto na página de tarifas do catálogo, uma vez que são lidos a partir da própria faturação.

A API Comparador segue o mesmo modelo: uma mensalidade por mercado (Portugal é vendido em separado), um preço por chamada e um acesso gratuito com um pacote de chamadas de teste para a experimentar com dados reais. Os mercados e as tarifas estão na página da API Comparador. Os pedidos repetidos não custam nada: quando uma resposta não mudou desde a última chamada, volta vazia e não é descontada da quota.

A quem se destina esta API?

Os integradores são de quatro famílias: os fabricantes de aparelhos comandáveis e os editores de sistemas de gestão de energia doméstica (HEMS), que precisam do preço para decidir quando ativar; os comercializadores de energia, que querem oferecer aos seus clientes a gestão inteligente do consumo sem reconstruir uma base tarifária; os agregadores de flexibilidade e de resposta à procura; e os operadores de carregamento de veículos elétricos, cujo valor consiste precisamente em saber deslocar uma carga algumas horas.

O ponto comum destas quatro famílias: nenhuma tem interesse em tornar-se editora de dados tarifários. Manter as tarifas de um só país ocupa já uma equipa a tempo inteiro, e a dificuldade não está no número de comercializadores, mas na velocidade a que as opções mudam.

Porque é que a Selectra oferece esta API?

A Selectra compara ofertas de eletricidade desde 2007. Os fundadores, Xavier Pinon e Aurian de Maupeou, anteciparam desde a liberalização do mercado a crescente complexidade das ofertas e a necessidade de melhor informação ao consumidor, baseada em dados de preços. A API de planeamento segue a mesma lógica: simplificar um tema complexo, ao serviço da eletrificação do consumo de energia.

A Selectra opera em 15 países e conta com uma equipa de 50 especialistas do mercado energético que mantêm os sites e as bases de dados atualizados em tempo real. Com mais de 100 milhões de euros de faturação em 2024 e 2000 colaboradores, tem os meios para sustentar essa manutenção ao longo do tempo — a única questão que importa quando se confia o dado tarifário a um terceiro.

Perguntas frequentes sobre a API de planeamento

Permite que um aparelho comandável — carregador de veículo elétrico, termoacumulador, bateria doméstica ou sistema de gestão de energia — conheça o preço do kWh nas próximas horas e desloque por si mesmo o consumo para os períodos mais baratos. É a peça que falta na maioria dos objetos ligados: sabem comandar o consumo, mas não a que preço.

Uma tabela JSON de períodos sucessivos. Cada entrada contém uma data de início, uma data de fim, o preço do kWh, o nome do período tarifário tal como o comercializador o designa («Vazio», «Ponta»…) e a referência do índice correspondente no contador, além da moeda e da hora da próxima atualização.

Não adivinha: pergunta. A primeira chamada abre um questionário curto cujas perguntas e respostas são construídas pela própria API, mercado a mercado. O integrador não tem de manter a lista de comercializadores nem a das suas opções: mostra o que a API lhe devolve.

O Continente, sim: a API cobre 95% das casas, com as ofertas residenciais publicadas de todos os comercializadores, o ciclo semanal e o ciclo diário, as opções simples, bi-horária e tri-horária e a compensação de excedentes. A Madeira e os Açores ainda não fazem parte da API de planeamento, mas estão cobertos pela API Comparador.

A API de planeamento parte da tarifa que uma casa já tem e indica a um aparelho quando a eletricidade será mais barata nas próximas horas. A API Comparador parte do consumo da casa (um total anual, uma fatura ou o diagrama de carga do contador) e ordena todas as ofertas de eletricidade e gás do mercado português segundo o que lhe custariam. A primeira serve os aparelhos inteligentes; a segunda, os comparadores e as ferramentas de mudança de comercializador.

Pode testá-la diretamente no catálogo api.selectra.com, com um acesso gratuito, sem cartão de crédito, que abre os três pontos de entrada em todos os mercados cobertos. A API Comparador tem o seu próprio acesso gratuito, com um pacote de chamadas de teste.

Uma questão sobre o seu caso de uso?

Teste a API livremente a partir do catálogo, ou contacte diretamente Aurian de Maupeou, cofundador da Selectra, através do +33 6 47 39 40 42.