Aller au contenu principal
Version: v2

Beekube API

API Beekube v2 — Accédez à toutes vos données apicoles : ruchers, ruches, interventions, récoltes, reines, objets connectés. Créez des interventions et des tâches depuis vos outils. Configurez des webhooks pour recevoir des notifications en temps réel dans vos outils d'automatisation (Make, N8N, etc.).

Authentification​

Incluez votre clé API dans l'en-tête X-API-KEY de chaque requête. Générez votre clé dans Configuration > Développeur.

Pagination​

Les endpoints de liste retournent des résultats paginés. Utilisez les paramètres page et limit pour naviguer.

Webhooks​

Souscrivez à des événements pour recevoir des notifications HTTP en temps réel. Les payloads sont signés avec HMAC-SHA256.

API d'écriture​

Un endpoint par type : POST /interventions/{type} (groupe « Interventions (création) ») et POST /tasks/{type} (groupe « Tâches (création) »). Chaque endpoint publie son propre schéma de requête : toute clé inconnue est refusée et aucune valeur n'est convertie ("3" n'est pas un entier).

Scopes et auteur​

  • write:interventions pour créer des interventions, write:tasks pour créer des tâches. Cochez-les dans Configuration > Développeur.
  • Une clé sans scopes explicites reste en lecture seule : un scope write:* doit toujours être coché.
  • Les saisies sont faites au nom de l'« Auteur des saisies » choisi pour la clé (un membre non lecteur de l'exploitation), sinon au nom du propriétaire de l'exploitation.
  • Scope manquant, auteur lecteur ou retiré, aucun auteur possible : 403.

Enveloppe commune​

{
  "target":   { "beehiveId": 12 },
  "date":     "2026-10-04T10:15:00+02:00",
  "comments": "RAS",
  "taskId":   87,
  "stepId":   null,
  "data":     {}
}
  • target : exactement une forme parmi {"beehiveId": 12} (une ruche), {"beehiveIds": [12, 13]} (1 à 100 ruches, une saisie par ruche), {"apiaryId": 3} (toutes les ruches actives du rucher), {"queenId": 5} (une reine) et {} (l'exploitation, pour queen-reserve-add seulement). Les formes acceptées sont indiquées par chaque endpoint ; une autre forme donne target_not_allowed.
  • date : RFC 3339 avec fuseau horaire. Intervention : facultative (défaut : maintenant), au plus maintenant + 5 minutes. Tâche : obligatoire (date planifiée), du 2000-01-01 à maintenant + 5 ans. Une saisie a posteriori est permise.
  • comments : 1 à 10 000 caractères. Omettez le champ plutôt que d'envoyer une chaîne vide.
  • taskId (interventions) : tâche non validée, du même type, sur une des ruches ciblées. Elle est validée par la création.
  • stepId (élevage de reines) : étape de la série. Sans stepId, l'étape en cours est cherchée sur la ruche ciblée.
  • data : champs propres au type, décrits par le schéma de l'endpoint. {} ou absent pour un type sans données.

Réponses​

  • Interventions : 200 avec {"data": [...], "count": n}, une intervention par ruche ciblée, au format de GET /interventions/{id}. Les interventions créées en cascade (déplacement de ruche d'une division, etc.) restent consultables par GET /interventions.
  • Tâches : 200 avec {"taskGroupId": 451, "data": [...], "count": n}.
  • Les automatismes, webhooks (intervention.created, task.created) et mises à jour de la ruche ou de la reine sont ceux de la saisie dans l'application. Un automatisme en erreur ne fait pas échouer la création.

Idempotence : Idempotency-Key​

En-tête facultatif, un UUID v4 par saisie (Idempotency-Key: 3f6c2b1e-8a4d-4c3e-9b7a-1d2e3f4a5b6c). Rejouer la même requête avec la même clé renvoie la même réponse 200 sans rien créer de nouveau : un client peut réessayer sans risque après une coupure réseau. La même clé avec un corps différent donne 400 idempotency_key_reused. Une valeur qui n'est pas un UUID v4 donne type_mismatch sur le chemin Idempotency-Key.

Erreurs de validation (400)​

Toutes les erreurs détectables avant l'écriture sont renvoyées en une fois, sans rien enregistrer :

{
  "error": {
    "code": 400,
    "message": "Requête invalide",
    "details": {
      "violations": [
        { "path": "data.quantity.unit", "code": "invalid_choice", "message": "Valeurs autorisées : gram, kilogram, millilitre" },
        { "path": "target.beehiveIds[3]", "code": "not_found", "message": "Ruche inconnue" }
      ]
    }
  }
}

path suit la notation du corps (data.supers[2].frames). Codes : required, unknown_field, type_mismatch, invalid_choice, out_of_range, too_short, too_long, count, duplicate, invalid_date, date_in_future, exclusive, not_found, target_not_allowed, apiary_empty, precondition_failed, idempotency_key_reused. Un identifiant inconnu et un identifiant d'une autre exploitation donnent la même erreur not_found. precondition_failed signale un geste impossible dans l'état actuel (reine absente, ruche déjà pourvue, étape introuvable…) : la saisie n'est pas enregistrée.

Référentiels​

Les identifiants à fournir se lisent dans le groupe « Référentiel » : GET /feed-types, /feed-presets, /treatments, /treatment-presets, /materials, /maladies, /bees, /beehive-types, /contacts, /evaluation-criteria, /supers, /breeding-configs et /queen-breeding-steps (paramètres beehive_id et type facultatifs). Les unités (gram, kilogram, millilitre…) sont des valeurs fixes, listées dans chaque schéma.

Exemples​

Tâche de nourrissement sur tout un rucher (une tâche par ruche) :

POST /api/v2/tasks/feed
X-API-KEY: votre-clé
Content-Type: application/json

{
  "target": { "apiaryId": 3 },
  "date": "2026-10-15T09:00:00+02:00",
  "comments": "Avant l'hivernage",
  "data": { "feedTypeId": 2, "quantity": { "value": 1.5, "unit": "kilogram" } }
}

Intervention simple, une visite sur deux ruches :

POST /api/v2/interventions/check
X-API-KEY: votre-clé
Idempotency-Key: 3f6c2b1e-8a4d-4c3e-9b7a-1d2e3f4a5b6c
Content-Type: application/json

{
  "target": { "beehiveIds": [12, 13] },
  "data": { "seeQueen": true, "seeBrood": true, "broodFrames": 6, "powerPercent": 80, "behaviour": "calm" }
}

Division vers une ruche existante et une ruche à créer :

POST /api/v2/interventions/splitting
X-API-KEY: votre-clé
Content-Type: application/json

{
  "target": { "beehiveId": 12 },
  "date": "2026-05-02T11:00:00+02:00",
  "data": {
    "daughters": [
      { "beehiveId": 21 },
      { "create": { "beehiveTypeId": 1, "reference": "R-2026-07" } }
    ]
  }
}

Étape d'élevage, le greffage d'une série en cours (stepId lu dans GET /queen-breeding-steps?type=queen-breeding-gref) :

POST /api/v2/interventions/queen-breeding-gref
X-API-KEY: votre-clé
Content-Type: application/json

{
  "target": { "beehiveId": 30 },
  "stepId": 418,
  "data": { "actualQuantity": 32 }
}

Document OpenAPI​

https://www.beekube.com/docs/v2_openapi.yaml

Contact

Support Beekube: [email protected]