openapi: 3.0.0
info:
  title: 'Beekube Device'
  description: "Bienvenue dans la section développeur de Beekube. L'API ouvre un monde de possibilités pour les apiculteurs passionnés et les amateurs de bricolage (DIY) qui souhaitent intégrer leurs propres solutions connectées à l'écosystème Beekube.\nQu'est-ce que l'API Beekube ?\n\nL'API Beekube est une interface de programmation qui permet une communication fluide entre vos objets connectés DIY pour ruches, comme les balances de ruche connectées ou les stations météo, et la plateforme Beekube. Grâce à cette API, vous pouvez envoyer automatiquement les données collectées par vos dispositifs directement dans votre compte Beekube, vous permettant ainsi de surveiller et d'analyser ces informations en temps réel.\nPourquoi utiliser l'API Beekube ?\n\n- **Intégration facile** : L'API est conçue pour être simple et intuitive, permettant une intégration rapide de vos dispositifs avec Beekube.\n- **Suivi en temps réel** : Obtenez des mises à jour immédiates de l'état de vos ruches directement sur votre tableau de bord Beekube.\n- **Personnalisation** : Adaptez la gestion de vos ruches en fonction des données spécifiques recueillies par vos dispositifs connectés.\nSupport et documentation complète : Nous vous fournissons toutes les informations nécessaires et l'assistance pour faciliter l'utilisation de notre API.\n\n## Comment démarrer ?\n\nPour commencer, rendez-vous dans la section `Configuration > Développeur` de votre compte Beekube. Vous pourrez alors générer votre clé API personnelle. Cette page vous donne également accès aux logs de vos appels API pour vérifier le bon fonctionnement de vos appareils. \n\nVous devez créer vos objets connectés en amont dans `Objets connectés`, avec le bouton `Ajouter un objet connecté`. \n\n## Document OpenAPI\nVoici le lien de la documentation OpenAPI : https://www.beekube.com/docs/user_openapi.yaml\n"
  contact:
    name: 'Support Beekube'
    email: support@beekube.com
  version: v1
servers:
  -
    url: 'https://www.beekube.com/api/v1'
paths:
  /device/all:
    get:
      tags:
        - devices
      summary: 'Liste des objets connectés'
      operationId: 76be054dc1253ec8d7dc10abe3bd41c3
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Device'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRespond'
              example:
                error:
                  code: 401
                  message: Unauthorized
                  details: []
  '/device/{id}':
    get:
      tags:
        - devices
      summary: "Informations d'un objet connecté"
      operationId: 802c943ae51d13a8c0a18d75fb61eb74
      parameters:
        -
          name: id
          in: path
          description: "Identifiant de l'objet"
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Device'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRespond'
              example:
                error:
                  code: 401
                  message: Unauthorized
                  details: []
        '404':
          description: 'Device inconnu'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRespond'
              example:
                error:
                  code: 404
                  message: 'Not Found: Device inconnu'
                  details: []
  '/device/{id}/update':
    post:
      tags:
        - devices
      summary: "Mettre à jour les informations d'un objet connecté"
      operationId: 968d20ee45c37883c2883009e47fff2c
      parameters:
        -
          name: id
          in: path
          description: "Identifiant de l'objet"
          required: true
          schema:
            type: integer
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceUpdate'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Device'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRespond'
              example:
                error:
                  code: 401
                  message: Unauthorized
                  details: []
        '404':
          description: 'Device inconnu'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRespond'
              example:
                error:
                  code: 404
                  message: 'Not Found: Device inconnu'
                  details: []
  '/device/{id}/datum':
    post:
      tags:
        - device-data
      summary: 'Envoyer une donnée de mesure'
      operationId: c335b12eae24626aedbb12f4a8387116
      parameters:
        -
          name: id
          in: path
          description: "Identifiant de l'objet"
          required: true
          schema:
            type: integer
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceData'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRespond'
              example:
                error:
                  code: 401
                  message: Unauthorized
                  details: []
        '404':
          description: 'Device inconnu'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRespond'
              example:
                error:
                  code: 404
                  message: 'Not Found: Device inconnu'
                  details: []
  '/device/{id}/data':
    get:
      tags:
        - device-data
      summary: 'Récupérer les données de mesure'
      operationId: 56ff5f4d2c80f904e4c9e6ea576e605d
      parameters:
        -
          name: id
          in: path
          description: "Identifiant de l'objet"
          required: true
          schema:
            type: integer
        -
          name: date
          in: query
          description: 'Date de début'
          required: true
          schema:
            type: string
          example: '2023-10-21 10:05:04'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataRespond'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRespond'
              example:
                error:
                  code: 401
                  message: Unauthorized
                  details: []
        '404':
          description: 'Device inconnu'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRespond'
              example:
                error:
                  code: 404
                  message: 'Not Found: Device inconnu'
                  details: []
    post:
      tags:
        - device-data
      summary: 'Envoyer plusieurs données de mesure'
      operationId: 27ccb49b1d6b19eaf20b867992e4718f
      parameters:
        -
          name: id
          in: path
          description: "Identifiant de l'objet"
          required: true
          schema:
            type: integer
      requestBody:
        description: 'Tableau de mesure'
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/DeviceData'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRespond'
              example:
                error:
                  code: 401
                  message: Unauthorized
                  details: []
        '404':
          description: 'Device inconnu'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRespond'
              example:
                error:
                  code: 404
                  message: 'Not Found: Device inconnu'
                  details: []
components:
  schemas:
    Device:
      properties:
        id:
          description: ID
          type: integer
          example: 23
        typeConnection:
          description: 'Type de connexion : Sigfox = 0, Lora = 2, Satellite = 3'
          example: 0
          nullable: true
        refExtern:
          description: 'Référence externe'
          type: string
          example: B0023
          nullable: true
        name:
          description: 'Nom de la balance'
          type: string
          example: 'Balance DIY n°2'
          nullable: true
        last_sync:
          description: 'Date de dernière synchronisation'
          type: string
          format: date-time
          nullable: true
        state:
          description: Statut
          type: integer
          nullable: true
        lat:
          description: Latitude
          type: number
          format: float
          example: 48.4014
          nullable: true
        lng:
          description: Longitude
          type: number
          format: float
          example: 4.417
          nullable: true
      type: object
    DeviceData:
      properties:
        date:
          description: 'Date de la mesure : 2023-12-21 10:11:01'
          type: string
          pattern: '[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}(?::[0-9]{2})?'
          example: '2023-10-21 10:05:04'
          nullable: true
        value:
          description: 'Valeur de la mesure'
          type: number
          format: float
          example: 32.57
        unit:
          description: 'Unité de la mesure'
          type: string
          enum:
            - degres
            - gram
            - kilogram
            - pourcentage
            - volt
          example: kilogram
        type:
          description: 'Type de mesure'
          type: string
          enum:
            - temp_ext
            - temp_int
            - hygro_ext
            - hygro_int
            - weight
            - device_signal
            - device_battery
          example: weight
      type: object
    DeviceUpdate:
      properties:
        typeConnection:
          description: 'Type de connexion'
          type: integer
          nullable: true
        statusConnection:
          description: 'Statut de connexion'
          type: integer
          nullable: true
        refExtern:
          description: 'Référence externe'
          type: string
          nullable: true
        state:
          description: Statut
          type: integer
          nullable: true
        lat:
          description: Latitude
          type: number
          format: float
          nullable: true
        lng:
          description: Longitude
          type: number
          format: float
          nullable: true
      type: object
    DataRespond:
      properties:
        data:
          description: Donnée
          type: array
          items:
            $ref: '#/components/schemas/DeviceDataItemRespond'
        pagination:
          $ref: '#/components/schemas/PaginationRespond'
      type: object
      example:
        data:
          -
            date: '2023-10-09T11:40:00+02:00'
            value: 11
            unit: degres
            type: temp_ext
          -
            date: '2023-10-09T11:40:00+02:00'
            value: 31.7
            unit: kilogram
            type: weight
          -
            date: '2023-10-10T11:40:00+02:00'
            value: 9
            unit: degres
            type: temp_ext
          -
            date: '2023-10-10T11:40:00+02:00'
            value: 32.7
            unit: kilogram
            type: weight
          -
            date: '2023-10-11T11:40:00+02:00'
            value: 11
            unit: degres
            type: temp_ext
          -
            date: '2023-10-11T11:40:00+02:00'
            value: 34.7
            unit: kilogram
            type: weight
          -
            date: '2023-11-09T11:40:00+01:00'
            value: 11
            unit: degres
            type: temp_ext
          -
            date: '2023-11-09T11:40:00+01:00'
            value: 31.7
            unit: kilogram
            type: weight
          -
            date: '2023-11-10T11:40:00+01:00'
            value: 9
            unit: degres
            type: temp_ext
          -
            date: '2023-11-10T11:40:00+01:00'
            value: 32.7
            unit: kilogram
            type: weight
        pagination:
          currentPage: 1
          maxPage: 2
          itemPerPage: 10
          nextPage: 2
          nextPageUrl: 'https://www.beekube.com/api/v1//device/23/data?date=2023-09-01&page=2'
          previousPage: null
          previousPageUrl: null
    DeviceDataItemRespond:
      properties:
        date:
          description: 'Date de la mesure : 2023-12-21 10:11:01'
          type: string
          pattern: '[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}(?::[0-9]{2})?'
          example: '2023-10-21 10:05:04'
          nullable: true
        value:
          description: 'Valeur de la mesure'
          type: number
          format: float
          example: 32.57
        unit:
          description: 'Unité de la mesure'
          type: string
          enum:
            - degres
            - gram
            - kilogram
            - pourcentage
            - volt
          example: kilogram
        type:
          description: 'Type de mesure'
          type: string
          enum:
            - temp_ext
            - temp_int
            - hygro_ext
            - hygro_int
            - weight
            - device_signal
            - device_battery
          example: weight
      type: object
    ErrorRespond:
      properties:
        code:
          description: "Code d'erreur"
          type: integer
        message:
          description: "Message de l'erreur"
          type: string
        details:
          description: 'Informations supplémentaires'
          type: array
          items:
            type: integer
      type: object
    PaginationRespond:
      properties:
        currentPage:
          description: 'Page actuelle'
          type: integer
          example: 1
        maxPage:
          description: 'Nombre de page maximum'
          type: integer
          example: 2
        itemPerPage:
          description: "Nombre maximum d'item par page"
          type: integer
          example: 100
        nextPage:
          description: 'Numéro de la page suivante'
          type: integer
          example: 2
          nullable: true
        nextPageUrl:
          description: 'URL de la page suivante'
          type: string
          nullable: true
        previousPage:
          description: 'Numéro de la page précédente'
          type: integer
          nullable: true
        previousPageUrl:
          description: 'URL de la page précédente'
          type: string
          nullable: true
      type: object
    Success:
      properties:
        success:
          description: 'Succès de la requète'
          type: boolean
        message:
          description: 'Message du succès'
          type: string
      type: object
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      description: "## Authentification de l'API Beekube\n\nL'authentification à l'API Beekube est assurée par l'utilisation d'une clé API. Cette clé est un token unique qui permet d'identifier et de sécuriser vos interactions avec l'API. Voici comment procéder pour l'utiliser :\n\n### Obtention de votre Clé API\n\n1. **Accès à la clé :** Connectez-vous à votre compte Beekube et naviguez vers la section `Configuration > Développeur`. \n2. **Génération de la clé :** Dans cette section, vous trouverez l'option pour générer votre clé API personnelle. Une fois générée, vous pouvez la copier pour l'utiliser dans vos requêtes API.\n\n### Utilisation de la Clé API\n\n- **Intégration dans les Requêtes :** Pour chaque requête envoyée à l'API Beekube, vous devez inclure votre clé API. Elle doit être insérée dans l'en-tête HTTP de la requête sous la clé `X-API-KEY`.\n- **Format de l'En-tête :** L'en-tête doit être structuré de la manière suivante : `X-API-KEY: VotreCléAPI`.\n\n### Sécurité\n\n- **Confidentialité :** Votre clé API est unique et doit rester confidentielle. Ne la partagez avec personne pour assurer la sécurité de vos données.\n- **Révocation et Régénération :** En cas de compromission ou pour des raisons de sécurité, vous pouvez à tout moment révoquer et régénérer une nouvelle clé API depuis votre compte Beekube.\n\nEn suivant ces étapes simples, vous assurez une connexion sécurisée et authentifiée avec l'API Beekube, permettant une interaction fluide et sûre avec vos dispositifs connectés pour ruches.\n"
      name: X-API-KEY
      in: header
security:
  -
    ApiKeyAuth: []
tags:
  -
    name: devices
    description: 'Vous pouvez récupérer la liste objets connecté DIY, mettre à jour les informations'
    x-displayName: 'Objets connectés'
  -
    name: device-data
    description: 'Envoyer des données (poids, température, etc.), et récupérer les données'
    x-displayName: 'Données de mesure'
x-tagGroups:
  -
    name: device
    tags:
      - device
      - device-data
