Connecteurs

Les connecteurs transmettent les messages des topics de votre projet vers vos propres systèmes dès leur arrivée, de sorte que vous n'avez jamais à interroger la source ni à vous connecter au broker des appareils. Cette page vous montre comment livrer des données à votre broker MQTT (avec TLS mutuel si nécessaire) ou à votre point de terminaison HTTPS sous forme de webhook.

Fonctionnement des connecteurs

Un connecteur décrit comment Fundamentum atteint l'un de vos systèmes. Un lien rattache un connecteur à un topic du projet et indique la destination de votre côté :

• un lien sortant livre chaque message du topic à votre système ;
• un lien entrant amène des messages de votre système dans le topic (voir Flux entrants).

Un connecteur peut avoir plusieurs liens. La suppression d'un connecteur supprime ses liens ; un connecteur désactivé ne livre rien.

Les connecteurs WebSocket sont à venir.

Le sens du lien doit correspondre au type de topic : les liens sortants acceptent les topics telemetry, states, dimension et fact ; les liens entrants acceptent les topics custom_actions, dimension et fact.

Avant de commencer

• La CLI fun installée et connectée (voir Authentification), ou l'accès à la page Connectors du Hub.
• L'ID de votre projet et l'ID du topic à livrer (fun api v1 pub-sub list-pub-sub-topics --project-id <project-id>).
• Pour MQTT : un broker accessible depuis Internet et prenant en charge MQTT 5. Pour HTTPS : un point de terminaison public https:// qui accepte POST.

1. Créer le connecteur

Les paramètres de connexion se placent dans connection_string, sous forme de paires key=value séparées par ;. Les secrets sont écrits sous forme d'espaces réservés (%password%, %ca_cert%, %client_cert%, %client_key%) et leurs valeurs se placent dans placeholders. Les valeurs des secrets ne sont jamais renvoyées par l'API.

Votre broker MQTT

Écrivez la définition du connecteur dans connector.json :

{
  "name": "plant-broker",
  "adapter_type": 2,
  "is_enabled": true,
  "connection_string": "host=mqtt.example.com;port=8883;clientid=fundamentum-plant;ca_cert=%ca_cert%;client_cert=%client_cert%;client_key=%client_key%",
  "placeholders": {
    "ca_cert": {"value": "-----BEGIN CERTIFICATE-----\n..."},
    "client_cert": {"value": "-----BEGIN CERTIFICATE-----\n..."},
    "client_key": {"value": "-----BEGIN PRIVATE KEY-----\n..."}
  }
}

fun api v1 pub-sub store-connector --project-id <project-id> --body-file connector.json

Lorsque vous mettez à jour un connecteur ultérieurement, définissez "skip_update": true sur un espace réservé pour conserver sa valeur stockée.

Votre point de terminaison HTTPS

fun api v1 pub-sub store-connector --project-id <project-id> --body '{
  "name": "erp-webhook",
  "adapter_type": 3,
  "is_enabled": true,
  "connection_string": "host=https://erp.example.com/fundamentum;headername=X-Api-Key;headervalue=<your-key>"
}'

La réponse contient l'id du connecteur.

2. Vérifier la connexion

fun api v1 pub-sub get-connector-status --project-id <project-id> --connector-id <connector-id>

{"status": "success", "data": {"connected": true}}

3. Lier un topic

fun api v1 pub-sub store-link --project-id <project-id> --connector-id <connector-id> \
  --body '{"pubsub_topic_id": <topic-id>, "external_topic_name": "plant/readings", "ingoing": false}'

Sur un connecteur MQTT, le même topic externe ne peut pas servir à la fois pour un lien entrant et un lien sortant.

4. Recevoir les messages

Sur votre broker, abonnez-vous à external_topic_name. La valeur de chaque message est transmise telle quelle, en QoS 0, et les en-têtes du message deviennent des propriétés utilisateur MQTT 5.

Sur votre point de terminaison HTTPS, Fundamentum envoie une requête par message :

POST https://erp.example.com/fundamentum/plant/readings
Content-Type: application/json
X-Api-Key: <your-key>
Project-Id: <project-id>
Registry-Id: <registry-id>
Serial-Number: <serial-number>
Device-Id: <device-id>
Received-At: 2026-10-22T14:30:00.123456789Z

{"deviceId": "<serial-number>", "data": "<base64-payload>"}

Le corps est le message du topic (ici, la télémétrie d'un appareil, dont l'enveloppe est décrite dans Topics). Les en-têtes du message deviennent des en-têtes HTTP, avec les traits de soulignement remplacés par des tirets.

Répondez avec un statut 2xx dans un délai de 10 secondes. Fundamentum effectue jusqu'à 5 tentatives au total, avec un backoff exponentiel, lorsque votre point de terminaison renvoie 408, 500, 502, 503 ou 504, ou 429 avec un en-tête Retry-After (en secondes), qu'il respecte. Les autres statuts ne donnent lieu à aucune nouvelle tentative.

Gérer les connecteurs et les liens

Étapes suivantes

• Référence de l'API dans Swagger UI : PubSub
• Flux entrants : envoyez des messages de vos systèmes vers la plateforme.
• Fonctions cloud : décodez ou enrichissez les messages avant qu'ils n'atteignent votre connecteur.
• Référence de la Public API : schémas complets des connecteurs et des liens.