Référence API

Référence REST

138 opérations, leurs paramètres, corps et réponses.

Référence générée depuis le contrat versionné · Version Markdown

Contrat téléchargeable#

Cette référence est générée depuis le contrat OpenAPI versionné. Base : /api/v1. Le document de votre instance reste accessible par GET /api/v1/openapi.json. Les schémas complets décrivent les objets imbriqués, valeurs nulles, enums et contraintes.

Télécharger OpenAPI · Conventions et authentification

Ressources#

Sécurité du contrat

{
  "oauth2": {
    "type": "oauth2",
    "description": "Grant client_credentials - token Bearer opaque, TTL 1 h.",
    "flows": {
      "clientCredentials": {
        "tokenUrl": "/api/v1/oauth/token",
        "scopes": {
          "referentials:read": "Référentiels - lecture (cycles, entités, secteurs, users)",
          "referentials:write": "Référentiels - écriture (identité légale & bancaire des entités)",
          "companies:read": "Sociétés - lecture (+ affiliations)",
          "companies:write": "Sociétés - écriture (+ affiliations)",
          "contacts:read": "Contacts - lecture (+ affiliations)",
          "contacts:write": "Contacts - écriture (+ affiliations)",
          "products:read": "Produits - lecture (+ tarifs)",
          "products:write": "Produits - écriture (+ tarifs)",
          "quotes:read": "Devis - lecture",
          "quotes:write": "Devis - écriture (CRUD + transitions)",
          "invoices:read": "Factures - lecture (avoirs, échéances)",
          "invoices:write": "Factures - écriture (avoirs, échéances)",
          "requests:read": "Requêtes - lecture",
          "requests:write": "Requêtes - écriture (CRUD + transitions)",
          "sales_activities:read": "Activités commerciales - lecture",
          "sales_activities:write": "Activités commerciales - écriture (CRUD + transitions)",
          "signatures:read": "Signature électronique - lecture des enveloppes et du dossier de preuve",
          "signatures:write": "Signature électronique - création, relance, annulation d'enveloppes",
          "webhooks:manage": "Webhooks sortants - gestion des abonnements",
          "exports:read": "Exports de l'organisation - liste et téléchargement des archives",
          "users:read": "Utilisateurs - lecture d'administration (comptes, profils, état, invitation en attente)",
          "users:write": "Utilisateurs - inviter, modifier le profil, désactiver, réactiver, renvoyer l'invitation (toujours soumis à l'approbation d'un administrateur)",
          "marketing:read": "Marketing - lecture (campagnes, segments, étiquettes, consentement, formulaires, invitations)",
          "marketing:write": "Marketing - écriture (brouillons, segments, étiquettes, consentement prouvé, envoi d'une campagne)",
          "documents:read": "Documents des fiches - liste et lien de téléchargement signé (15 minutes)",
          "settings:write": "Réglages - objectifs individuels des commerciaux (lecture et écriture)"
        }
      }
    }
  },
  "userSession": {
    "type": "http",
    "scheme": "bearer",
    "description": "Session utilisateur Better Auth en Bearer (T-685, docs/08-API §2bis) - obtenue à la connexion (header set-auth-token). Les scopes publiés ne s'appliquent pas : les droits sont les permissions objet et la visibilité de l'utilisateur, à l'identique de l'UI web."
  }
}

Schémas partagés et références $ref

{
  "Problem": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "type": {
        "type": "string",
        "description": "URN stable urn:cercla:problem:<slug> - la clé à tester"
      },
      "title": {
        "type": "string"
      },
      "status": {
        "type": "integer",
        "minimum": -9007199254740991,
        "maximum": 9007199254740991
      },
      "detail": {
        "type": "string"
      },
      "instance": {
        "type": "string",
        "description": "Id de corrélation des logs serveur"
      },
      "errors": {
        "description": "Détail par champ - uniquement sur les erreurs de validation",
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "path": {
              "type": "string"
            },
            "message": {
              "type": "string"
            }
          },
          "required": [
            "path",
            "message"
          ],
          "additionalProperties": false
        }
      }
    },
    "required": [
      "type",
      "title",
      "status",
      "instance"
    ],
    "additionalProperties": false
  }
}