Documentation de l'API externe

Intégrez vos systèmes à l'API EasySolar

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.

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

Statut Raison
401 Clé API manquante ou invalide
401 En-tête d'autorisation mal formé
401 Clé API inactive
403 Autorisation de ressource manquante
402 Entreprise inactive

2. Pagination

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

Paramètres

Paramètre Description Par défaut Max
limit Nombre de résultats à renvoyer 100 500
offset Décalage de pagination 0 —

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

Champ Type Description
id UUID Identifiant de l'événement
category string Catégorie de l'événement (voir les valeurs ci-dessous)
subject string Titre de l'événement
description string Notes supplémentaires sur l'événement
client object | null Client associé
participants array Employés affectés à l'événement
start_at datetime Heure de début de l'événement (UTC)
end_at datetime Heure de fin de l'événement (UTC)
full_day boolean Indique si l'événement dure toute la journée
created_at datetime Horodatage de création de l'événement

Valeurs de catégorie

Valeur Description
meeting Réunion
call Appel téléphonique
installation Rendez-vous d'installation
contract Signature du contrat
quotation Présentation du devis

Objets imbriqués

Objet client :

Champ Type Description
id UUID Identifiant du client
name string Nom du client
address string Adresse du client
phone string Numéro de téléphone du client
is_open boolean Statut actif du client

Objet participant :

Champ Type Description
first_name string Prénom de l'employé
last_name string Nom de famille de l'employé
email string Adresse e-mail de l'employé

Filtres

Paramètre Type Description
start_at_after datetime Filtrer les événements commençant après cette heure
start_at_before datetime Filtrer les événements commençant avant cette heure
end_at_after datetime Filtrer les événements se terminant après cette heure
end_at_before datetime Filtrer les événements se terminant avant cette heure
category string (multi) Filtrer par catégorie ; répétez pour plusieurs valeurs
client UUID Filtrer par ID client

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

Champ Type Description
id UUID Identifiant du projet
name string Nom du projet
address string Adresse du projet
latitude decimal | null Latitude du projet
longitude decimal | null Longitude du projet
client object Client associé (voir l'objet client)
status object Statut du projet
currency object Devise utilisée pour les valeurs financières
total_price decimal string Prix total actuel du projet
payback_period integer | null Période de retour sur investissement estimée en années
created datetime Horodatage de création
updated datetime Horodatage de dernière mise à jour

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 :

Champ Type Description
name string Nom d'affichage du statut
order integer Valeur d'ordre du statut

Objet devise :

Champ Type Description
code string Code devise ISO
name string Nom de la devise

Filtres

Paramètre Type Description
created_after datetime Filtrer par date de création (borne inférieure)
created_before datetime Filtrer par date de création (borne supérieure)
updated_after datetime Filtrer par date de mise à jour (borne inférieure)
updated_before datetime Filtrer par date de mise à jour (borne supérieure)
client UUID Filtrer par ID client
status UUID Filtrer par ID de statut
name string Correspondance partielle insensible à la casse sur le nom

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

Champ Type Description
id UUID Identifiant du client
name string Nom du client
description string Notes supplémentaires
address string Adresse du client
latitude decimal | null Latitude du client
longitude decimal | null Longitude du client
phone string | null Numéro de téléphone du client
is_open boolean Indique si le client est actuellement actif
created datetime Horodatage de création
updated datetime Horodatage de dernière mise à jour

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

Paramètre Type Description
created_after datetime Filtrer par date de création (borne inférieure)
created_before datetime Filtrer par date de création (borne supérieure)
updated_after datetime Filtrer par date de mise à jour (borne inférieure)
updated_before datetime Filtrer par date de mise à jour (borne supérieure)
is_open boolean Filtrer par statut actif (true ou false)
name string Correspondance partielle insensible à la casse sur le nom
phone string Correspondance partielle insensible à la casse sur le numéro de téléphone

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"
}
Champ Type Obligatoire Description
type string Oui Doit être "panel"
manufacturer_name string Oui Nom du fabricant
name string Oui Nom du modèle du panneau photovoltaïque
net_unit_price decimal Non Prix net unitaire
nominal_power decimal Oui Puissance nominale (W). Doit être comprise entre 1.0 et 1000.0
length decimal Oui Longueur du panneau photovoltaïque (m). Doit être comprise entre 0.1 et 5.0
width decimal Oui Largeur du panneau photovoltaïque (m). Doit être comprise entre 0.1 et 5.0
weight decimal | null Non Poids (kg)
efficiency decimal Oui Rendement de conversion. Doit être un ratio compris entre 0 et 1
short_circuit_current decimal Oui Courant de court-circuit (A). Doit être compris entre 0.00001 et 999.99999
open_circuit_voltage decimal Oui Tension à vide (V). Doit être comprise entre 0.00001 et 999.99999
current_temperature_coefficient decimal | null Non Coefficient de température du courant. S'il est fourni, il doit être compris entre −99.999999 et 99.999999
voltage_temperature_coefficient decimal | null Non Coefficient de température de la tension
power_temperature_coefficient decimal | null Non Coefficient de température de la puissance

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
}
Champ Type Obligatoire Description
type string Oui Doit être "inverter"
manufacturer_name string Oui Nom du fabricant
name string Oui Nom du modèle de l'onduleur
net_unit_price decimal Non Prix net unitaire
nominal_power decimal Oui Puissance nominale (W). Doit être comprise entre 100.0 et 100000000.0
number_of_dc_inputs integer Oui Nombre d'entrées DC. Doit être au moins 1

Autre

{
  "type": "other",
  "name": "Système de montage",
  "unit": "pcs",
  "net_unit_price": "50.00"
}
Champ Type Obligatoire Description
type string Oui Doit être "other"
name string Oui Nom du composant
unit string Non Unité de mesure
net_unit_price decimal Non Prix net unitaire

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 :

Champs de filtre Comportement
created_after / created_before Filtre de plage sur l'horodatage de création
updated_after / updated_before Filtre de plage sur l'horodatage de dernière mise à jour
start_at_after / start_at_before Filtre de plage sur l'heure de début de l'événement
end_at_after / end_at_before Filtre de plage sur l'heure de fin de l'événement

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 :

Ressource Autorisation de lecture Autorisation d'écriture
Calendrier calendar_read (non pris en charge)
Projets projects_read (non pris en charge)
Clients clients_read clients_write
Composants (non pris en charge) components_write

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

Statut Catégorie Signification
401 Authentification Clé API invalide, manquante ou inactive ; en-tête mal formé
402 Métier L'entreprise est inactive
403 Autorisation La clé API ne dispose pas de l'autorisation de ressource requise
4xx Validation Les erreurs au niveau des champs sont renvoyées sous forme d'objet

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

Contactez-nous

Besoin d'aide ?

support@easysolar.app

N'hésitez pas à nous contacter et notre équipe dédiée répondra rapidement à vos demandes.

Vendez automatiquement grâce à l'IA

Créez en 2 minutes un commercial IA automatisé

Ajoutez le générateur de devis photovoltaïques IA à votre site web actuel. Définissez vos prix, choisissez vos produits et personnalisez l'identité visuelle de votre entreprise. Vos clients recevront un devis instantané, et vous recevrez une notification e-mail immédiate pour chaque devis et chaque client intéressé.

Détection des bords de toiture pour panneaux photovoltaïques