Documentation de l'API externe

L'intégration basée sur une clé API vous donne accès au calendrier, aux projets, aux clients et aux composants. Cela vous offre la flexibilité nécessaire pour intégrer vos systèmes et automatiser les processus.

Table des matières

1. Authentification
2. Pagination
3. API du calendrier
4. API des projets
5. API des clients
6. API des composants
7. Conventions de données
8. Comportement des filtres
9. Modèle d'autorisations
10. Gestion des erreurs
11. Schémas d'intégration
12. Stabilité et versionnement

1. Authentification

Toutes les requêtes doivent inclure une clé API dans l'en-tête de la requête.

Authorization: Api-Key <raw_api_key>

Notes : - Les clés API sont créées et gérées par les propriétaires et les administrateurs de l'entreprise. - Chaque clé est limitée à des autorisations de ressources spécifiques. - Toutes les requêtes sont automatiquement limitées à l'entreprise associée à la clé API.

Erreurs d'authentification

2. Pagination

Les endpoints de liste (Calendrier, Projets, Clients) utilisent une pagination limit/offset.

Paramètres

Enveloppe de réponse

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

Lorsque next vaut null, vous avez atteint la dernière page.

3. API du calendrier

Représente les événements planifiés tels que les réunions, les appels et les rendez-vous d'installation. Lecture seule.

Endpoints

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

Autorisation requise : calendar_read

Exemple de réponse

{
  "id": "7d0f4d55-3b66-4c71-a86d-2b0ef2fca6d5",
  "category": "meeting",
  "subject": "Visite initiale du site",
  "description": "Discuter des besoins d'installation et de l'inspection de la toiture.",
  "client": {
    "id": "4ab8e7cb-0a27-48f1-a0f6-6d6ecf5d8c6a",
    "name": "Solar Corp",
    "address": "Rue Principale 10, Varsovie",
    "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"
}

Référence des champs

Valeurs de catégorie

Objets imbriqués

Objet client :

Objet participant :

Filtres

Exemple :

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 des projets

Représente les enregistrements de projets liés aux clients (p. ex. des installations photovoltaïques). Lecture seule.

Endpoints

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

Autorisation requise : projects_read

Exemple de réponse

{
  "id": "d8e22cb9-1d88-4a3d-a3fd-f954d1f23d59",
  "name": "Installation photovoltaïque - bureau de Varsovie",
  "address": "Aleje Jerozolimskie 120, Varsovie",
  "latitude": 52.2297,
  "longitude": 21.0122,
  "client": {
    "id": "4ab8e7cb-0a27-48f1-a0f6-6d6ecf5d8c6a",
    "name": "Solar Corp",
    "address": "Rue Principale 10, Varsovie",
    "phone": "+48123456789",
    "is_open": true
  },
  "status": {
    "name": "En cours",
    "order": 2
  },
  "currency": {
    "code": "PLN",
    "name": "złoty polonais"
  },
  "total_price": "42500.00",
  "payback_period": 8,
  "created": "2026-05-01T09:00:00Z",
  "updated": "2026-06-01T15:30:00Z"
}

Référence des champs

total_price est renvoyé sous forme de chaîne décimale afin de préserver la précision. payback_period vaut null s'il n'a pas encore été calculé. latitude/longitude valent null si aucun emplacement n'est défini.

Objets imbriqués

Objet de statut :

Objet devise :

Filtres

Exemple :

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

5. API des clients

Représente des entités clientes. Prend en charge les opérations de lecture et d'écriture.

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}/

Autorisations requises : clients_read (lecture), clients_write (écriture)

Exemple de réponse

{
  "id": "4ab8e7cb-0a27-48f1-a0f6-6d6ecf5d8c6a",
  "name": "Solar Corp",
  "description": "Client commercial intéressé par une installation photovoltaïque en toiture.",
  "address": "Rue Principale 10, Varsovie",
  "latitude": 52.2297,
  "longitude": 21.0122,
  "phone": "+48123456789",
  "is_open": true,
  "created": "2026-05-01T10:15:00Z",
  "updated": "2026-06-01T08:45:30Z"
}

Référence des champs

Créer un client

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

{
  "name": "Nom du client",
  "description": "Client commercial",
  "address": "Adresse",
  "phone": "+48123456789",
  "latitude": 52.2297,
  "longitude": 21.0122
}

Mettre à jour le client

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

N'incluez que les champs que vous souhaitez mettre à jour :

{
  "address": "Nouvelle adresse 15, Varsovie",
  "phone": "+48987654321"
}

Règles relatives aux coordonnées

• latitude et longitude doivent toujours être fournies ensemble.
• Le fait de fournir une seule coordonnée entraîne une erreur de validation.
• Si aucun emplacement n'est défini, les deux champs sont renvoyés à null.

Filtres

6. API des composants

Crée des composants à utiliser dans les projets. Écriture seule.

Endpoint

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

Autorisation requise : components_write

Types de composants

Trois types de composants sont pris en charge : panel, inverter et other.

Panneau

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

Onduleur

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

Autre

{
  "type": "other",
  "name": "Système de montage",
  "unit": "pcs",
  "net_unit_price": "50.00"
}

Réponse

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

Notes

• Les fabricants sont créés automatiquement s'ils n'existent pas.
• L'unicité des fabricants est limitée à chaque entreprise.
• Tous les champs spécifiques aux panneaux sont validés avant la création.

7. Conventions de données

Identifiants

Tous les identifiants de ressources sont des chaînes UUID, stables et globalement uniques au sein d'une entreprise :

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

Horodatages

Tous les champs datetime sont renvoyés au format ISO 8601, toujours en UTC :

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

Géolocalisation

Les coordonnées s'appliquent aux clients et aux projets. Elles sont stockées sous forme de point géographique et renvoyées sous forme de champs séparés :

"latitude": 52.2297,
"longitude": 21.0122

Gestion des valeurs nulles

Les champs qui ne sont pas définis sont renvoyés comme null — ils ne sont jamais omis de la réponse.

8. Comportement des filtres

Règles générales

• Tous les filtres sont facultatifs sauf indication contraire.
• Plusieurs filtres sont combinés avec une logique ET.
• Les valeurs de filtre multi-sélection (p. ex. category) utilisent une logique OU en interne.
• Les valeurs de filtre invalides renvoient des résultats vides ou une erreur de validation selon le type de champ.

Filtres de plage de dates

Disponibles sur l'ensemble des endpoints :

Filtres de recherche textuelle

Correspondance partielle, insensible à la casse, sur name et phone :

?name=solar

Correspond à : "Solar Corp", "Mon projet photovoltaïque", etc.

9. Modèle d'autorisations

Les autorisations des clés API sont configurées indépendamment pour chaque ressource :

10. Gestion des erreurs

Format des erreurs

Erreur générale :

{
  "detail": "Message d'erreur"
}

Erreur de validation au niveau du champ :

{
  "field_name": ["Message d'erreur"]
}

Référence des erreurs

Liste de vérification d'intégration

Si vous rencontrez des erreurs, vérifiez :

1. La clé API dispose des autorisations correctes pour la ressource.
2. Le compte de l'entreprise est actif.
3. Toutes les valeurs de filtre (ID, etc.) appartiennent au même périmètre d'entreprise.

11. Schémas d'intégration

Stratégie de synchronisation

L'approche recommandée pour synchroniser les données :

1. Récupérez l'endpoint de liste (avec pagination).
2. Stockez id comme référence externe.
3. Utilisez le champ updated pour les synchronisations incrémentales.

Gestion de la pagination

Parcourez les pages en incrémentant le décalage jusqu'à ce que next soit 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

Synchronisation incrémentale

Utilisez des filtres de date pour récupérer uniquement les enregistrements modifiés depuis votre dernière synchronisation :

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

Bonnes pratiques de filtrage

• Privilégiez les filtres basés sur l'ID (client, status) plutôt que les recherches textuelles pour les synchronisations à fort volume.
• Combinez plusieurs filtres pour réduire la taille du jeu de résultats.
• Évitez les recherches textuelles trop larges sur les grands ensembles de données.

12. Stabilité et versionnement

Garanties stables

Les éléments suivants ne changeront pas sans migration versionnée :

• URLs des endpoints
• Noms des champs
• Format UUID
• Structure de pagination
• Schéma d'authentification

Susceptible de changer (sans rupture)

• Filtres facultatifs (de nouveaux filtres peuvent être ajoutés)
• Enrichissement des réponses (de nouveaux champs peuvent être ajoutés)

Politique de versionnement

Aucune version explicite n'est actuellement exposée dans l'URL. Les modifications incompatibles introduiront un nouvel espace de noms d'endpoint :

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

Les changements additifs sont considérés comme sans rupture et peuvent être déployés sans changement de version.

Fin de la documentation