\n

Documentação externa da API

\n

\n

A integração baseada em chave de API concede-lhe acesso ao Calendário, aos Projetos, aos Clientes e aos Componentes.\nIsto dá-lhe flexibilidade para integrar com os seus sistemas e automatizar processos.

\n

\n

---

\n

Índice

\n

\n
1. Autenticação
\n
2. Paginação
\n
3. API do Calendário
\n
4. API de Projetos
\n
5. API de Clientes
\n
6. API de Componentes
\n
7. Convenções de dados
\n
8. Comportamento da filtragem
\n
9. Modelo de permissões
\n
10. Tratamento de erros
\n
11. Padrões de integração
\n
12. Estabilidade e versionamento
\n

\n

---

\n

1. Autenticação

\n

Todos os pedidos devem incluir uma chave de API no cabeçalho do pedido.

\n

Authorization: Api-Key <raw_api_key>\n

\n

Notas:\n- As chaves de API são criadas e geridas pelos proprietários e administradores da empresa.\n- Cada chave está limitada a permissões específicas de recursos.\n- Todos os pedidos são automaticamente limitados à empresa associada à chave de API.

\n

Erros de autenticação

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Estado	Motivo
401	Chave de API em falta ou inválida
401	Cabeçalho de autorização malformado
401	Chave de API inativa
403	Permissão de recurso em falta
402	Empresa inativa

\n

---

\n

2. Paginação

\n

Os endpoints de listagem (Calendário, Projetos, Clientes) usam paginação limit/offset.

\n

Parâmetros

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parâmetro	Descrição	Predefinição	Máximo
limit	Número de resultados a devolver	100	500
offset	Deslocamento da paginação	0	—

\n

Envelope da resposta

\n

{\n  "count": 123,\n  "next": null,\n  "previous": null,\n  "results": []\n}\n

\n

Quando next é null, atingiu a última página.

\n

---

\n

3. API do Calendário

\n

Representa eventos agendados, como reuniões, telefonemas e instalações. Só leitura.

\n

Endpoints

\n

GET https://api-production.easysolar-app.com/integrations/calendar/\nGET https://api-production.easysolar-app.com/integrations/calendar/{id}/\n

\n

Permissão necessária: calendar_read

\n

Exemplo de resposta

\n

{\n  "id": "7d0f4d55-3b66-4c71-a86d-2b0ef2fca6d5",\n  "category": "meeting",\n  "subject": "Visita inicial ao local",\n  "description": "Discutir os requisitos da instalação e a inspeção do telhado.",\n  "client": {\n    "id": "4ab8e7cb-0a27-48f1-a0f6-6d6ecf5d8c6a",\n    "name": "Solar Corp",\n    "address": "Rua Principal 10, Varsóvia",\n    "phone": "+48123456789",\n    "is_open": true\n  },\n  "participants": [\n    {\n      "first_name": "John",\n      "last_name": "Smith",\n      "email": "john.smith@example.com"\n    }\n  ],\n  "start_at": "2026-06-15T09:00:00Z",\n  "end_at": "2026-06-15T10:00:00Z",\n  "full_day": false,\n  "created_at": "2026-06-01T12:30:45Z"\n}\n

\n

Referência dos campos

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Campo	Tipo	Descrição
id	UUID	Identificador do evento
category	string	Categoria do evento (ver os valores abaixo)
subject	string	Título do evento
description	string	Notas adicionais do evento
client	object | null	Cliente associado
participants	array	Colaboradores atribuídos ao evento
start_at	datetime	Hora de início do evento (UTC)
end_at	datetime	Hora de fim do evento (UTC)
full_day	boolean	Se o evento decorre durante todo o dia
created_at	datetime	Carimbo de data/hora de criação do evento

\n

Valores da categoria

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Valor	Descrição
meeting	Reunião
call	Telefonema
installation	Agendamento de instalação
contract	Assinatura de contrato
quotation	Apresentação da proposta

\n

Objetos aninhados

\n

Objeto cliente:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Campo	Tipo	Descrição
id	UUID	Identificador do cliente
name	string	Nome do cliente
address	string	Morada do cliente
phone	string	Número de telefone do cliente
is_open	boolean	Estado ativo do cliente

\n

Objeto participante:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Campo	Tipo	Descrição
first_name	string	Nome próprio do colaborador
last_name	string	Apelido do colaborador
email	string	Endereço de e-mail do colaborador

\n

Filtros

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parâmetro	Tipo	Descrição
start_at_after	datetime	Filtrar eventos que comecem após esta hora
start_at_before	datetime	Filtrar eventos que comecem antes desta hora
end_at_after	datetime	Filtrar eventos que terminem após esta hora
end_at_before	datetime	Filtrar eventos que terminem antes desta hora
category	string (múltiplo)	Filtrar por categoria; repetir para vários valores
client	UUID	Filtrar por ID do cliente

\n

Exemplo:

\n

GET https://api-production.easysolar-app.com/integrations/calendar/?start_at_after=2026-01-01T00:00:00Z&category=meeting&category=call\nAuthorization: Api-Key <key>\n

\n

---

\n

4. API de Projetos

\n

Representa registos de projetos associados a clientes (por exemplo, instalações fotovoltaicas). Só leitura.

\n

Endpoints

\n

GET https://api-production.easysolar-app.com/integrations/projects/\nGET https://api-production.easysolar-app.com/integrations/projects/{id}/\n

\n

Permissão necessária: projects_read

\n

Exemplo de resposta

\n

{\n  "id": "d8e22cb9-1d88-4a3d-a3fd-f954d1f23d59",\n  "name": "Instalação fotovoltaica - Escritório de Varsóvia",\n  "address": "Aleje Jerozolimskie 120, Varsóvia",\n  "latitude": 52.2297,\n  "longitude": 21.0122,\n  "client": {\n    "id": "4ab8e7cb-0a27-48f1-a0f6-6d6ecf5d8c6a",\n    "name": "Solar Corp",\n    "address": "Rua Principal 10, Varsóvia",\n    "phone": "+48123456789",\n    "is_open": true\n  },\n  "status": {\n    "name": "Em curso",\n    "order": 2\n  },\n  "currency": {\n    "code": "PLN",\n    "name": "Zloty polaco"\n  },\n  "total_price": "42500.00",\n  "payback_period": 8,\n  "created": "2026-05-01T09:00:00Z",\n  "updated": "2026-06-01T15:30:00Z"\n}\n

\n

Referência dos campos

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Campo	Tipo	Descrição
id	UUID	Identificador do projeto
name	string	Nome do projeto
address	string	Morada do projeto
latitude	decimal | null	Latitude do projeto
longitude	decimal | null	Longitude do projeto
client	object	Cliente associado (ver Objeto cliente)
status	object	Estado do projeto
currency	object	Moeda utilizada nos valores financeiros
total_price	decimal string	Preço total atual do projeto
payback_period	integer | null	Período estimado de retorno do investimento em anos
created	datetime	Carimbo de data/hora de criação
updated	datetime	Carimbo de data/hora da última atualização

\n

\n

total_price é devolvido como uma string decimal para preservar a precisão. payback_period é null se ainda não tiver sido calculado. latitude/longitude são null se não estiver definida qualquer localização.

\n

\n

Objetos aninhados

\n

Objeto estado:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Campo	Tipo	Descrição
name	string	Nome de exibição do estado
order	integer	Valor de ordenação do estado

\n

Objeto moeda:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Campo	Tipo	Descrição
code	string	Código da moeda ISO
name	string	Nome da moeda

\n

Filtros

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parâmetro	Tipo	Descrição
created_after	datetime	Filtrar por data de criação (limite inferior)
created_before	datetime	Filtrar por data de criação (limite superior)
updated_after	datetime	Filtrar por data de atualização (limite inferior)
updated_before	datetime	Filtrar por data de atualização (limite superior)
client	UUID	Filtrar por ID do cliente
status	UUID	Filtrar por ID do estado
name	string	Correspondência parcial de nome sem distinção entre maiúsculas e minúsculas

\n

Exemplo:

\n

GET https://api-production.easysolar-app.com/integrations/projects/?client=<id>&name=solar\nAuthorization: Api-Key <key>\n

\n

---

\n

5. API de Clientes

\n

Representa entidades de clientes. Suporta operações de leitura e escrita.

\n

Endpoints

\n

GET    https://api-production.easysolar-app.com/integrations/clients/\nPOST   https://api-production.easysolar-app.com/integrations/clients/\nGET    https://api-production.easysolar-app.com/integrations/clients/{id}/\nPATCH  https://api-production.easysolar-app.com/integrations/clients/{id}/\n

\n

Permissões necessárias: clients_read (leitura), clients_write (escrita)

\n

Exemplo de resposta

\n

{\n  "id": "4ab8e7cb-0a27-48f1-a0f6-6d6ecf5d8c6a",\n  "name": "Solar Corp",\n  "description": "Cliente comercial interessado numa instalação fotovoltaica em telhado.",\n  "address": "Rua Principal 10, Varsóvia",\n  "latitude": 52.2297,\n  "longitude": 21.0122,\n  "phone": "+48123456789",\n  "is_open": true,\n  "created": "2026-05-01T10:15:00Z",\n  "updated": "2026-06-01T08:45:30Z"\n}\n

\n

Referência dos campos

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Campo	Tipo	Descrição
id	UUID	Identificador do cliente
name	string	Nome do cliente
description	string	Notas adicionais
address	string	Morada do cliente
latitude	decimal | null	Latitude do cliente
longitude	decimal | null	Longitude do cliente
phone	string | null	Número de telefone do cliente
is_open	boolean	Indica se o cliente está atualmente ativo
created	datetime	Carimbo de data/hora de criação
updated	datetime	Carimbo de data/hora da última atualização

\n

Criar cliente

\n

POST https://api-production.easysolar-app.com/integrations/clients/\n

\n

{\n  "name": "Nome do cliente",\n  "description": "Cliente comercial",\n  "address": "Morada",\n  "phone": "+48123456789",\n  "latitude": 52.2297,\n  "longitude": 21.0122\n}\n

\n

Atualizar cliente

\n

PATCH https://api-production.easysolar-app.com/integrations/clients/{id}/\n

\n

Inclua apenas os campos que pretende atualizar:

\n

{\n  "address": "Nova Morada 15, Varsóvia",\n  "phone": "+48987654321"\n}\n

\n

Regras de coordenadas

\n

\n
• latitude e longitude devem ser sempre fornecidas em conjunto.
\n
• Fornecer apenas uma coordenada resulta num erro de validação.
\n
• Se não estiver definida qualquer localização, ambos os campos são devolvidos como null.
\n

\n

Filtros

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parâmetro	Tipo	Descrição
created_after	datetime	Filtrar por data de criação (limite inferior)
created_before	datetime	Filtrar por data de criação (limite superior)
updated_after	datetime	Filtrar por data de atualização (limite inferior)
updated_before	datetime	Filtrar por data de atualização (limite superior)
is_open	boolean	Filtrar por estado ativo (true ou false)
name	string	Correspondência parcial de nome sem distinção entre maiúsculas e minúsculas
phone	string	Correspondência parcial de telefone sem distinção entre maiúsculas e minúsculas

\n

---

\n

6. API de Componentes

\n

Cria componentes para utilização em projetos. Só escrita.

\n

Endpoints

\n

POST https://api-production.easysolar-app.com/integrations/components/\n

\n

Permissão necessária: components_write

\n

Tipos de componentes

\n

São suportados três tipos de componente: panel, inverter e other.

\n

---

\n

Painel fotovoltaico

\n

{\n  "type": "panel",\n  "manufacturer_name": "Longi",\n  "name": "LR5-54HPH",\n  "net_unit_price": "120.00",\n  "nominal_power": "430.000",\n  "length": "1.7220",\n  "width": "1.1340",\n  "weight": "21.500",\n  "efficiency": "0.2100000",\n  "short_circuit_current": "13.52000",\n  "open_circuit_voltage": "37.85000",\n  "current_temperature_coefficient": "0.045000",\n  "voltage_temperature_coefficient": "-0.280000",\n  "power_temperature_coefficient": "-0.350000"\n}\n

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Campo	Tipo	Obrigatório	Descrição
type	string	Sim	Tem de ser \"panel\"
manufacturer_name	string	Sim	Nome do fabricante
name	string	Sim	Nome do modelo do painel
net_unit_price	decimal	Não	Preço unitário líquido
nominal_power	decimal	Sim	Potência nominal (W)
length	decimal	Sim	Comprimento do painel (m)
width	decimal	Sim	Largura do painel (m)
weight	decimal | null	Não	Peso (kg)
efficiency	decimal	Sim	Eficiência de conversão
short_circuit_current	decimal	Sim	Corrente de curto-circuito (A)
open_circuit_voltage	decimal	Sim	Tensão em circuito aberto (V)
current_temperature_coefficient	decimal | null	Não	Coeficiente de temperatura da corrente
voltage_temperature_coefficient	decimal | null	Não	Coeficiente de temperatura da tensão
power_temperature_coefficient	decimal | null	Não	Coeficiente de temperatura da potência

\n

---

\n

Inversor

\n

{\n  "type": "inverter",\n  "manufacturer_name": "SMA",\n  "name": "Sunny Tripower 5.0",\n  "net_unit_price": "900.00",\n  "nominal_power": "5000.000",\n  "number_of_dc_inputs": 2\n}\n

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Campo	Tipo	Obrigatório	Descrição
type	string	Sim	Tem de ser \"inverter\"
manufacturer_name	string	Sim	Nome do fabricante
name	string	Sim	Nome do modelo do inversor
net_unit_price	decimal	Não	Preço unitário líquido
nominal_power	decimal	Sim	Potência nominal (W)
number_of_dc_inputs	integer	Sim	Número de entradas CC

\n

---

\n

Outro

\n

{\n  "type": "other",\n  "name": "Estrutura de montagem",\n  "unit": "pcs",\n  "net_unit_price": "50.00"\n}\n

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Campo	Tipo	Obrigatório	Descrição
type	string	Sim	Tem de ser \"other\"
name	string	Sim	Nome do componente
unit	string	Não	Unidade de medida
net_unit_price	decimal	Não	Preço unitário líquido

\n

Resposta

\n

{\n  "id": "uuid",\n  "type": "panel | inverter | other",\n  "name": "string"\n}\n

\n

Notas

\n

\n
• Os fabricantes são criados automaticamente se não existirem.
\n
• A unicidade do fabricante está limitada a cada empresa.
\n
• Todos os campos específicos do painel são validados antes da criação.
\n

\n

---

\n

7. Convenções de dados

\n

IDs

\n

Todos os identificadores de recursos são strings UUID, estáveis e globalmente únicos dentro de uma empresa:

\n

\"id\": \"550e8400-e29b-41d4-a716-446655440000\"\n

\n

Carimbos de data/hora

\n

Todos os campos datetime são devolvidos no formato ISO 8601, sempre em UTC:

\n

\"created\": \"2026-06-09T12:34:56Z\"\n

\n

Geolocalização

\n

As coordenadas aplicam-se a Clientes e Projetos. São armazenadas como um ponto geográfico e devolvidas como campos separados:

\n

\"latitude\": 52.2297,\n\"longitude\": 21.0122\n

\n

Tratamento de valores nulos

\n

Os campos que não estão definidos são devolvidos como null — nunca são omitidos da resposta.

\n

---

\n

8. Comportamento da filtragem

\n

Regras gerais

\n

\n
• Todos os filtros são opcionais, salvo indicação em contrário.
\n
• Vários filtros são combinados com lógica AND.
\n
• Os valores de filtros de seleção múltipla (por exemplo, category) usam lógica OR internamente.
\n
• Valores de filtro inválidos devolvem resultados vazios ou um erro de validação, consoante o tipo de campo.
\n

\n

Filtros de intervalo de datas

\n

Disponíveis em vários endpoints:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Campos de filtro	Comportamento
created_after / created_before	Filtro de intervalo no carimbo de criação
updated_after / updated_before	Filtro de intervalo no carimbo da última atualização
start_at_after / start_at_before	Filtro de intervalo na hora de início do evento
end_at_after / end_at_before	Filtro de intervalo na hora de fim do evento

\n

Filtros de pesquisa textual

\n

Correspondência parcial sem distinção entre maiúsculas e minúsculas em name e phone:

\n

?name=solar\n

\n

Corresponde a: "Solar Corp", "O meu projeto solar", etc.

\n

---

\n

9. Modelo de permissões

\n

As permissões da chave de API são configuradas independentemente por recurso:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Recurso	Permissão de leitura	Permissão de escrita
Calendário	calendar_read	(não suportado)
Projetos	projects_read	(não suportado)
Clientes	clients_read	clients_write
Componentes	(não suportado)	components_write

\n

---

\n

10. Tratamento de erros

\n

Formato do erro

\n

Erro geral:

\n

{\n  "detail": "Mensagem de erro"\n}\n

\n

Erro de validação ao nível do campo:

\n

{\n  "field_name": ["Mensagem de erro"]\n}\n

\n

Referência de erros

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Estado	Categoria	Significado
401	Autenticação	Chave de API inválida, em falta ou inativa; cabeçalho malformado
402	Negócio	A empresa está inativa
403	Autorização	A chave de API não tem a permissão de recurso necessária
4xx	Validação	Erros ao nível do campo devolvidos como um objeto

\n

Lista de verificação da integração

\n

Se encontrar erros, verifique:

\n

\n
1. A chave de API tem as permissões corretas para o recurso.
\n
2. A conta da empresa está ativa.
\n
3. Todos os valores dos filtros (IDs, etc.) pertencem ao mesmo âmbito da empresa.
\n

\n

---

\n

11. Padrões de integração

\n

Estratégia de sincronização

\n

A abordagem recomendada para sincronizar dados:

\n

\n
1. Obtenha o endpoint de listagem (paginado).
\n
2. Armazene o id como referência externa.
\n
3. Use o campo updated para sincronizações incrementais.
\n

\n

Tratamento da paginação

\n

Percorra as páginas incrementando o offset até que next seja null:

\n

GET https://api-production.easysolar-app.com/integrations/clients/?limit=100&offset=0\nGET https://api-production.easysolar-app.com/integrations/clients/?limit=100&offset=100\n

\n

Sincronização incremental

\n

Use filtros de data para obter apenas os registos alterados desde a sua última sincronização:

\n

GET https://api-production.easysolar-app.com/integrations/projects/?updated_after=2026-01-01T00:00:00Z\n

\n

Boas práticas de filtragem

\n

\n
• Prefira filtros baseados em ID (client, status) em vez de pesquisas textuais para sincronizações de grande volume.
\n
• Combine vários filtros para reduzir o tamanho do conjunto de resultados.
\n
• Evite pesquisas textuais abrangentes em conjuntos de dados grandes.
\n

\n

---

\n

12. Estabilidade e versionamento

\n

Garantias estáveis

\n

O seguinte não mudará sem uma migração versionada:

\n

\n
• URLs dos endpoints
\n
• Nomes dos campos
\n
• Formato UUID
\n
• Estrutura da paginação
\n
• Esquema de autenticação
\n

\n

Sujeito a alterações (compatíveis)

\n

\n
• Filtros opcionais (podem ser adicionados novos filtros)
\n
• Enriquecimento da resposta (podem ser adicionados novos campos)
\n

\n

Política de versionamento

\n

Atualmente não é exposta nenhuma versão explícita na URL. Alterações incompatíveis introduzirão um novo namespace de endpoints:

\n

https://api-production.easysolar-app.com/integrations/v2/...\n

\n

As alterações aditivas são consideradas compatíveis e podem ser implementadas sem aumento de versão.

\n

---

\n

Fim da documentação

\n