API publique

Conçue pour les serveurs, pas pour les navigateurs

L'API publique sert aux automatisations exécutées sur une infrastructure que vous contrôlez : tâches cron, backends et pipelines CI. Elle gère les formulaires et leurs champs, et lit et traite les soumissions. Elle est distincte de l'API de soumission de formulaires, qui reçoit les données des visiteurs de votre site ; si c'est votre besoin, commencez par sa documentation.

Ce que vous pouvez faire

Chaque opération est autorisée par les scopes de votre clé API et par les formulaires auxquels cette clé est accordée.

• Gérer les formulaires — les lister, en créer, les modifier et les supprimer, conformément aux scopes forms:read, forms:create, forms:update et forms:delete.
• Définir les champs — lire et mettre à jour la configuration des champs d'un formulaire avec les scopes forms:read et forms:update.
• Lire les soumissions — lister les soumissions par formulaire et les marquer comme lues avec les scopes submissions:read et submissions:mark_read.
• Accéder aux fichiers — obtenir un accès de téléchargement autorisé et à courte durée pour les fichiers joints aux soumissions.
• Opérer les workflows — consulter et modifier les brouillons, valider et publier les versions, lancer des tests à sec, consulter les exécutions et réessayer les échecs admissibles.

Une requête minimale

Chaque appel est authentifié avec une clé API Bearer dans l'en-tête Authorization. Les clés ressemblent à smto_live_<key_id>_<secret> : il s'agit uniquement du format, pas d'une clé fonctionnelle.

Authorization: Bearer smto_live_<key_id>_<secret>
Accept: application/json

請先呼叫GET /v1/capabilities確認此 Key 的可用能力:

curl https://api.submeto.com/v1/capabilities \
  -H "Authorization: Bearer smto_live_<key_id>_<secret>" \
  -H "Accept: application/json"

Choisissez un accès restreint et prévoyez la rotation

Une clé est un identifiant serveur indépendant. Modifier votre mot de passe ne la révoque pas ; gérez donc délibérément ses scopes, sa durée de vie et sa révocation.

• Commencez avec des formulaires sélectionnés, des scopes de lecture et une expiration de 90 jours ; élargissez l'accès uniquement lorsque l'automatisation en a besoin.
• La clé en clair n'est affichée qu'une seule fois. Si elle est perdue, créez-en une nouvelle plutôt que d'essayer de la récupérer.
• Si une clé a pu fuiter, révoquez-la immédiatement et faites tourner le secret du runtime.
• Désactiver l'API publique révoque définitivement toutes les clés actives. Réactiver l'accès ne restaure jamais une ancienne clé.

Règles d'exécution à connaître

• Appelez d'abord GET /v1/capabilities. L'accès effectif en écriture peut être indisponible même si une clé comprend des scopes d'écriture.
• Les modifications de formulaires et de workflows utilisent des ETags pour éviter les écritures obsolètes ; les opérations de création, publication, test et nouvelle tentative utilisent des clés d'idempotence lorsque nécessaire.
• Les opérations de liste utilisent une pagination par curseur bornée et des en-têtes de limite de débit. Après une réponse 429, respectez Retry-After.
• Les tests à sec de workflow n'envoient jamais de vrais messages, mais les étapes d'IA réservent et règlent tout de même des points de calcul.

Limites de sécurité

• Les clés API authentifient votre serveur, jamais un navigateur ou une application mobile. Utilisez uniquement des runtimes serveur à serveur via HTTPS.
• Les clés portent des scopes sélectionnés et peuvent être accordées à certains formulaires seulement. Les ressources non accordées ne sont pas visibles pour la clé.
• Les réponses omettent les secrets, tokens de formulaire, configurations d'intégration et payloads bruts des soumissions.
• Les opérations destructrices exigent une confirmation au niveau de l'application en plus des scopes.

Pour commencer

1. Ouvrez les paramètres du Dashboard, activez l'API publique après avoir examiné les risques de sécurité, puis créez une clé API avec le moindre privilège. La clé en clair n'est affichée qu'une fois : stockez-la immédiatement dans le gestionnaire de secrets de votre serveur.
2. Appelez GET /v1/capabilities pour confirmer la version de l'API, les scopes disponibles, l'état d'écriture et les limites de débit utilisables par votre clé.
3. Lisez le guide complet de l'API sur cette page et la spécification OpenAPI publiée avant de développer.

Contrat complet et OpenAPI

Cette page est le guide public. Utilisez la référence API générée et l'artefact OpenAPI pour consulter le contrat complet lisible par machine.