Documentação da API externa

A integração por chave de API concede acesso ao Calendário, Projetos, Clientes e Componentes. Isso oferece flexibilidade para integrar seus sistemas e automatizar processos.

Sumário

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 dos Filtros
9. Modelo de Permissões
10. Tratamento de Erros
11. Padrões de Integração
12. Estabilidade & Versionamento

1. Autenticação

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

Authorization: Api-Key <raw_api_key>

Observações: - As chaves de API são criadas e gerenciadas pelos proprietários e administradores da empresa. - Cada chave tem escopo restrito a permissões específicas de recurso. - Todas as requisições são automaticamente limitadas ao escopo da empresa associada à chave de API.

Erros de Autenticação

2. Paginação

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

Parâmetros

Envelope de Resposta

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

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

3. API do Calendário

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

Endpoints

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

Permissão obrigatória: calendar_read

Exemplo de Resposta

{
  "id": "7d0f4d55-3b66-4c71-a86d-2b0ef2fca6d5",
  "category": "meeting",
  "subject": "Visita inicial ao local",
  "description": "Discuta os requisitos de 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 de Campos

Valores de Categoria

Objetos Aninhados

Objeto do cliente:

Objeto do 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 registros de projetos relacionados a clientes (por exemplo, instalações fotovoltaicas). Somente leitura.

Endpoints

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

Permissão obrigató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, Varsóvia",
  "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 andamento",
    "order": 2
  },
  "currency": {
    "code": "PLN",
    "name": "Złoty polonês"
  },
  "total_price": "42500.00",
  "payback_period": 8,
  "created": "2026-05-01T09:00:00Z",
  "updated": "2026-06-01T15:30:00Z"
}

Referência de Campos

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.

Objetos Aninhados

Objeto de status:

Objeto de 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 gravação.

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 obrigatórias: clients_read (leitura), clients_write (gravação)

Exemplo de Resposta

{
  "id": "4ab8e7cb-0a27-48f1-a0f6-6d6ecf5d8c6a",
  "name": "Solar Corp",
  "description": "Cliente comercial interessado em uma 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 de Campos

Criar cliente

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

{
  "name": "Nome do cliente",
  "description": "Cliente comercial",
  "address": "Endereço",
  "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 deseja atualizar:

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

Regras de coordenadas

• latitude e longitude devem sempre ser informados juntos.
• Informar apenas uma coordenada resulta em um erro de validação.
• Se nenhuma localização estiver definida, ambos os campos são retornados como null.

Filtros

6. API de Componentes

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

Endpoint

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

Permissão obrigatória: components_write

Tipos de componente

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

Módulo fotovoltaico

{
  "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
}

Outros

{
  "type": "other",
  "name": "Sistema de fixação",
  "unit": "pcs",
  "net_unit_price": "50.00"
}

Resposta

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

Observações

• Os fabricantes são criados automaticamente se não existirem.
• A unicidade do fabricante é limitada por empresa.
• Todos os campos específicos de módulos fotovoltaicos são validados antes da criação.

7. Convenções de Dados

IDs

Todos os identificadores de recurso são strings UUID, estáveis e globalmente exclusivos dentro de uma empresa:

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

Marcas de tempo

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

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

Geolocalização

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

"latitude": 52.2297,
"longitude": 21.0122

Tratamento de null

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

8. Comportamento dos Filtros

Regras gerais

• Todos os filtros são opcionais, salvo indicação em contrário.
• Vários filtros são combinados com lógica AND.
• Valores de filtro multisseleção (por exemplo, category) usam lógica OR internamente.
• Valores de filtro inválidos retornam resultados vazios ou um erro de validação, dependendo do tipo do campo.

Filtros de intervalo de datas

Disponíveis em todos os endpoints:

Filtros de busca textual

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

?name=solar

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

9. Modelo de Permissões

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

10. Tratamento de Erros

Formato do erro

Erro geral:

{
  "detail": "Mensagem de erro"
}

Erro de validação em nível de campo:

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

Referência de Erros

Lista de verificação de integração

Se você encontrar erros, verifique:

1. A chave de API possui as permissões corretas de recurso.
2. A conta da empresa está ativa.
3. Todos os valores de filtro (IDs etc.) pertencem ao mesmo escopo da empresa.

11. Padrões de Integração

Estratégia de sincronização

A abordagem recomendada para sincronizar dados:

1. Busque 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

Itere pelas páginas incrementando o offset até que next seja 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 buscar apenas registros alterados desde sua última sincronização:

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

Boas práticas de filtragem

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

12. Estabilidade & Versionamento

Garantias estáveis

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

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

Sujeito a alterações (sem quebra de compatibilidade)

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

Política de versionamento

Nenhuma versão explícita é exposta atualmente na URL. Mudanças que quebram compatibilidade introduzirão um novo namespace de endpoints:

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

Mudanças aditivas são consideradas não disruptivas e podem ser implantadas sem incremento de versão.

Fim da documentação