{"id":31646413,"url":"https://github.com/hello-sycon/sycon-api","last_synced_at":"2025-10-07T05:49:39.900Z","repository":{"id":316243626,"uuid":"1062443215","full_name":"Hello-sycon/sycon-api","owner":"Hello-sycon","description":"Production API documentation for Sycon Cloud (OpenAPI + usage guide)","archived":false,"fork":false,"pushed_at":"2025-10-03T15:43:05.000Z","size":2588,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-03T17:50:21.994Z","etag":null,"topics":["api-docs","industrial-iot","openapi","redoc","swagger-ui","sycon"],"latest_commit_sha":null,"homepage":"https://www.sycon.fr/","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Hello-sycon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-23T09:06:01.000Z","updated_at":"2025-10-01T09:22:18.000Z","dependencies_parsed_at":"2025-10-03T17:50:23.808Z","dependency_job_id":null,"html_url":"https://github.com/Hello-sycon/sycon-api","commit_stats":null,"previous_names":["hello-sycon/sycon-api-production","hello-sycon/sycon-api"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/Hello-sycon/sycon-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hello-sycon%2Fsycon-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hello-sycon%2Fsycon-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hello-sycon%2Fsycon-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hello-sycon%2Fsycon-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Hello-sycon","download_url":"https://codeload.github.com/Hello-sycon/sycon-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hello-sycon%2Fsycon-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278727839,"owners_count":26035410,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-07T02:00:06.786Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-docs","industrial-iot","openapi","redoc","swagger-ui","sycon"],"created_at":"2025-10-07T05:49:38.584Z","updated_at":"2025-10-07T05:49:39.896Z","avatar_url":"https://github.com/Hello-sycon.png","language":null,"readme":"# Guide d’utilisation — Sycon Cloud API\n\u003ca href=\"https://www.sycon.fr\"\u003e\n  \u003cimg src=\"docs/assets/logo.webp\" alt=\"Sycon\" align=\"right\" width=\"240\"\u003e\n\u003c/a\u003e\n\n[![Sycon](https://img.shields.io/badge/Sycon-1.2.0-0bf57a.svg)](#)\n[![OpenAPI](https://img.shields.io/badge/OpenAPI-3.1-blue.svg)](#)\n[![Docs](https://img.shields.io/badge/SwaggerUI-success.svg)](#)\n[![License](https://img.shields.io/badge/License-MIT-lightgrey.svg)](#)\n\nCe guide explique comment **s’authentifier**, **explorer la documentation Swagger**, **lister vos équipements** et **récupérer des données brutes**.\n\n**Swagger** : \u003chttps://hello-sycon.github.io/sycon-api/\u003e  \n**URL API** : \u003chttps://cloud.sycon.io\u003e  \n**Spécification API 1.2.0** : `docs/v1.2.0/sycon-cloud-api`.    \n\n---\n\n## 1) Prérequis\n- Un compte client Sycon actif (identifiants fournis par Sycon).\n- Accès HTTPS sortant (443).\n- Navigateur moderne pour Swagger UI (ou votre outil habituel : Postman, Insomnia, etc.).\n\n---\n\n## 2) Authentification (JWT + Renew)\n\nL’API utilise un **jeton JWT** transmis dans l’en-tête `Authorization` et un jeton **Renew** pour renouveler le JWT sans ressaisir vos identifiants.\n\n**Étapes :**\n1. **Login** (`POST /auth/login`) avec vos identifiants.  \n   • En cas de succès (`200`), la réponse ne contient **pas** de corps JSON, mais **deux en‑têtes** :  \n   `Authorization: Bearer \u003cJWT\u003e` et `Renew: \u003cRENEW_TOKEN\u003e`.\n2. **Appeler l’API** en ajoutant `Authorization: Bearer \u003cJWT\u003e` à chaque requête.\n3. **Vérifier** votre JWT à tout moment via `GET /auth/check` (retour `200` si valide, `403` sinon).\n4. **Renouveler** le JWT via `GET /auth/renew` en envoyant l’en‑tête `Renew: \u003cRENEW_TOKEN\u003e` ; un **nouveau** `Authorization` est renvoyé.\n\n**Bonnes pratiques :**\n- Conservez `Renew` de manière sécurisée et **renouvelez avant** l’expiration du JWT.\n- Ne partagez jamais vos jetons ni ne les commitez dans un dépôt.\n\n---\n\n## 3) Utiliser Swagger UI (pas à pas)\n\n1. Ouvrez : \u003chttps://hello-sycon.github.io/sycon-api-production/\u003e.\n2. Cliquez **Authorize** et collez votre valeur `Bearer \u003cJWT\u003e` dans le champ prévu.\n3. Utilisez la **recherche** pour trouver un endpoint par nom ou par tag (« API auth », « Data API »).\n4. Dépliez un endpoint, cliquez **Try it out**, renseignez les paramètres, puis **Execute**.\n5. Consultez le **Request URL**, les **en‑têtes**, et la **réponse** (corps + codes).\n\n\u003e Astuce : Servez‑vous d’un device/field réel récupéré via `/api/devices` pour vos essais.\n\n---\n\n## 4) Parcours type\n\n### A) Lister vos appareils\n- Endpoint : `GET /api/devices`\n- Résultat : liste des devices rattachés à votre client.  \n  Les champs `fields` et `externalSensorIds` reflètent ce qui a été mesuré **sur les 7 derniers jours** (leur absence n’exclut pas des historiques plus anciens).\n\n### B) Récupérer des données brutes capteur\n- Endpoint : `GET /api/devices/{deviceId}/{field}/data/raw`\n- Paramètres **path** :\n  - `deviceId` *(int64, requis)* — identifiant du device.\n  - `field` *(enum, requis)* — type de mesure (voir la liste complète dans l’OpenAPI / Swagger).\n- Paramètres **query** :\n\n  | Nom               | Type     | Obligatoire | Règles / Exemple                                  |\n  |-------------------|----------|-------------|----------------------------------------------------|\n  | `start`           | string   | oui         | Instant **UTC** ISO‑8601, ex. `2025-09-22T00:00:00Z` |\n  | `end`             | string   | oui         | Instant **UTC** ISO‑8601                            |\n  | `headLimit`       | int ≤10000 | au moins 1/2 | Garde les **N premiers** points depuis `start`       |\n  | `tailLimit`       | int ≤10000 | au moins 1/2 | Garde les **N derniers** points jusqu’à `end`        |\n  | `externalSensorId`| string   | non         | Filtre sur un capteur **externe** précis            |\n\n  \u003e **Règle** : fournir **au moins** `headLimit` **ou** `tailLimit`. Si la fenêtre contient plus de N points, l’API tronque selon l’option choisie.\n\n- Réponse (résumé) :  \n  • métadonnées : `deviceId`, `field`, `externalSensorId` (optionnel), `firstTimestamp`, `lastTimestamp`, `count`  \n  • données : `dataPoints[]` (chaque point contient `time` (ISO‑8601) et `value` ou `textValue`)\n\n### C) Paginer par fenêtres (recommandé)\n- Enchaînez plusieurs appels en découpant votre période (ex. tranches d’1 h).  \n- Utilisez `firstTimestamp` / `lastTimestamp` pour avancer sans chevauchement.\n\n---\n\n## 5) Codes d’erreur \u0026 Dépannage\n\n**Codes fréquents :**\n- `401` — JWT manquant/invalide.\n- `403` — Accès refusé (droits/périmètre) ou `Renew` invalide/expiré.\n- `404` — Device introuvable.\n- `400` — Paramètres invalides (dates, limites manquantes, formats).\n- `502` — Erreur lors de l’interrogation des données en backend.\n\n**Checklist rapide :**\n1. L’en‑tête `Authorization` commence par **`Bearer `** et le JWT est **valide** (`/auth/check`).\n2. `start \u003c end` et vos dates sont au format **ISO‑8601 UTC** (suffixe `Z`).\n3. Vous fournissez **`headLimit` ou `tailLimit`** (≤ 10000).\n4. Le `deviceId` vous appartient (visible dans `/api/devices`).\n5. Le `field` existe pour votre device (il peut ne pas apparaître si aucune mesure récente, mais rester interrogeable si de l’historique existe).\n\n---\n\n## 6) Bonnes pratiques d’intégration\n\n- **UTC partout** : sérialisez vos timestamps avec le suffixe `Z`.\n- **Fenêtrage** : préférez des fenêtres limitées (ex. 1 h) plutôt qu’un très large intervalle.\n- **Renouvellement proactif** : anticipez l’expiration de votre JWT avec `/auth/renew`.\n- **Résilience** : en cas de `502`, appliquez un backoff exponentiel.\n- **Sécurité** : ne divulguez jamais `Authorization`/`Renew` (pas de commit, pas de tickets publics).\n\n---\n\n## 7) Support\n\n- Site : \u003chttps://www.sycon.fr/\u003e\n- Contact : \u003chello@sycon.fr\u003e\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhello-sycon%2Fsycon-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhello-sycon%2Fsycon-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhello-sycon%2Fsycon-api/lists"}