Développeurs

Dernière mise à jour : 2 octobre 2026

Il y a trois façons de travailler avec le Layer depuis l’extérieur :

• Connecter une app d’IA via MCP, comme Claude ou ChatGPT. Vous vous connectez au Layer et choisissez ce que l’app peut faire.
• L’API REST pour vos propres logiciels, avec une clé que vous créez vous-même.
• Webhooks : le Layer signale à votre adresse qu’il s’est passé quelque chose, comme une facture payée.

1. Comment cela reste sûr

• Jamais plus que le créateur. Une clé ou une app connectée ne peut jamais faire plus que la personne qui l’a créée. Si son rôle change, la clé change aussi. Si quelqu’un quitte l’équipe, sa clé ne fonctionne plus.
• Écrire est toujours une proposition. Rien de l’extérieur ne modifie quoi que ce soit de lui-même dans votre espace de travail. Chaque modification arrive dans Approbations et n’a lieu que lorsqu’une personne disposant de ce droit l’approuve.
• Le texte externe reste marqué. Ce qui arrive via l’API ou MCP compte comme texte externe. Une proposition contenant un tel texte ne s’exécute jamais automatiquement, même si vous laissez d’autres propositions s’exécuter automatiquement.
• Visible et révocable. Dans Paramètres, Appareils, vous voyez chaque clé et app, quand elle a été utilisée pour la dernière fois et ce qu’elle a fait. La révocation est immédiate.
• Un frein. Chaque clé et app peut faire 120 requêtes par minute. Au-delà, vous recevez un 429 avec un Retry-After.

2. Créer une clé

Dans le Layer : Paramètres, Développeurs, Clé pour l’API. Donnez un nom à la clé, choisissez sa durée de validité (30 jours, 90 jours ou un an) et cochez ce qu’elle peut faire. Vous ne voyez la clé qu’une fois. Nous ne conservons qu’un hash, donc une clé perdue est perdue : révoquez-la et créez-en une nouvelle.

Les clés appartiennent à votre propre espace de travail, pas à la démo. L’adresse exacte de votre API et de votre serveur MCP figure sur la même page ; dans les exemples ci-dessous, elle apparaît comme https://jouw-werkplek.example.

Un droit ne fonctionne que si le module fait partie de votre abonnement et que votre rôle l’autorise. Les montants, comme un taux horaire, ne sont visibles que si votre rôle peut voir les données financières.

3. L’API REST

Tout se trouve sous /api/v1. Envoyez la clé comme Authorization : Bearer. GET /api/v1 montre quelles ressources votre clé peut lire. La description complète se trouve dans /api/v1/openapi.json (OpenAPI 3.1), consultable aussi sans clé.

Lire et paginer

curl "https://jouw-werkplek.example/api/v1/taken?status=open&per_pagina=20" \
  -H "Authorization: Bearer $LAYER_SLEUTEL"

Chaque liste arrive en pages, les plus récents d’abord. Avec per_pagina (1 à 100, 50 par défaut) et pagina, vous parcourez les pages ; volgende donne l’adresse de la page suivante, ou null. Filtrez avec status, ou avec sinds (une date ou une heure en ISO 8601) pour ne récupérer que ce qui a changé depuis.

{
  "data": [ { "id": "...", "titel": "...", "status": "open", "deadline": "2026-10-03T07:00:00.000Z" } ],
  "pagina": 1,
  "per_pagina": 20,
  "totaal": 1,
  "volgende": null
}

Proposer une modification

Avec le droit voorstellen.maken, vous proposez un nouvel enregistrement ou une modification. La réponse est un 202 : la proposition est prête, rien n’a encore changé. Indiquez dans waarom la raison, et l’évaluateur la verra à côté.

curl -X POST "https://jouw-werkplek.example/api/v1/taken" \
  -H "Authorization: Bearer $LAYER_SLEUTEL" \
  -H "Content-Type: application/json" \
  -d '{"titel": "Relancer le devis", "deadline": "2026-10-03", "waarom": "Convenu en réunion"}'

HTTP/1.1 202 Accepted

{
  "voorstel": { "id": "...", "actie": "taak.nieuw", "titel": "...", "status": "wacht", "link": "https://jouw-werkplek.example/app/ai/goedkeuringen?id=..." },
  "uitleg": "Dit is een voorstel. Er is nog niets veranderd: het wacht in Goedkeuringen tot iemand het goedkeurt."
}

Suivez l’état avec GET /api/v1/voorstellen ou GET /api/v1/voorstellen/{id} ; vous ne voyez que les propositions de votre propre clé. Vous préférez un webhook ? Abonnez-vous alors à voorstel.goedgekeurd. Les autres actions que l’IA connaît dans le Layer, vous les proposez avec POST /api/v1/voorstellen et {"actie": "...", "gegevens": { ... }}. Si une action n’est pas possible, ou s’il manque quelque chose, vous recevez un 422 avec la raison. La suppression n’est pas possible via l’API.

Erreurs

Une erreur est toujours en JSON : {"fout": {"code": "...", "melding": "..."}}, avec un message en langage clair.

4. Webhooks

Les personnes qui gèrent les connexions dans le Layer configurent les webhooks dans Paramètres, Développeurs, Webhooks : une adresse et les événements que vous voulez recevoir. Le secret pour vérifier la signature n’est visible qu’une fois.

Un message est volontairement léger : ce qui s’est passé et où le lire, sans montants ni données client. Vous récupérez le contenu avec une clé, via href. L’id reste identique si nous renvoyons un message, ce qui vous permet de reconnaître un doublon.

POST /jouw-webhook HTTP/1.1
Content-Type: application/json
TrompTech-Event: factuur.betaald
TrompTech-Delivery: ...
TrompTech-Signature: t=1790931600,v1=...

{
  "id": "evt_...",
  "type": "factuur.betaald",
  "aangemaakt": "2026-10-02T09:00:00.000Z",
  "data": { "object": "factuur", "id": "...", "nummer": "...", "href": "/api/v1/facturen/..." }
}

Vérifier la signature

L’en-tête TrompTech-Signature contient une heure t (en secondes) et v1 : un HMAC-SHA256 avec votre secret sur t, un point et le body tel qu’il est arrivé. Recalculez-le vous-même, comparez en temps constant et refusez les messages de plus de cinq minutes.

import { createHmac, timingSafeEqual } from "node:crypto";

// geheim : le secret complet du webhook, avec le préfixe whsec_.
// inhoud : le corps de la requête tel qu’il est arrivé, en texte (ne pas le lire d’abord en JSON).
export function handtekeningKlopt(geheim, kop, inhoud) {
  const delen = new Map((kop ?? "").split(",").map(d => d.trim().split("=", 2)));
  const t = Number(delen.get("t")), v1 = delen.get("v1") ?? "";
  // Plus de cinq minutes : refuser, pour que personne ne puisse rejouer un ancien message.
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > 300 || !/^[0-9a-f]{64}$/.test(v1)) return false;
  const verwacht = createHmac("sha256", geheim).update(`${t}.${inhoud}`).digest();
  return timingSafeEqual(verwacht, Buffer.from(v1, "hex"));
}

import hashlib, hmac, re, time

def handtekening_klopt(geheim: str, kop: str, inhoud: bytes) -> bool:
    delen = dict(d.strip().split("=", 1) for d in (kop or "").split(",") if "=" in d)
    t, v1 = delen.get("t", ""), delen.get("v1", "")
    if not t.isdigit() or abs(time.time() - int(t)) > 300 or not re.fullmatch(r"[0-9a-f]{64}", v1):
        return False
    verwacht = hmac.new(geheim.encode(), t.encode() + b"." + inhoud, hashlib.sha256).hexdigest()
    return hmac.compare_digest(verwacht, v1)

Livraison et nouvelles tentatives

• Répondez dans les 10 secondes avec un 2xx. Nous ne suivons pas les redirections (3xx).
• En cas d’échec, nous réessayons après 1 minute, 5 minutes, 30 minutes, 2 heures, 6 heures et 24 heures. Ensuite, le message est considéré comme échoué ; vous pouvez le renvoyer dans le Layer.
• Si dix messages échouent d’affilée, le webhook est désactivé. Vous le réactivez vous-même.
• Uniquement https vers une adresse publique avec nom de domaine, sur le port standard. Une adresse qui pointe vers un réseau interne ne reçoit rien ; nous le vérifions à nouveau à chaque livraison.

5. Connecter une app d’IA via MCP

Le Layer est un serveur MCP à l’adresse https://jouw-werkplek.example/api/mcp (Streamable HTTP). La connexion se fait avec OAuth 2.1 et PKCE : l’app vous envoie vers le Layer, vous vous connectez comme d’habitude (avec votre second facteur si vous en avez un) et choisissez sur l’écran d’autorisation ce que l’app peut faire.

• Claude : ouvrez Paramètres, Connecteurs, et ajoutez un connecteur personnalisé avec l’adresse de votre serveur MCP.
• ChatGPT : ouvrez Paramètres, Apps et connecteurs. Sous Avancé, activez le mode développeur et créez un connecteur avec l’adresse, avec OAuth comme connexion.
• Autres apps : tout client MCP avec OAuth fonctionne. Le Layer prend en charge l’enregistrement dynamique (RFC 7591) et les Client ID Metadata Documents, et publie ses informations sur /.well-known/oauth-authorization-server et /.well-known/oauth-protected-resource.

Les noms de menu dans Claude et ChatGPT varient parfois selon la version. L’app ne voit que les outils liés aux droits choisis. La lecture est directe. Versions de protocole prises en charge : 2026-07-28, 2025-11-25, 2025-06-18 et 2025-03-26.

D’abord un plan. L’app effectue immédiatement une modification isolée. Plusieurs modifications à la fois, ou quelque chose qui crée une structure comme un projet avec des tâches, elle les consigne d’abord dans un plan : exactement les actions avec leurs données. Vous voyez ce plan dans votre chat, et ce n’est qu’après votre oui explicite que le Layer exécute exactement ces actions, une seule fois. Les modifications internes (un lead, un contact, une note, une tâche, un rendez-vous sans invitation, un projet ou un document), le Layer les exécute alors immédiatement, si votre espace de travail le permet. Vous les retrouvez dans Approbations et pouvez les y annuler. Tout ce qui sort ou concerne de l’argent, comme un e-mail, une invitation, l’envoi d’un devis ou une facture, reste toujours une proposition que vous approuvez. Une session via MCP compte toujours comme texte externe.

Une app connectée continue de fonctionner jusqu’à ce que vous la révoquiez dans Paramètres, Appareils, ou jusqu’à ce qu’elle n’ait pas été utilisée pendant 30 jours.

6. Des questions ou un problème ?

Écrivez à info@tromptech.nl. Un problème de sécurité, signalez-le de préférence de manière confidentielle, comme décrit dans Signaler un problème de sécurité.