> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firma.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Mettre à Jour Partiellement un Modèle
> Met à jour les propriétés du modèle, un seul utilisateur, OU un seul champ. Impossible de mélanger plusieurs types d'entités dans une seule requête. Utilisez PUT pour des mises à jour complètes incluant les utilisateurs, les champs et les rappels.
## OpenAPI
````yaml api-reference/v01.39.00/openapi-v01.39.00.fr.json patch /templates/{id}
openapi: 3.0.3
info:
title: API Partenaire Firma
description: >-
API RESTful pour la signature de documents et la gestion de modèles.
**Authentification** : Tous les endpoints nécessitent une authentification
par clé API via l'en-tête `Authorization`. Utilisez votre clé API
directement sans préfixe (par exemple, `your-api-key`). Le préfixe Bearer
est optionnel mais pas obligatoire.
**Fonctionnalités de sécurité** :
- Validation des entrées avec des schémas Zod incluant des messages d'erreur
détaillés au niveau des champs
- Jetons JWT signés RSA-256 pour l'accès aux modèles intégrés
**Limitation de débit** : Les limites de débit sont hiérarchisées selon le
type d'opération :
- Opérations de lecture (GET) : 200 requêtes par minute
- Opérations d'écriture (POST/PUT/PATCH/DELETE) : 120 requêtes par minute
- Opérations CRUD sur les webhooks : 60 requêtes par minute
- Test de webhook : 10 requêtes par minute
- Régénération/expiration de clé API : 1 requête par minute
- Rotation du secret de webhook : 1 requête par minute
Lorsque les limites de débit sont dépassées, l'API renvoie une réponse `429
Too Many Requests` avec les en-têtes suivants :
- `X-RateLimit-Limit` : Nombre maximal de requêtes par minute pour cet
endpoint
- `X-RateLimit-Remaining` : Requêtes restantes dans la fenêtre actuelle
- `X-RateLimit-Reset` : Horodatage Unix de la réinitialisation de la limite
- `Retry-After` : Secondes à attendre avant de pouvoir réessayer
**Gestion des erreurs** : Toutes les erreurs renvoient des réponses JSON
structurées avec `error` (message lisible par un humain), `code`
(identifiant lisible par une machine) et `details` (erreurs de validation au
niveau des champs, le cas échéant).
**Intégration de l'Éditeur de Modèles intégré** : L'Éditeur de Modèles Firma
peut être intégré dans votre application à l'aide d'une bibliothèque
JavaScript autonome.
```html
```
**En-tête X-Firma-Deprecation** : Certaines opérations de création de cachet
et de mise à jour d'image renvoient un en-tête de réponse
`X-Firma-Deprecation` lorsqu'elles sont appelées via l'edge gateway,
indiquant que l'opération doit être effectuée sur l'hôte principal de l'API.
**Documents multiples (API 01.39.00, activation requise)** : un modèle ou
une demande de signature peut contenir jusqu'à 20 documents. Les routes de
la sous-ressource `/documents` et les clés `documents`, `documents_version`
et `documents_layout_version` ne sont servies qu'aux entreprises activées
pour les documents multiples ; pour toute autre entreprise, les routes
répondent `404 NOT_FOUND` et les clés sont absentes.
version: 01.39.00
contact:
name: API Support
url: https://firma.com/support
servers:
- url: https://api.firma.dev/functions/v1/signing-request-api
description: API de Production - Recommandée (Actuelle)
- url: https://api.firma.dev/api/v1
description: API de Production - Prévue
security:
- ApiKeyAuth: []
tags:
- name: Company
description: Informations et paramètres de l'entreprise
- name: Workspaces
description: Opérations de gestion des Espaces de Travail
- name: Templates
description: Opérations de gestion des Modèles
- name: Signing Requests
description: Opérations de Demande de Signature de documents
- name: Custom Fields
description: >-
Gestion des définitions de champs personnalisés pour les espaces de
travail, modèles et demandes de signature
- name: Webhooks
description: Configuration et gestion des webhooks
- name: JWT Management
description: Génération et révocation de jetons JWT pour les modèles intégrés
- name: Workspace Settings
description: Configuration et paramètres de l'espace de travail
- name: Email Domains
description: >-
Configuration et vérification de domaine e-mail pour l'envoi d'e-mails de
demande de signature depuis des domaines personnalisés
- name: Email Templates
description: >-
Gestion des modèles d'e-mail pour la personnalisation des notifications de
demande de signature au niveau de l'espace de travail et de l'entreprise
- name: Organization Seals
description: >-
Gestion des cachets d'organisation : créer, mettre à jour, révoquer et
effacer les cachets appliqués aux demandes de signature
- name: Signer Terms
description: >-
Conditions d'utilisation / déclarations de consentement personnalisées
pour le signataire, au niveau de l'entreprise avec des surcharges par
espace de travail et par langue
paths:
/templates/{id}:
patch:
tags:
- Templates
summary: Mettre à Jour Partiellement un Modèle
description: >-
Met à jour les propriétés du modèle, un seul utilisateur, OU un seul
champ. Impossible de mélanger plusieurs types d'entités dans une seule
requête. Utilisez PUT pour des mises à jour complètes incluant les
utilisateurs, les champs et les rappels.
operationId: patchTemplate
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- type: object
description: Mettre à jour les propriétés du modèle
properties:
name:
type: string
description: Nom du modèle
maxLength: 255
description:
type: string
description: Description du modèle
document:
type: string
format: byte
description: >-
PDF ou DOCX encodé en base64 pour remplacer le document.
Les fichiers DOCX sont automatiquement convertis en PDF.
Pour les documents de plus de 5 Mo, utilisez POST
/documents et transmettez le document_id à la place.
(mutuellement exclusif avec document_id)
document_id:
type: string
format: uuid
description: >-
ID d'un document précédemment téléversé (mutuellement
exclusif avec document). À obtenir en appelant d'abord
POST /documents.
example: 123e4567-e89b-12d3-a456-426614174000
expiration_hours:
type: integer
minimum: 1
description: Heures avant expiration
settings:
type: object
properties:
allow_editing_before_sending:
type: boolean
attach_pdf_on_finish:
type: boolean
allow_download:
type: boolean
hand_drawn_only:
type: boolean
require_otp_verification:
type: boolean
nullable: true
disable_guided_navigation:
type: boolean
nullable: true
allow_presigning_download:
type: boolean
nullable: true
description: >-
Autorise les signataires à télécharger le document
original avant de signer. Hérite du paramètre de
l'espace de travail ou de l'entreprise si null.
show_qr_code:
type: boolean
nullable: true
description: >-
Affiche un QR code sur la page de signature qui
permet aux signataires de continuer sur leur
téléphone. Hérite du paramètre de l'espace de
travail ou de l'entreprise si null.
- type: object
description: Mettre à jour ou créer un seul utilisateur
required:
- user
properties:
user:
type: object
required:
- first_name
- email
- designation
- order
properties:
id:
type: string
format: uuid
description: >-
À inclure pour mettre à jour un utilisateur
existant, à omettre pour en créer un nouveau. Un
destinataire existant ne peut pas passer de CC à
Signataire/Approbateur, ni inversement (400) ;
supprimez-le et recréez-le.
first_name:
type: string
maxLength: 255
last_name:
type: string
maxLength: 255
description: >-
Optionnel, mais requis si vous utilisez les
variables préremplies full_name ou last_name
email:
type: string
format: email
designation:
type: string
enum:
- Signer
- Approver
- CC
order:
type: integer
minimum: 1
phone_number:
type: string
street_address:
type: string
city:
type: string
state_province:
type: string
postal_code:
type: string
country:
type: string
title:
type: string
company:
type: string
- type: object
description: Mettre à jour ou créer un seul champ
required:
- field
properties:
field:
type: object
properties:
id:
type: string
format: uuid
description: >-
À inclure pour mettre à jour un champ existant, à
omettre pour en créer un nouveau
type:
type: string
enum:
- text
- signature
- date
- checkbox
- initial
- initials
- dropdown
- radio_buttons
- textarea
- text_area
- url
- file
- stamp
- approval_signature
- approval_checkmark
- approval_date
description: >-
Type de champ. Accepte 'initial' ou 'initials',
'textarea' ou 'text_area'. Requis pour les nouveaux
champs. Les champs url sont automatiquement en
lecture seule. Les champs file permettent aux
signataires de téléverser des pièces jointes
(images/PDF). Les champs stamp affichent une image
préconfigurée.
x:
type: number
description: >-
Position X sur le document. Requis pour les nouveaux
champs.
'y':
type: number
description: >-
Position Y sur le document. Requis pour les nouveaux
champs.
width:
type: number
description: Largeur du champ. Requis pour les nouveaux champs.
height:
type: number
description: Hauteur du champ. Requis pour les nouveaux champs.
page:
type: integer
minimum: 1
description: >-
Numéro de page (indexé à partir de 1). Requis pour
les nouveaux champs.
required:
type: boolean
description: Si le champ est obligatoire
assigned_to_user_id:
type: string
format: uuid
nullable: true
description: >-
ID de l'utilisateur du modèle auquel assigner le
champ
variable_name:
type: string
description: >-
Nom de variable pour le mapping des données
préremplies
variable_defined_name:
type: string
maxLength: 100
nullable: true
description: >-
Nom de définition de champ personnalisé, lisible par
un humain. Peut être utilisé comme alternative à
variable_name pour cibler des champs lors de la
création basée sur un modèle.
options:
type: array
items:
type: string
description: Options pour les champs de type liste déroulante
format_rules:
type: object
description: >-
Règles de format (par ex. format de date,
urlDisplayText pour les champs url,
acceptedFileTypes pour les champs file)
multi_group_id:
type: string
format: uuid
description: ID de groupe pour les groupes de boutons radio
default_to_signing_date:
type: boolean
description: >-
Pour les champs de type date, utilise la date de
signature par défaut
read_only:
type: boolean
description: >-
Si le champ est en lecture seule (automatiquement
vrai pour les champs url)
read_only_value:
type: string
description: >-
Valeur statique pour les champs en lecture seule.
Pour les champs url, il s'agit de l'URL vers
laquelle pointer.
documents_layout_version:
type: integer
minimum: 0
description: >-
Le `documents_layout_version` de votre dernière lecture
(multi-documents). Obligatoire pour écrire un champ sur
un modèle comportant plus d'un document ou une version
de mise en page supérieure à 1 (`409
DOCUMENTS_LAYOUT_VERSION_REQUIRED`) ; une valeur
obsolète répond `409 DOCUMENT_SET_VERSION_CONFLICT` ;
une valeur qui n'est pas un entier positif ou nul répond
`400 VALIDATION_ERROR` avec la clé
`documents_layout_version`.
- type: object
required:
- seal_participant
description: >-
Échange ou affecte un participant de cachet sur une demande
de signature envoyée. L'objet seal_participant identifie
l'emplacement du participant et le cachet cible à appliquer.
properties:
seal_participant:
type: object
required:
- participant_id
- swap_to_seal_id
description: >-
Échange de participant de cachet. Remplace le cachet
affecté à un emplacement de participant par un cachet
différent.
properties:
participant_id:
type: string
format: uuid
description: >-
ID de l'emplacement de participant de cachet à
mettre à jour
swap_to_seal_id:
type: string
format: uuid
description: >-
ID du nouveau cachet d'organisation à affecter à
l'emplacement
examples:
update-properties:
summary: Mettre à jour les propriétés
value:
name: Updated Template Name
expiration_hours: 72
create-url-field:
summary: Créer un champ URL
value:
field:
type: url
x: 100
'y': 200
width: 150
height: 30
page: 1
read_only_value: https://example.com/terms
format_rules:
urlDisplayText: View Terms & Conditions
create-file-field:
summary: Créer un champ de téléversement de fichier
value:
field:
type: file
x: 100
'y': 300
width: 200
height: 40
page: 1
required: true
format_rules:
acceptedFileTypes: image_and_pdf
update-field:
summary: Mettre à jour un champ existant
value:
field:
id: field123-e89b-12d3-a456-426614174000
x: 120
'y': 220
responses:
'200':
description: Modèle partiellement mis à jour avec succès
headers:
X-RateLimit-Limit:
schema:
type: integer
description: 'Limite de taux : 120 requêtes par minute'
X-RateLimit-Remaining:
schema:
type: integer
X-RateLimit-Reset:
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/TemplatePatchResponse'
'400':
description: >-
Requête Incorrecte - Échec de la validation. Multi-documents :
`PAGE_COUNT_MISMATCH`, `DIMENSION_MISMATCH` (remplacement de
document). Écritures de champs multi-documents : `VALIDATION_ERROR`
avec la clé `page` (une page au-delà du nombre de pages du document)
ou `documents_layout_version`
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Validation Error
message: Invalid input data
details:
name: Name is required
email: Invalid email format
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
description: Modèle ou participant de cachet introuvable
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
not_found:
value:
error: Template not found
code: NOT_FOUND
seal_not_found:
value:
error: >-
Organization seal not found or unavailable in this
workspace
code: NOT_FOUND
'409':
description: >-
Conflit : `MULTI_DOCUMENT_READ_ONLY`,
`MULTI_DOCUMENT_REPLACE_UNSUPPORTED`,
`DOCUMENT_SET_VERSION_CONFLICT`, `DOCUMENT_SET_BUSY`,
`DOCUMENT_SET_DISPATCH_STALE`, `DOCUMENT_CANDIDATE_EXPIRED`,
`DOCUMENT_SET_INCONSISTENT`, `DOCUMENTS_LAYOUT_VERSION_REQUIRED`
content:
application/json:
schema:
$ref: '#/components/schemas/MultiDocumentError'
'429':
$ref: '#/components/responses/RateLimitError'
security:
- ApiKeyAuth: []
x-codeSamples:
- lang: TypeScript
label: '@firma-dev/sdk'
source: |-
import { FirmaClient } from "@firma-dev/sdk";
const firma = new FirmaClient({ apiKey: "YOUR_API_KEY" });
const response = await firma.templates.patchTemplate({
id: "id",
body: {
name: "Updated Template Name",
expiration_hours: 72
}
});
console.log(response);
components:
schemas:
TemplatePatchResponse:
type: object
properties:
message:
type: string
updated_fields:
type: array
items:
type: string
description: Retourné lors de la mise à jour des propriétés
user:
type: object
description: Retourné lors de la mise à jour/création d'un utilisateur
description: Résultat de la mise à jour partielle du modèle
required:
- message
- updated_fields
Error:
type: object
properties:
error:
type: string
description: Message d'erreur lisible par un humain
code:
type: string
description: >-
Code d'erreur lisible par machine. Codes liés aux cachets :
SEALS_DISABLED, SEAL_ALREADY_REVOKED, SEAL_CREATION_DISABLED_EDGE,
SEAL_ERASE_NOT_ELIGIBLE, SEAL_IMAGE_INVALID,
SEAL_MUTATION_NOT_ALLOWED, SEAL_NOT_FOUND, SEAL_ORDER_COLLISION,
SEAL_PAUSED, SEAL_SCOPE_FORBIDDEN, SEAL_UNAVAILABLE Codes
multi-documents : voir MultiDocumentErrorCode (41 codes).
errors:
type: array
description: >-
Toutes les erreurs de validation lorsque plusieurs échecs sont
signalés ensemble. L'erreur de premier niveau répète le premier
élément pour la rétrocompatibilité.
items:
type: object
required:
- message
properties:
message:
type: string
message:
type: string
description: Description détaillée de l'erreur
details:
type: object
description: Détails d'erreur supplémentaires
additionalProperties: true
required:
- error
description: >-
Codes d'erreur des cachets d'organisation : SEALS_DISABLED,
SEAL_ALREADY_REVOKED, SEAL_CREATION_DISABLED_EDGE,
SEAL_ERASE_NOT_ELIGIBLE, SEAL_IMAGE_INVALID, SEAL_MUTATION_NOT_ALLOWED,
SEAL_NOT_FOUND, SEAL_ORDER_COLLISION, SEAL_PAUSED, SEAL_SCOPE_FORBIDDEN,
SEAL_UNAVAILABLE
MultiDocumentError:
description: Une erreur renvoyée par une route multi-documents.
allOf:
- $ref: '#/components/schemas/Error'
- type: object
required:
- error
- code
properties:
code:
$ref: '#/components/schemas/MultiDocumentErrorCode'
MultiDocumentErrorCode:
type: string
enum:
- ALREADY_CANCELLED
- ALREADY_FINISHED
- ALREADY_SENT
- ANCHOR_DOCUMENT_REQUIRED
- ANCHOR_MISMATCH
- CONFLICTING_DOCUMENT_SOURCE
- DIMENSION_MISMATCH
- DOCUMENTS_LAYOUT_VERSION_REQUIRED
- DOCUMENT_CANDIDATE_EXPIRED
- DOCUMENT_NOT_FOUND
- DOCUMENT_ORIGINAL_NOT_AVAILABLE
- DOCUMENT_SET_BUSY
- DOCUMENT_SET_DISPATCH_STALE
- DOCUMENT_SET_INCONSISTENT
- DOCUMENT_SET_LOCKED
- DOCUMENT_SET_TOO_LARGE
- DOCUMENT_SET_VERSION_CONFLICT
- DOCUMENT_SIGNED_NOT_AVAILABLE
- DOCUMENT_UPLOAD_NOT_FOUND
- DUPLICATE_DOCUMENT_ID
- FENCE_COLUMN_PROTECTED
- INSUFFICIENT_CREDITS
- INTERNAL
- INTERNAL_ERROR
- INVALID_DOCUMENT_ORDER
- INVALID_SIGNING_ORDER
- MAX_DOCUMENTS_EXCEEDED
- MIN_DOCUMENTS_REQUIRED
- MULTI_DOCUMENT_READ_ONLY
- MULTI_DOCUMENT_REPLACE_UNSUPPORTED
- NOT_FOUND
- PAGE_COUNT_MISMATCH
- PARTICIPANTS_CHANGED
- RATE_LIMIT_EXCEEDED
- SEAL_MUTATION_NOT_ALLOWED
- SEND_EFFECTS_EXIST
- SEND_IN_PROGRESS
- SIGNED_DATA_IMMUTABLE
- SIGNING_ORDER_LOCKED_APPLIED
- SIGNING_ORDER_LOCKED_SENDING
- SIGNING_ORDER_LOCKED_SENT
- VALIDATION_ERROR
description: >-
Codes d'erreur du contrat multi-documents et des routes qu'il modifie
(générés à partir des lignes de la matrice d'erreurs exposées par
l'API). Une véritable erreur serveur répond 500 avec INTERNAL_ERROR sur
les routes historiques et INTERNAL sur les chemins HttpError partagés
(répartition multi-documents, table des statuts RPC, routes de
l'ensemble de documents) ; aucun des deux ne contient de détail.
responses:
UnauthorizedError:
description: Non Autorisé - Clé API invalide ou manquante
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Unauthorized
message: Invalid API key
RateLimitError:
description: Trop de requêtes - Limite de débit dépassée
headers:
X-RateLimit-Limit:
schema:
type: integer
description: Nombre maximum de requêtes par minute
X-RateLimit-Remaining:
schema:
type: integer
description: Requêtes restantes
X-RateLimit-Reset:
schema:
type: integer
description: Timestamp Unix de la réinitialisation
Retry-After:
schema:
type: integer
description: Secondes avant de pouvoir réessayer
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Rate Limit Exceeded
message: Too many requests. Please wait before retrying.
details:
retry_after: 45
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Authorization
description: >-
Clé API pour l'authentification. Utilisez votre clé API directement sans
préfixe (par exemple, 'your-api-key'). Le préfixe Bearer est optionnel
mais pas obligatoire.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.