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é d'intégrer vos systèmes et d'automatiser vos 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 de filtrage
9. Modèle d'autorisations
10. Gestion des erreurs
11. Schémas d'intégration
12. Stabilité et gestion des versions

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>

Remarques : - 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 ressource spécifiques. - Toutes les requêtes sont automatiquement limitées à l'entreprise associée à la clé API.

Erreurs d'authentification

2. Pagination

Les points de terminaison de liste (Calendrier, Projets, Clients) utilisent la pagination limit/offset.

Paramètres

Enveloppe de réponse

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

Lorsque next est 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 installations. Lecture seule.

Points de terminaison

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 fiches de projet liées au client (p. ex. des installations photovoltaïques). Lecture seule.

Points de terminaison

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": "zloty 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 aucune localisation n'est définie.

Objets imbriqués

Objet 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 les entités clientes. Prend en charge les opérations de lecture et d'écriture.

Points de terminaison

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 un 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 de 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 aucune localisation n'est définie, les deux champs sont renvoyés à null.

Filtres

6. API des composants

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

Point de terminaison

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 photovoltaïque

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

Remarques

• Les fabricants sont créés automatiquement s'ils n'existent pas.
• L'unicité du fabricant est limitée à l'entreprise.
• Tous les champs spécifiques aux panneaux photovoltaïques 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 distincts :

"latitude": 52.2297,
"longitude": 21.0122

Gestion des valeurs nulles

Les champs non renseignés sont renvoyés comme null — ils ne sont jamais omis de la réponse.

8. Comportement de filtrage

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 à sélection multiple (par exemple 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 points de terminaison :

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 de clé 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 contrôle d'intégration

Si vous rencontrez des erreurs, vérifiez :

1. La clé API dispose des autorisations de ressource correctes.
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 le point de terminaison de liste (avec pagination).
2. Stockez l'id comme référence externe.
3. Utilisez le champ updated pour les synchronisations incrémentielles.

Gestion de la pagination

Parcourez les pages en incrémentant l'offset 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émentielle

Utilisez les 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 les 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 gestion des versions

Garanties de stabilité

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

• Les URL des points de terminaison
• Les noms de champs
• Le format UUID
• La structure de pagination
• Le schéma d'authentification

Susceptible de changer (sans rupture de compatibilité)

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

Politique de gestion des versions

Aucune version explicite n'est actuellement exposée dans l'URL. Les changements incompatibles introduiront un nouvel espace de noms de points de terminaison :

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

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

Fin de la documentation