Documentação da API Externa

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

Índice

1. Autenticação
2. Paginação
3. API do Calendário
4. API de Projetos
5. API de Clientes
6. API de Componentes
7. Convenções de Dados
8. Comportamento da Filtragem
9. Modelo de Permissões
10. Gestão de Erros
11. Padrões de Integração
12. Estabilidade & Versionamento

1. Autenticação

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

Authorization: Api-Key <raw_api_key>

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

Erros de Autenticação

2. Paginação

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

Parâmetros

Estrutura da resposta

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

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

3. API do Calendário

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

Endpoints

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

Permissão necessária: calendar_read

Exemplo de resposta

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

Referência dos campos

Valores da categoria

Objetos aninhados

Objeto cliente:

Objeto participante:

Filtros

Exemplo:

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

4. API de Projetos

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

Endpoints

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

Permissão necessária: projects_read

Exemplo de resposta

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

Referência dos campos

total_price é devolvido como 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 tiver sido definida nenhuma localização.

Objetos aninhados

Objeto estado:

Objeto moeda:

Filtros

Exemplo:

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

5. API de Clientes

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

Endpoints

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

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

Exemplo de resposta

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

Referência dos campos

Criar cliente

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

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

Atualizar cliente

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

Inclua apenas os campos que pretende atualizar:

{
  "address": "Nova morada 15, Varsóvia",
  "phone": "+48987654321"
}

Regras de coordenadas

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

Filtros

6. API de Componentes

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

Endpoint

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

Permissão necessária: components_write

Tipos de componente

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

Painel

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

Inversor

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

Outro

{
  "type": "other",
  "name": "Sistema de montagem",
  "unit": "pcs",
  "net_unit_price": "50.00"
}

Resposta

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

Notas

• Os fabricantes são criados automaticamente se não existirem.
• A unicidade do fabricante é limitada ao âmbito de cada empresa.
• Todos os campos específicos do painel são validados antes da criação.

7. Convenções de Dados

IDs

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

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

Marcas temporais

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

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

Geolocalização

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

"latitude": 52.2297,
"longitude": 21.0122

Tratamento de valores nulos

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

8. Comportamento da Filtragem

Regras Gerais

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

Filtros de Intervalo de Datas

Disponíveis em todos os endpoints:

Filtros de Pesquisa de Texto

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

?name=solar

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

9. Modelo de Permissões

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

10. Gestão de Erros

Formato do Erro

Erro geral:

{
  "detail": "Mensagem de erro"
}

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

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

Referência de Erros

Lista de Verificação da Integração

Se encontrar erros, verifique:

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

11. Padrões de Integração

Estratégia de Sincronização

A abordagem recomendada para sincronizar dados:

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

Tratamento da Paginação

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

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

Sincronização Incremental

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

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

Melhores Práticas de Filtragem

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

12. Estabilidade & Versionamento

Garantias Estáveis

Os seguintes elementos não serão alterados sem uma migração versionada:

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

Sujeito a Alterações (Não Disruptivas)

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

Política de Versionamento

Atualmente, não é exposta nenhuma versão explícita na URL. As alterações disruptivas introduzirão um novo namespace de endpoints:

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

As alterações aditivas são consideradas não disruptivas e podem ser implementadas sem alteração de versão.

Fim da documentação