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.
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:
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"
}
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:
- todos os comercializadores e todas as ofertas publicadas, do mercado regulado (CUR) ao mercado livre;
- o ciclo semanal e o ciclo diário, nas opções simples, bi-horária e tri-horária: o ciclo escolhe-se com o operador de rede, à parte da oferta, e muda as horas de cada período;
- a potência contratada, que determina também o IVA reduzido;
- os preços de compensação de excedentes, para clientes em autoconsumo.
| 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 |
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 | 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.
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.