**Versions de l’API** · [V2 (Latest)](/integrations/v2/docs?lang=fr) · **V1**

> **Cette version de l’API est obsolète.** Utilisez la dernière version pour toute nouvelle intégration. [Voir la documentation actuelle](/integrations/v2/docs?lang=fr)

# Formulaires

OpenAPI 3.0.3 · API 1.0.0

```json
[
  {
    "url": "https://api.unisoft.world/integrations/v1",
    "description": "API"
  }
]
```

Formulaires transactionnels : définitions (structure, produits, champs) et soumissions. Autorisations : `forms:read`/`forms:write` pour les définitions, `forms_submit:read`/`forms_submit:write` pour les soumissions, `forms_submit:validate` pour accepter/refuser une soumission (un email est envoyé à son auteur).

## Opérations

## GET /forms

Lister les formulaires

`list_forms`

Autorisation requise : `forms:read`. Liste les formulaires de l’organisation (champs succincts). Résultats paginés.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "forms:read",
  "additional": []
}
```

### Paramètres

```json
{
  "name": "limit",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 200,
    "default": 50
  },
  "description": "Nombre de résultats par page."
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "schema": {
    "type": "string"
  },
  "description": "Curseur opaque renvoyé par la requête précédente."
}
```

```json
{
  "name": "active",
  "in": "query",
  "schema": {
    "type": "boolean"
  },
  "description": "Filtrer par état actif."
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FormDefinition"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/Pagination"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "ERREUR",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "ERROR"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "AUTORISATION_INSUFFISANTE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INSUFFICIENT_SCOPE"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "forms:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /forms

Créer un formulaire

`create_form`

Autorisation requise : `forms:write`. Crée une DÉFINITION de formulaire à partir de l’objet métier de l’éditeur. La transpilation de `additionalFields` et l’enregistrement de `products` sont gérés côté serveur. Renvoie le formulaire créé dans la structure de l’éditeur.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "forms:write",
  "additional": []
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/FormInput"
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/FormInput"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "ERREUR_DE_VALIDATION",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "VALIDATION_ERROR"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "AUTORISATION_INSUFFISANTE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INSUFFICIENT_SCOPE"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "forms:write",
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## GET /forms/{id}

Obtenir la définition d’un formulaire (produits, calendriers, contenu)

`get_form`

Autorisation requise : `forms:read`. Renvoie la même charge utile que le site public utilise pour afficher le formulaire (`content` transpilé), limitée à l’organisation de la clé API. Pour MODIFIER un formulaire, consultez plutôt `/forms/{id}/edit`.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "forms:read",
  "additional": []
}
```

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Identifiant de ressource — doit être un UUID. Un identifiant mal formé est refusé avec 400 INVALID_UUID (pas simplement 404). Besoin d’un nouvel identifiant ? Appelez GET /utils/uuid."
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/FormDefinition"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "forms:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## PATCH /forms/{id}

Modifier un formulaire

`update_form`

Autorisation requise : `forms:write`. Mise à jour partielle d’une DÉFINITION de formulaire (objet métier de l’éditeur). Seuls les champs fournis sont modifiés ; omettez `products`/`additionalFields` pour les laisser tels quels, envoyez-les pour remplacer l’ensemble. Renvoie le formulaire modifié dans la structure de l’éditeur.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "forms:write",
  "additional": []
}
```

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Identifiant de ressource — doit être un UUID. Un identifiant mal formé est refusé avec 400 INVALID_UUID (pas simplement 404). Besoin d’un nouvel identifiant ? Appelez GET /utils/uuid."
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/FormUpdateInput"
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/FormInput"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "ERREUR_DE_VALIDATION",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "VALIDATION_ERROR"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "forms:write",
  "x-unisoft-mcp": {
    "category": "update",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /forms/{id}/edit

Obtenir un formulaire dans le format de l’éditeur

`get_form_edit`

Autorisation requise : `forms:read`. Renvoie l’objet métier de l’éditeur (produits intégrés, `additionalFields` reconstitués) — exactement la structure acceptée par `POST /forms` et `PATCH /forms/{id}`. Lisez cette ressource avant toute modification.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "forms:read",
  "additional": []
}
```

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Identifiant de ressource — doit être un UUID. Un identifiant mal formé est refusé avec 400 INVALID_UUID (pas simplement 404). Besoin d’un nouvel identifiant ? Appelez GET /utils/uuid."
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/FormInput"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "forms:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /forms-submit

Lister les soumissions de formulaire

`list_forms_submit`

Autorisation requise : `forms_submit:read`

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "forms_submit:read",
  "additional": []
}
```

### Paramètres

```json
{
  "name": "limit",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 200,
    "default": 50
  },
  "description": "Nombre de résultats par page."
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "schema": {
    "type": "string"
  },
  "description": "Curseur opaque renvoyé par la requête précédente."
}
```

```json
{
  "name": "createdAfter",
  "in": "query",
  "schema": {
    "type": "string",
    "format": "date-time"
  },
  "description": "Filtre : créé après cette date (ISO 8601)."
}
```

```json
{
  "name": "createdBefore",
  "in": "query",
  "schema": {
    "type": "string",
    "format": "date-time"
  },
  "description": "Filtre : créé avant cette date (ISO 8601)."
}
```

```json
{
  "name": "formId",
  "in": "query",
  "schema": {
    "type": "string"
  }
}
```

```json
{
  "name": "state",
  "in": "query",
  "schema": {
    "type": "string",
    "enum": [
      "SUBMIT",
      "VALIDE",
      "INVALIDE"
    ]
  },
  "description": "Filtrer par état de décision. SUBMIT = décision en attente."
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FormSubmit"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/Pagination"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "forms_submit:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /forms-submit

Soumettre un formulaire

`create_forms_submit`

Autorisation requise : `forms_submit:write`. Crée un document `forms_submit` et applique les mêmes effets secondaires que le site public (synchronisation CRM du contact, totaux, codes promotionnels, notifications, lien de paiement). Si un paiement est requis, `url` dans la réponse renvoie vers la page de paiement hébergée. Le mode modification (`data.extra.editId`) n’est pas pris en charge par cette opération.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "forms_submit:write",
  "additional": []
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/SubmitRequest"
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/SubmitResponse"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "MISSING_FORM_ID ou EDIT_MODE_NOT_SUPPORTED",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "MISSING_FORM_ID or EDIT_MODE_NOT_SUPPORTED"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "FORM_NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "FORM_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "forms_submit:write",
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## POST /forms-submit/with-payment

Soumettre un formulaire et créer le lien de paiement en un seul appel

`create_forms_submit_with_payment`

Autorisations requises : `forms_submit:write` ET `paiements:write`. Même comportement que `POST /forms-submit` — opération pratique rendant explicites les autorisations requises lorsque l’appelant sait qu’un paiement est attendu. L’URL de paiement est renvoyée dans `url`.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "forms_submit:write",
  "additional": []
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/SubmitRequest"
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/SubmitResponse"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "MISSING_FORM_ID ou EDIT_MODE_NOT_SUPPORTED",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "MISSING_FORM_ID or EDIT_MODE_NOT_SUPPORTED"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPES",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INSUFFICIENT_SCOPES"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "FORM_NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "FORM_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "forms_submit:write",
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## GET /forms-submit/{id}

Obtenir une soumission de formulaire

`get_forms_submit`

Autorisation requise : `forms_submit:read`

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "forms_submit:read",
  "additional": []
}
```

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Identifiant de ressource — doit être un UUID. Un identifiant mal formé est refusé avec 400 INVALID_UUID (pas simplement 404). Besoin d’un nouvel identifiant ? Appelez GET /utils/uuid."
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/FormSubmit"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "forms_submit:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /forms-submit/{id}/validate

Accepter une soumission (⚠️ envoie un email à son auteur)

`validate_submission`

Autorisation requise : `forms_submit:validate`. Définit la soumission à l’état VALIDE et ENVOIE un email de confirmation à son auteur — effet réel, d’où cette autorisation dédiée. Idempotent : renvoie `already:true` si la soumission était déjà VALIDE.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "forms_submit:validate",
  "additional": []
}
```

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Identifiant de ressource — doit être un UUID. Un identifiant mal formé est refusé avec 400 INVALID_UUID (pas simplement 404). Besoin d’un nouvel identifiant ? Appelez GET /utils/uuid."
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "AUTORISATION_INSUFFISANTE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INSUFFICIENT_SCOPE"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "forms_submit:validate",
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "destructive": true,
    "idempotent": false,
    "warn": true
  }
}
```

## POST /forms-submit/{id}/invalidate

Refuser une soumission (sans email)

`invalidate_submission`

Autorisation requise : `forms_submit:validate`. Définit la soumission à l’état INVALIDE. N’envoie d’email à personne. Idempotent : renvoie `already:true` si la soumission était déjà INVALIDE.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "forms_submit:validate",
  "additional": []
}
```

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Identifiant de ressource — doit être un UUID. Un identifiant mal formé est refusé avec 400 INVALID_UUID (pas simplement 404). Besoin d’un nouvel identifiant ? Appelez GET /utils/uuid."
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "AUTORISATION_INSUFFISANTE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INSUFFICIENT_SCOPE"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "forms_submit:validate",
  "x-unisoft-mcp": {
    "category": "update",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## Schémas

```json
{
  "components": {
    "parameters": {
      "LimitParam": {
        "name": "limit",
        "in": "query",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 200,
          "default": 50
        },
        "description": "Nombre de résultats par page."
      },
      "CursorParam": {
        "name": "cursor",
        "in": "query",
        "schema": {
          "type": "string"
        },
        "description": "Curseur opaque renvoyé par la requête précédente."
      },
      "IdParam": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid",
          "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
        },
        "description": "Identifiant de ressource — doit être un UUID. Un identifiant mal formé est refusé avec 400 INVALID_UUID (pas simplement 404). Besoin d’un nouvel identifiant ? Appelez GET /utils/uuid."
      },
      "CreatedAfterParam": {
        "name": "createdAfter",
        "in": "query",
        "schema": {
          "type": "string",
          "format": "date-time"
        },
        "description": "Filtre : créé après cette date (ISO 8601)."
      },
      "CreatedBeforeParam": {
        "name": "createdBefore",
        "in": "query",
        "schema": {
          "type": "string",
          "format": "date-time"
        },
        "description": "Filtre : créé avant cette date (ISO 8601)."
      }
    },
    "schemas": {
      "FormDefinition": {
        "type": "object",
        "description": "Définition publique d’un formulaire (produits, calendriers, HTML transpilé).",
        "properties": {
          "id": {
            "type": "string"
          },
          "organisation": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "SIMPLE",
              "COMPLEX"
            ]
          },
          "title": {
            "type": "string"
          },
          "active": {
            "type": "boolean"
          },
          "withPaiement": {
            "type": "boolean"
          },
          "autoValid": {
            "type": "boolean"
          },
          "requirePaiementValidation": {
            "type": "boolean"
          },
          "content": {
            "type": "string",
            "description": "HTML transpilé lorsque type=SIMPLE."
          },
          "afficheUrl": {
            "type": "string",
            "description": "URL absolue de l’affiche/de l’image de couverture affichée en haut du formulaire (présente si définie)."
          },
          "aiContentBlockId": {
            "type": "string",
            "description": "Identifiant du bloc de contenu IA affiché sous forme de bannière enrichie en haut du formulaire (présent s’il est défini)."
          },
          "products": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FormProduct"
            }
          },
          "calendars": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "expired": {
            "type": "boolean",
            "description": "True si la session PE associée n’est plus active."
          }
        }
      },
      "FormProduct": {
        "type": "object",
        "description": "Ligne de produit d’un formulaire COMPLEX (article acheté).",
        "properties": {
          "id": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "montant": {
            "type": "number",
            "description": "Montant unitaire en unités majeures (par ex. euros)."
          },
          "cerfa": {
            "type": "boolean"
          },
          "simple_stock": {
            "type": "integer",
            "nullable": true
          },
          "activeReducedPrice": {
            "type": "boolean"
          },
          "reducedPercent": {
            "type": "number",
            "nullable": true
          },
          "reducedExpireAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "position": {
            "type": "integer"
          }
        }
      },
      "Pagination": {
        "type": "object",
        "properties": {
          "nextCursor": {
            "type": "string",
            "nullable": true
          },
          "hasMore": {
            "type": "boolean"
          },
          "count": {
            "type": "integer"
          }
        }
      },
      "FormInput": {
        "type": "object",
        "description": "Objet métier de l’éditeur pour une DÉFINITION de formulaire — structure à envoyer pour créer ou modifier un formulaire, et structure renvoyée par GET /forms/{id}/edit. Un formulaire est un moteur transactionnel flexible : une soumission peut correspondre à une commande de billets, un achat de plusieurs produits, une inscription familiale, un don, etc. Distinguez le PAYEUR (qui soumet) des BÉNÉFICIAIRES (renseignés dans les champs supplémentaires du produit). Dans un PATCH partiel, omettez `products`/`additionalFields` pour les laisser tels quels ; envoyez-les pour remplacer l’ensemble.",
        "required": [
          "title"
        ],
        "properties": {
          "title": {
            "type": "string",
            "description": "Titre public du formulaire (obligatoire)."
          },
          "url": {
            "type": "string",
            "description": "Slug public (minuscules, sans accents, espaces remplacés par \"-\"). Facultatif."
          },
          "description": {
            "type": "string",
            "description": "Description interne (visible par l’admin uniquement)."
          },
          "afficheUrl": {
            "type": "string",
            "description": "URL de l’affiche/de l’image de couverture ou nom du fichier hébergé, affiché en haut du formulaire. Ajoute les métadonnées de partage WhatsApp. Envoyez \"\" pour la supprimer. Peut coexister avec aiContentBlockId (les deux peuvent être définis)."
          },
          "aiContentBlockId": {
            "type": "string",
            "nullable": true,
            "description": "Identifiant d’un bloc de contenu IA (ai_content_blocks), affiché sous forme de bannière HTML enrichie tout en haut du formulaire, au-dessus des champs d’identité. Facultatif — omettre pour ne pas modifier ; envoyer \"\"/null pour le supprimer. Indépendant de afficheUrl (l’image d’affiche) : un formulaire peut afficher les deux."
          },
          "autoValid": {
            "type": "boolean",
            "description": "true = soumissions validées automatiquement ; false = validation manuelle."
          },
          "withPaiement": {
            "type": "boolean",
            "description": "Activer le paiement en ligne. Si false, tous les champs de paiement ci-dessous sont ignorés."
          },
          "paiementType": {
            "type": "string",
            "enum": [
              "PAIEMENT",
              "ABONNEMENT",
              "MONTHLY"
            ],
            "description": "Modèle de facturation : PAIEMENT = paiement ponctuel ; ABONNEMENT = versements limités ; MONTHLY = paiement mensuel récurrent. Nécessite withPaiement=true."
          },
          "onePaiement": {
            "type": "boolean",
            "description": "Imposer un paiement unique (sans acompte). Uniquement avec paiementType=PAIEMENT."
          },
          "deposit": {
            "type": "number",
            "description": "Montant fixe de l’acompte. paiementType=PAIEMENT et onePaiement=false."
          },
          "depositPercent": {
            "type": "number",
            "description": "Acompte en pourcentage (0-100). Même dépendance que `deposit`."
          },
          "abonnementMaxMonth": {
            "type": "integer",
            "description": "Nombre maximal de versements (≥2). paiementType=ABONNEMENT."
          },
          "aboMonthInfinite": {
            "type": "boolean",
            "description": "Abonnement sans date de fin. paiementType=MONTHLY."
          },
          "aboMonthMin": {
            "type": "integer",
            "description": "Nombre minimal de mois d’abonnement (≥1). MONTHLY + aboMonthInfinite=false."
          },
          "aboMonthMax": {
            "type": "integer",
            "description": "Nombre maximal de mois d’abonnement (≥ aboMonthMin). MONTHLY + aboMonthInfinite=false."
          },
          "paiementMethods": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Autres moyens de paiement manuels possibles, par ex. [\"CHEQUE\",\"VIREMENT\",\"ESPECES\"]."
          },
          "requirePaiementValidation": {
            "type": "boolean",
            "description": "Validation conditionnée au paiement en ligne. Nécessite withPaiement=true."
          },
          "autoValidOtherPaiementMethod": {
            "type": "boolean",
            "description": "Valider automatiquement les paiements par un autre moyen. Nécessite requirePaiementValidation=true."
          },
          "allowZeroAmount": {
            "type": "boolean",
            "description": "Autoriser une soumission dont le total est égal à 0."
          },
          "identity": {
            "type": "string",
            "enum": [
              "SIMPLE"
            ],
            "description": "Niveau d’identification du contact. SIMPLE = nom complet + email + téléphone."
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Catégories CRM appliquées automatiquement à chaque contact ayant soumis le formulaire."
          },
          "globalStock": {
            "type": "integer",
            "nullable": true,
            "description": "Stock partagé qui remplace les stocks définis par produit."
          },
          "allowNoProduct": {
            "type": "boolean",
            "description": "Autoriser l’envoi d’une soumission sans sélectionner de produit."
          },
          "products": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FormProductInput"
            },
            "description": "Articles pouvant être achetés. Utilisez des produits distincts pour des prix différents."
          },
          "additionalFields": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FormAdditionalField"
            },
            "description": "Champs personnalisés globaux (une fois par soumission)."
          }
        }
      },
      "FormProductInput": {
        "type": "object",
        "description": "Ligne de produit d’un formulaire (article, billet ou option pouvant être acheté). LES VARIATIONS DE PRIX SE FONT UNIQUEMENT AU MOYEN DE PRODUITS DISTINCTS — jamais avec des options tarifaires sur un seul produit.",
        "required": [
          "label",
          "title",
          "montant"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Identifiant du produit (omettre à la création ; lors de la modification, correspondance par identifiant ou libellé)."
          },
          "label": {
            "type": "string",
            "description": "Libellé interne unique dans le formulaire."
          },
          "title": {
            "type": "string",
            "description": "Titre public affiché à l’acheteur."
          },
          "description": {
            "type": "string",
            "description": "Description interne (visible par l’admin uniquement)."
          },
          "montant": {
            "type": "number",
            "description": "Prix unitaire en unités MAJEURES (par ex. euros). 0 = gratuit. Interprété par mois lorsque paiementType=MONTHLY."
          },
          "cerfa": {
            "type": "boolean",
            "description": "Indique si ce produit ouvre droit à un reçu fiscal."
          },
          "active": {
            "type": "boolean",
            "description": "Indique si le produit est actif (true par défaut)."
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Catégories CRM appliquées au contact UNIQUEMENT lorsque ce produit est sélectionné."
          },
          "simple_stock": {
            "type": "integer",
            "description": "Limite de stock pour ce produit. Ignorée lorsque globalStock est défini."
          },
          "additionalFields": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FormAdditionalField"
            },
            "description": "Champs par produit, répétés pour chaque quantité achetée."
          }
        }
      },
      "FormAdditionalField": {
        "type": "object",
        "description": "Champ dynamique ajouté à un formulaire (ou à un produit). Deux portées : les champs GLOBAL (à la racine du formulaire) apparaissent une fois par soumission ; les champs PRODUCT (dans un produit) se répètent pour chaque unité achetée. Utilisez un champ produit uniquement pour recueillir des informations par unité ; tout ce qui concerne la commande entière doit être un champ global.",
        "required": [
          "type"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "TEXT-INPUT",
              "TEXTAREA-INPUT",
              "SELECT-INPUT",
              "CHECKBOX-INPUT",
              "DOCS-INPUT",
              "DATE-INPUT",
              "TITLE",
              "CONTACT-INPUT",
              "FREE-AMOUNT-INPUT"
            ],
            "description": "Type de champ. TEXT-INPUT = texte libre sur une ligne ; TEXTAREA-INPUT = texte libre multiligne (avec `height` facultatif en px) ; SELECT-INPUT = liste déroulante (nécessite `values`) ; CHECKBOX-INPUT = oui/non ; DOCS-INPUT = téléversement de fichier (nécessite `doctype`) ; DATE-INPUT = sélecteur de date/heure (`picker`/`dateFilter`/`range`/`defaultNow` facultatifs, date simple par défaut) ; TITLE = séparateur visuel (aucune donnée ; utilise `__title_tag`+`__text`) ; CONTACT-INPUT = contact CRM secondaire (nom+email+téléphone) ; FREE-AMOUNT-INPUT = montant choisi par le donateur (GLOBAL uniquement, exige withPaiement=true, jamais dans un produit)."
          },
          "required": {
            "type": "boolean",
            "description": "Indique si le champ est obligatoire."
          },
          "__label": {
            "type": "string",
            "description": "Libellé visible du champ."
          },
          "values": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Options de SELECT-INPUT (obligatoires pour ce type)."
          },
          "doctype": {
            "type": "string",
            "enum": [
              "IMG",
              "PDF",
              "ZIP"
            ],
            "description": "Type de fichier autorisé pour DOCS-INPUT."
          },
          "height": {
            "type": "integer",
            "description": "TEXTAREA-INPUT uniquement : hauteur fixe de la zone de texte, en pixels (facultative)."
          },
          "picker": {
            "type": "string",
            "enum": [
              "Date & Heure",
              "Uniquement les Années",
              "Uniquement les Mois",
              "Uniquement l'heure"
            ],
            "description": "DATE-INPUT uniquement : granularité. Omettre pour une date simple (JJ/MM/AAAA). \"Date & Heure\" = date et heure ; \"Uniquement les Années\" = année ; \"Uniquement les Mois\" = mois ; \"Uniquement l'heure\" = heure."
          },
          "dateFilter": {
            "type": "string",
            "enum": [
              "Antérieur à aujourd'hui",
              "Ultérieur à aujourd'hui",
              "Aujourd'hui & antérieur à aujourd'hui",
              "Aujourd'hui & ultérieur à aujourd'hui"
            ],
            "description": "DATE-INPUT uniquement : limiter les dates sélectionnables par rapport à aujourd’hui (facultatif)."
          },
          "range": {
            "type": "boolean",
            "description": "DATE-INPUT uniquement : choisir une plage début→fin plutôt qu’une seule valeur (facultatif)."
          },
          "defaultNow": {
            "type": "boolean",
            "description": "DATE-INPUT uniquement : préremplir avec la date/heure actuelle (facultatif)."
          },
          "__title_tag": {
            "type": "string",
            "enum": [
              "h1",
              "h2",
              "h3",
              "h4",
              "h5"
            ],
            "description": "Niveau de titre pour TITLE."
          },
          "__text": {
            "type": "string",
            "description": "Texte du titre pour TITLE."
          }
        }
      },
      "FormUpdateInput": {
        "type": "object",
        "description": "Mise à jour partielle de définition de formulaire. Seuls les champs fournis sont modifiés ; aucun champ n’est obligatoire.",
        "properties": {
          "title": {
            "type": "string",
            "description": "Titre public du formulaire (obligatoire)."
          },
          "url": {
            "type": "string",
            "description": "Slug public (minuscules, sans accents, espaces remplacés par \"-\"). Facultatif."
          },
          "description": {
            "type": "string",
            "description": "Description interne (visible par l’admin uniquement)."
          },
          "afficheUrl": {
            "type": "string",
            "description": "URL de l’affiche/de l’image de couverture ou nom du fichier hébergé, affiché en haut du formulaire. Ajoute les métadonnées de partage WhatsApp. Envoyez \"\" pour la supprimer. Peut coexister avec aiContentBlockId (les deux peuvent être définis)."
          },
          "aiContentBlockId": {
            "type": "string",
            "nullable": true,
            "description": "Identifiant d’un bloc de contenu IA (ai_content_blocks), affiché sous forme de bannière HTML enrichie tout en haut du formulaire, au-dessus des champs d’identité. Facultatif — omettre pour ne pas modifier ; envoyer \"\"/null pour le supprimer. Indépendant de afficheUrl (l’image d’affiche) : un formulaire peut afficher les deux."
          },
          "autoValid": {
            "type": "boolean",
            "description": "true = soumissions validées automatiquement ; false = validation manuelle."
          },
          "withPaiement": {
            "type": "boolean",
            "description": "Activer le paiement en ligne. Si false, tous les champs de paiement ci-dessous sont ignorés."
          },
          "paiementType": {
            "type": "string",
            "enum": [
              "PAIEMENT",
              "ABONNEMENT",
              "MONTHLY"
            ],
            "description": "Modèle de facturation : PAIEMENT = paiement ponctuel ; ABONNEMENT = versements limités ; MONTHLY = paiement mensuel récurrent. Nécessite withPaiement=true."
          },
          "onePaiement": {
            "type": "boolean",
            "description": "Imposer un paiement unique (sans acompte). Uniquement avec paiementType=PAIEMENT."
          },
          "deposit": {
            "type": "number",
            "description": "Montant fixe de l’acompte. paiementType=PAIEMENT et onePaiement=false."
          },
          "depositPercent": {
            "type": "number",
            "description": "Acompte en pourcentage (0-100). Même dépendance que `deposit`."
          },
          "abonnementMaxMonth": {
            "type": "integer",
            "description": "Nombre maximal de versements (≥2). paiementType=ABONNEMENT."
          },
          "aboMonthInfinite": {
            "type": "boolean",
            "description": "Abonnement sans date de fin. paiementType=MONTHLY."
          },
          "aboMonthMin": {
            "type": "integer",
            "description": "Nombre minimal de mois d’abonnement (≥1). MONTHLY + aboMonthInfinite=false."
          },
          "aboMonthMax": {
            "type": "integer",
            "description": "Nombre maximal de mois d’abonnement (≥ aboMonthMin). MONTHLY + aboMonthInfinite=false."
          },
          "paiementMethods": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Autres moyens de paiement manuels possibles, par ex. [\"CHEQUE\",\"VIREMENT\",\"ESPECES\"]."
          },
          "requirePaiementValidation": {
            "type": "boolean",
            "description": "Validation conditionnée au paiement en ligne. Nécessite withPaiement=true."
          },
          "autoValidOtherPaiementMethod": {
            "type": "boolean",
            "description": "Valider automatiquement les paiements par un autre moyen. Nécessite requirePaiementValidation=true."
          },
          "allowZeroAmount": {
            "type": "boolean",
            "description": "Autoriser une soumission dont le total est égal à 0."
          },
          "identity": {
            "type": "string",
            "enum": [
              "SIMPLE"
            ],
            "description": "Niveau d’identification du contact. SIMPLE = nom complet + email + téléphone."
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Catégories CRM appliquées automatiquement à chaque contact ayant soumis le formulaire."
          },
          "globalStock": {
            "type": "integer",
            "nullable": true,
            "description": "Stock partagé qui remplace les stocks définis par produit."
          },
          "allowNoProduct": {
            "type": "boolean",
            "description": "Autoriser l’envoi d’une soumission sans sélectionner de produit."
          },
          "products": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FormProductInput"
            },
            "description": "Articles pouvant être achetés. Utilisez des produits distincts pour des prix différents."
          },
          "additionalFields": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FormAdditionalField"
            },
            "description": "Champs personnalisés globaux (une fois par soumission)."
          }
        }
      },
      "FormSubmit": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "organisation": {
            "type": "string"
          },
          "form": {
            "type": "string",
            "description": "Identifiant du formulaire"
          },
          "state": {
            "type": "string"
          },
          "data": {
            "type": "object"
          },
          "total": {
            "type": "number",
            "description": "Montant total attendu pour l’inscription, en unités majeures de la devise."
          },
          "devise": {
            "type": "string",
            "description": "Code de devise."
          },
          "paye": {
            "type": "number",
            "readOnly": true,
            "description": "Montant réellement payé (somme des paiements COMPLETED), en unités majeures."
          },
          "reste": {
            "type": "number",
            "readOnly": true,
            "description": "Solde restant (max(0, total - paye)), en unités majeures."
          },
          "paiements": {
            "type": "array",
            "readOnly": true,
            "description": "Paiements COMPLETED de cette soumission (montants en unités majeures). Disponible uniquement sur GET /forms-submit/{id}.",
            "items": {
              "type": "object",
              "properties": {
                "amount": {
                  "type": "number"
                },
                "method": {
                  "type": "string",
                  "nullable": true
                },
                "datetime": {
                  "type": "string",
                  "format": "date-time"
                }
              }
            }
          },
          "datetime": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "SubmitRequest": {
        "type": "object",
        "required": [
          "formId"
        ],
        "properties": {
          "formId": {
            "type": "string",
            "description": "Identifiant du formulaire cible (doit appartenir à l’organisation de la clé API)."
          },
          "devise": {
            "type": "string",
            "description": "Devise de la soumission. Par défaut, devise du formulaire.",
            "nullable": true
          },
          "data": {
            "type": "object",
            "description": "Données de soumission libres. Clés courantes : `identity` (objet contact), `__promo`, `__paiementMethod`, `[CONTACT]_*`, `[HAZKARA]_*`, `[CHILD]_*`, `[FREE_AMOUNT]_*`, `<productId>_quantity`. Remarque : `data.extra.editId` est refusé pour les intégrations.",
            "additionalProperties": true
          }
        }
      },
      "SubmitResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/FormSubmit"
          },
          "url": {
            "type": "string",
            "nullable": true,
            "description": "URL du lien de paiement si la soumission nécessite un paiement ; sinon null."
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Format : `ke_live_xxx`"
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  }
}
```
