\n

Documentação da API Externa

\n

\n

A integração baseada em chave de API dá a você acesso ao Calendário, Projetos, Clientes e Componentes.\nIsso lhe dá flexibilidade para integrar seus sistemas e automatizar processos.

\n

\n

---

\n

Sumário

\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 de 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

Todas as requisições devem incluir uma chave de API no cabeçalho da requisição.

\n

Authorization: Api-Key <raw_api_key>\n

\n

Observações:\n- As chaves de API são criadas e gerenciadas pelos proprietários e administradores da empresa.\n- Cada chave é limitada a permissões específicas de recursos.\n- Todas as requisições são automaticamente limitadas à 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

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

\n

---

\n

2. Paginação

\n

Os endpoints de listagem (Calendário, Projetos, Clientes) usam paginação por 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	Padrão	Máx.
limit	Número de resultados a retornar	100	500
offset	Offset de paginação	0	—

\n

Envelope da Resposta

\n

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

\n

Quando next for null, você chegou à última página.

\n

---

\n

3. API do Calendário

\n

Representa eventos agendados, como reuniões, ligações e instalações. Somente 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 (veja os valores abaixo)
subject	string	Título do evento
description	string	Observações adicionais do evento
client	object | null	Cliente vinculado
participants	array	Colaboradores atribuídos ao evento
start_at	datetime	Horário de início do evento (UTC)
end_at	datetime	Horário de término do evento (UTC)
full_day	boolean	Se o evento dura o dia inteiro
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	Ligação telefônica
installation	Agendamento de instalação
contract	Assinatura do 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	Endereço do cliente
phone	string	Número de telefone do cliente
is_open	boolean	Se o cliente está ativo no momento

\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 do colaborador
last_name	string	Sobrenome do colaborador
email	string	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 com início após este horário
start_at_before	datetime	Filtrar eventos com início antes deste horário
end_at_after	datetime	Filtrar eventos com término após este horário
end_at_before	datetime	Filtrar eventos com término antes deste horário
category	string (multi)	Filtrar por categoria; repita para vários valores
client	UUID	Filtrar pelo 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 registros de projetos relacionados ao cliente (por exemplo, instalações fotovoltaicas). Somente 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 andamento",\n    "order": 2\n  },\n  "currency": {\n    "code": "PLN",\n    "name": "zloty polonês"\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	Endereço do projeto
latitude	decimal | null	Latitude do projeto
longitude	decimal | null	Longitude do projeto
client	object	Cliente vinculado (veja o objeto Cliente)
status	object	Status do projeto
currency	object	Moeda usada nos valores financeiros
total_price	decimal string	Preço total atual do projeto
payback_period	integer | null	Período estimado de retorno 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 é retornado como string decimal para preservar a precisão. payback_period é null se ainda não tiver sido calculado. latitude/longitude são null se nenhuma localização estiver definida.

\n

\n

Objetos Aninhados

\n

Objeto Status:

\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 exibido do status
order	integer	Valor de ordenação do status

\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 ISO da moeda
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 pela data de criação (limite inferior)
created_before	datetime	Filtrar pela data de criação (limite superior)
updated_after	datetime	Filtrar pela data de atualização (limite inferior)
updated_before	datetime	Filtrar pela data de atualização (limite superior)
client	UUID	Filtrar pelo ID do cliente
status	UUID	Filtrar pelo ID do status
name	string	Correspondência parcial de nome sem diferenciar maiúsculas/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 gravação.

\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 (gravação)

\n

Exemplo de Resposta

\n

{\n  "id": "4ab8e7cb-0a27-48f1-a0f6-6d6ecf5d8c6a",\n  "name": "Solar Corp",\n  "description": "Cliente comercial interessado em uma 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	Observações adicionais
address	string	Endereço 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	Se o cliente está ativo no momento
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": "Endereço",\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 você deseja atualizar:

\n

{\n  "address": "Novo endereço 15, Varsóvia",\n  "phone": "+48987654321"\n}\n

\n

Regras de Coordenadas

\n

\n
• latitude e longitude devem sempre ser informados juntos.
\n
• Informar apenas uma coordenada resulta em um erro de validação.
\n
• Se nenhuma localização estiver definida, ambos os campos são retornados 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 pela data de criação (limite inferior)
created_before	datetime	Filtrar pela data de criação (limite superior)
updated_after	datetime	Filtrar pela data de atualização (limite inferior)
updated_before	datetime	Filtrar pela data de atualização (limite superior)
is_open	boolean	Filtrar pelo status ativo (true ou false)
name	string	Correspondência parcial de nome sem diferenciar maiúsculas/minúsculas
phone	string	Correspondência parcial de telefone sem diferenciar maiúsculas/minúsculas

\n

---

\n

6. API de Componentes

\n

Cria componentes para uso em projetos. Somente gravação.

\n

Endpoint

\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 componentes: panel, inverter e other.

\n

---

\n

Módulo 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	Deve ser "panel"
manufacturer_name	string	Sim	Nome do fabricante
name	string	Sim	Nome do modelo do módulo fotovoltaico
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 módulo fotovoltaico (m)
width	decimal	Sim	Largura do módulo fotovoltaico (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 de 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	Deve 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 fixação",\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	Deve 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

Observações

\n

\n
• Os fabricantes são criados automaticamente se não existirem.
\n
• O nome do fabricante é único por empresa.
\n
• Todos os campos específicos do módulo fotovoltaico são validados antes da criação.
\n

\n

---

\n

7. Convenções de Dados

\n

IDs

\n

Todos os identificadores de recurso 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 retornados no formato ISO 8601, sempre em UTC:

\n

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

\n

Geolocalização

\n

As coordenadas se aplicam a Clientes e Projetos. Elas são armazenadas como um ponto geográfico e retornadas em campos separados:

\n

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

\n

Tratamento de null

\n

Campos que não estão definidos são retornados como null — eles nunca são omitidos da resposta.

\n

---

\n

8. Comportamento de 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
• Valores de filtro com múltipla seleção (por exemplo, category) usam lógica OR internamente.
\n
• Valores de filtro inválidos retornam resultados vazios ou um erro de validação, dependendo do tipo do campo.
\n

\n

Filtros de Intervalo de Datas

\n

Disponíveis em todos os 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 do filtro	Comportamento
created_after / created_before	Filtro de intervalo no carimbo de data/hora de criação
updated_after / updated_before	Filtro de intervalo no carimbo de data/hora da última atualização
start_at_after / start_at_before	Filtro de intervalo no horário de início do evento
end_at_after / end_at_before	Filtro de intervalo no horário de término do evento

\n

Filtros de Busca Textual

\n

Correspondência parcial sem diferenciar maiúsculas/minúsculas em name e phone:

\n

?name=solar\n

\n

Corresponde a: "Solar Corp", "Meu Projeto Solar", etc.

\n

---

\n

9. Modelo de Permissões

\n

As permissões da chave de API são configuradas de forma independente 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 gravação
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 em nível de 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

Status	Categoria	Significado
401	Autenticação	Chave de API inválida, ausente ou inativa; cabeçalho malformado
402	Negócios	Empresa inativa
403	Autorização	A chave de API não possui a permissão de recurso necessária
4xx	Validação	Erros por campo retornados como um objeto

\n

Checklist de Integração

\n

Se encontrar erros, verifique:

\n

\n
1. A chave de API possui as permissões corretas para o recurso.
\n
2. A conta da empresa está ativa.
\n
3. Todos os valores de filtro (IDs etc.) pertencem ao mesmo escopo 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. Busque 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 buscar apenas registros alterados desde 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 buscas textuais para sincronizações de alto volume.
\n
• Combine vários filtros para reduzir o tamanho do conjunto de resultados.
\n
• Evite buscas textuais amplas em grandes conjuntos de dados.
\n

\n

---

\n

12. Estabilidade e Versionamento

\n

Garantias de Estabilidade

\n

Os itens a seguir não mudarão sem uma migração versionada:

\n

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

\n

Sujeito a Alterações (Sem Quebra)

\n

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

\n

Política de Versionamento

\n

Nenhuma versão explícita está atualmente exposta na URL. Mudanças que quebrem compatibilidade introduzirão um novo namespace de endpoint:

\n

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

\n

Alterações aditivas são consideradas sem quebra e podem ser implantadas sem aumento de versão.

\n

---

\n

Fim da documentação

\n